تحميل Maps JavaScript API

يشرح هذا الدليل كيفية تحميل Maps JavaScript API. هناك ثلاث طرق للقيام بذلك:

• استخدام ميزة "الاستيراد الديناميكي للمكتبات"
• استخدام علامة تحميل النص البرمجي المباشر
• استخدام حزمة js-api-loader في NPM

استخدام ميزة "الاستيراد الديناميكي للمكتبات"

توفّر ميزة "الاستيراد الديناميكي للمكتبات" إمكانية تحميل المكتبات في وقت التشغيل. ويتيح لك ذلك طلب المكتبات المطلوبة في الوقت الذي تحتاج إليها فيه، بدلاً من طلبها كلها مرة واحدة في مدّة التحميل. كما تحمي هذه الميزة صفحتك من تحميل Maps JavaScript API عدة مرات.

يمكنك تحميل Maps JavaScript API عن طريق إضافة عامل تحميل التمهيد المضمّن إلى الرمز البرمجي لتطبيقك، كما هو موضّح في المقتطف التالي:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

يمكنك أيضًا إضافة رمز أداة تحميل التمهيد مباشرةً إلى رمز JavaScript.

لتحميل المكتبات في وقت التشغيل، استخدِم عامل التشغيل await لاستدعاء importLibrary() من داخل دالة async. يسمح لك تعريف متغيرات للفئات المطلوبة بتخطّي استخدام مسار مؤهَّل (مثل google.maps.Map)، كما هو موضّح في مثال الرمز التالي:

async function initMap() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');
    // Create the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;
}
initMap();
index.js

يمكن أن تحمّل دالتك أيضًا المكتبات بدون تعريف متغيّر للفئات المطلوبة، وهو أمر مفيد بشكل خاص إذا أضفت خريطة باستخدام عنصر gmp-map. بدون المتغيّر، عليك استخدام مسارات مؤهَّلة، مثل google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

بدلاً من ذلك، يمكنك تحميل المكتبات مباشرةً في HTML كما هو موضّح هنا:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

تعرَّف على كيفية نقل البيانات إلى Dynamic Library Loading API.

المعلمات المطلوبة

• key: مفتاح واجهة برمجة التطبيقات. لن يتم تحميل Maps JavaScript API ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

المعلمات الاختيارية

• v: إصدار Maps JavaScript API الذي سيتم تحميله.

• libraries: مصفوفة من مكتبات Maps JavaScript API الإضافية التي سيتم البدء في تحميلها مسبقًا. لا يُنصح عمومًا بتحديد مجموعة ثابتة من المكتبات، ولكنها متاحة للمطوّرين الذين يريدون ضبط سلوك التخزين المؤقت على موقعهم الإلكتروني بدقة. يظل من المهم استدعاء google.maps.importLibrary() لكل مكتبة تم اختيارها قبل استخدامها.

• language: الـ لغة التي سيتم استخدامها. تؤثر هذه اللغة في أسماء عناصر التحكّم وإشعارات حقوق الطبع والنشر واتجاهات القيادة وتصنيفات عناصر التحكّم وردود طلبات الخدمة. يمكنك الاطّلاع على قائمة اللغات المتاحة.

• region: رمز المنطقة الذي سيتم استخدامه. يغيّر هذا الرمز سلوك واجهة برمجة التطبيقات استنادًا إلى بلد أو منطقة معيّنة.

• authReferrerPolicy: يمكن لعملاء Maps JS ضبط "قيود المحيل في HTTP" في Cloud Console للحدّ من عناوين URL المسموح لها باستخدام مفتاح واجهة برمجة تطبيقات معيّن. يمكن ضبط هذه القيود تلقائيًا للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة التطبيقات. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط authReferrerPolicy: "origin" للحدّ من مقدار البيانات المرسَلة عند منح الإذن للطلبات من Maps JavaScript API. عند تحديد هذه المَعلمة وتفعيل "قيود المحيل في HTTP" على Cloud Console، لن يتمكّن Maps JavaScript API من التحميل إلا إذا كان هناك قيد محيل في HTTP يطابق نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.

• mapIds: مصفوفة من أرقام تعريف الخرائط. يؤدي ذلك إلى تحميل إعدادات أرقام تعريف الخرائط المحدّدة مسبقًا. ليس من الضروري تحديد أرقام تعريف الخرائط هنا لاستخدامها، ولكنها متاحة للمطوّرين الذين يريدون ضبط أداء الشبكة بدقة.

• channel: يمكنك الاطّلاع على مقالة تتبُّع الاستخدام حسب القناة.

استخدام علامة تحميل النص البرمجي المباشر

يوضّح هذا القسم كيفية استخدام علامة تحميل النص البرمجي المباشر. بما أنّ النص البرمجي المباشر يحمّل المكتبات عند تحميل الخريطة، يمكنه تبسيط الخرائط التي تم إنشاؤها باستخدام عنصر gmp-map عن طريق إزالة الحاجة إلى طلب المكتبات بشكل صريح في وقت التشغيل. بما أنّ علامة تحميل النص البرمجي المباشر تحمّل جميع المكتبات المطلوبة مرة واحدة عند تحميل النص البرمجي، قد يتأثر الأداء في بعض التطبيقات. يجب تضمين علامة تحميل النص البرمجي المباشر مرة واحدة فقط لكل عملية تحميل صفحة.

إضافة علامة نص برمجي

لتحميل Maps JavaScript API مضمّنة في ملف HTML، أضِف علامة script كما هو موضّح أدناه.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

مَعلمات عنوان URL لتحميل النص البرمجي المباشر

