تحميل Maps JavaScript API

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

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

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

يتيح استيراد المكتبات الديناميكية إمكانية تحميل المكتبات في وقت التشغيل. يتيح لك ذلك طلب المكتبات المطلوبة عند الحاجة إليها، بدلاً من طلبها كلها مرة واحدة عند وقت التحميل. وتحمي صفحتك أيضًا من تحميل "واجهة برمجة تطبيقات JavaScript للخرائط" عدة مرات.

حمِّل 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 init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

عندما يحتاج تطبيقك إلى مكتبات متعددة في الوقت نفسه، استخدِم Promise.all() لطلبها بشكل متوازٍ:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

تجنَّب استدعاء await google.maps.importLibrary() في أسطر منفصلة بالتسلسل. تمنع عبارات await المتسلسلة التنفيذ إلى أن تنتهي كل مكتبة من التنزيل والتهيئة قبل طلب المكتبة التالية، ما يؤدي إلى إنشاء عرض انحداري لطلبات الشبكة يزيد من مدة التحميل. تبدأ الدالة Promise.all() جميع عمليات تنزيل المكتبات في الوقت نفسه ويتم حلّها فور أن تصبح جميعها جاهزة.

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

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

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    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 Referrer في Cloud Console للحدّ من عناوين URL المسموح لها باستخدام مفتاح واجهة برمجة التطبيقات معيّن. بشكل تلقائي، يمكن ضبط هذه القيود للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة التطبيقات. إذا كان أي عنوان URL على النطاق أو المصدر نفسهما يمكنه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط authReferrerPolicy: "origin" للحدّ من كمية البيانات التي يتم إرسالها عند منح الإذن للطلبات من Maps JavaScript API. عند تحديد هذه المَعلمة وتفعيل "قيود مُحيل HTTP" في Cloud Console، لن يتم تحميل Maps JavaScript API إلا إذا كان هناك قيد مُحيل HTTP يتطابق مع نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.

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

• ‫channel: راجِع تتبُّع الاستخدام لكل قناة.

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

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

ملاحظة: يمكنك استدعاء importLibrary بعد انتهاء تحميل علامة تحميل النص البرمجي المباشر.

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

لتحميل 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 في المثال التالي إلى تحميل واجهة برمجة التطبيقات JavaScript في "خرائط Google":

<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: يُرجى الاطّلاع على تتبُّع الاستخدام لكل قناة.

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

ملاحظة: الإصدار v2.0.0 هو إعادة هيكلة رئيسية تحلّ محلّ فئة Loader القديمة باستخدام واجهة برمجة تطبيقات تتألف من دالتَين، هما setOptions() وimportLibrary(). يتيح لك هذا التغيير تحميل مكتبات Maps API الفردية ديناميكيًا عند الطلب، ما يؤدي إلى تأجيل تنزيل الميزات لتحسين أداء الصفحة الأولي.

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

npm install @googlemaps/js-api-loader

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

TypeScript

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

ملاحظة: يُرجى الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

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

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

TypeScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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

    // 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.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

ملاحظة: يُرجى قراءة الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // 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.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
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();

تحميل مكتبات متعددة

لتحميل أكثر من مكتبة واحدة، استخدِم Promise.all() لطلب المكتبات بالتوازي، ثم قسِّم الفئات التي تم إرجاعها:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

لا تحمِّل المكتبات بشكل تسلسلي من خلال ربط عبارات await منفصلة:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

عندما await كل importLibrary() استدعاء واحدًا تلو الآخر، لن يبدأ طلب المكتبة الثاني إلا بعد اكتمال تنزيل المكتبة الأولى وتهيئتها. يؤدي استخدام Promise.all() إلى بدء جميع طلبات المكتبة في الوقت نفسه، ما يقلل من وقت استجابة الشبكة ويحسّن سرعة الإعداد.