يناقش هذا القسم جميع المَعلمات التي يمكنك تحديدها في سلسلة طلب البحث لعنوان URL لتحميل النص البرمجي عند تحميل Maps JavaScript API. بعض المَعلمات مطلوبة والبعض الآخر اختياري. كما هو معتاد في عناوين URL، يتم فصل جميع المَعلمات باستخدام علامة العطف (&).

يحتوي عنوان URL المثال التالي على عناصر نائبة لجميع المَعلمات الممكنة:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

يحمّل عنوان URL في علامة script المثال التالي Maps JavaScript API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

المعلمات المطلوبة (مباشرة) {:.hide-from-toc}

المَعلمات التالية مطلوبة عند تحميل Maps JavaScript API.

• key: مفتاح واجهة برمجة التطبيقات. لن يتم تحميل Maps JavaScript API ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

المعلمات الاختيارية (مباشرة) {:.hide-from-toc}

استخدِم هذه المَعلمات لطلب إصدار معيّن من Maps JavaScript API أو تحميل مكتبات إضافية أو تخصيص خريطتك أو تحديد سياسة التحقّق من المحيل في HTTP.

• loading: استراتيجية تحميل الرمز التي يمكن أن تستخدمها Maps JavaScript API. اضبط هذه المَعلمة على async للإشارة إلى أنّه لم يتم تحميل Maps JavaScript API بشكل متزامن وأنّه لم يتم تشغيل أي رمز JavaScript من خلال حدث load للنص البرمجي. يُنصح بشدة بضبط هذه المَعلمة على async كلما أمكن ذلك لتحسين الأداء. (استخدِم المَعلمة callback بدلاً من ذلك لتنفيذ الإجراءات عندما تتوفّر Maps JavaScript API.) تتوفّر هذه المَعلمة بدءًا من الإصدار 3.55.

• callback: اسم دالة عامة سيتم استدعاؤها بعد تحميل Maps JavaScript API بالكامل.

• v: إصدار Maps JavaScript API الذي سيتم استخدامه.

• libraries: قائمة قيم مفصولة بفاصلة من مكتبات Maps JavaScript API إضافية التي سيتم تحميلها.

• language: الـ لغة التي سيتم استخدامها. تؤثر هذه اللغة في أسماء عناصر التحكّم وإشعارات حقوق الطبع والنشر واتجاهات القيادة وتصنيفات عناصر التحكّم، بالإضافة إلى ردود طلبات الخدمة. يمكنك الاطّلاع على قائمة اللغات المتاحة.

• region: رمز المنطقة الذي سيتم استخدامه. يغيّر هذا الرمز سلوك واجهة برمجة التطبيقات استنادًا إلى بلد أو منطقة معيّنة.

• auth_referrer_policy: يمكن للعملاء ضبط "قيود المحيل في HTTP" في Cloud Console للحدّ من عناوين URL المسموح لها باستخدام مفتاح واجهة برمجة تطبيقات معيّن. يمكن ضبط هذه القيود تلقائيًا للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة التطبيقات. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط auth_referrer_policy=origin للحدّ من مقدار البيانات المرسَلة عند منح الإذن للطلبات من Maps JavaScript API. تتوفّر هذه المَعلمة بدءًا من الإصدار 3.46. عند تحديد هذه المَعلمة و تفعيل "قيود المحيل في HTTP" على Cloud Console، لن يتمكّن Maps JavaScript API من التحميل إلا إذا كان هناك "قيد محيل في HTTP" يطابق نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.

• map_ids: قائمة قيم مفصولة بفاصلة لأرقام تعريف الخرائط. يؤدي ذلك إلى تحميل إعدادات أرقام تعريف الخرائط المحدّدة مسبقًا. ليس من الضروري تحديد أرقام تعريف الخرائط هنا لاستخدامها، ولكنها متاحة للمطوّرين الذين يريدون ضبط أداء الشبكة بدقة.

• channel: يمكنك الاطّلاع على مقالة تتبُّع الاستخدام حسب القناة.

• internal_usage_attribution_ids: قائمة قيم مفصولة بفاصلة من أرقام تعريف إحالة الاستخدام التي تساعد Google في فهم المكتبات والنماذج المفيدة للمطوّرين، مثل استخدام مكتبة أداة تجميع محدّدات المواقع. لإيقاف إرسال رقم تعريف إحالة الاستخدام، يمكنك حذف هذه السمة أو استبدال القيمة بسلسلة فارغة. لن يتم إرسال سوى القيم الفريدة. لمزيد من المعلومات، يمكنك الاطّلاع على مَعلمة حلول "منصة خرائط Google".

استخدام حزمة js-api-loader في NPM

تتوفّر حزمة ‏@googlemaps/js-api-loader للتحميل باستخدام مدير حزم NPM. ثبِّتها باستخدام الأمر التالي:

npm install @googlemaps/js-api-loader

استورِد الحزمة كما هو موضّح هنا:

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

تستخدِم أداة التحميل الوعود لإتاحة المكتبات. يمكنك تحميل المكتبات باستخدام طريقة importLibrary(). يوضّح المثال التالي كيفية استخدام أداة التحميل لتحميل خريطة:

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function initMap(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });

    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));
    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };
    // Declare the map.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

يمكنك الاطّلاع على مثال الرمز الكامل.

نقل البيانات إلى Dynamic Library Import API

يغطّي هذا القسم الخطوات المطلوبة لنقل عملية الدمج لاستخدام Dynamic Library Import API.

خطوات نقل البيانات

أولاً، استبدِل علامة تحميل النص البرمجي المباشر بعلامة أداة تحميل التمهيد المضمّنة.

قبل

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

بعد

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

بعد ذلك، عدِّل الرمز البرمجي لتطبيقك:

• غيِّر دالة initMap() لتصبح غير متزامنة.
• استدعِ importLibrary() لتحميل المكتبات التي تحتاج إليها والوصول إليها.

قبل

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

بعد

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();