تحميل Maps JavaScript API

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

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

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

يتيح استيراد المكتبات الديناميكية إمكانية تحميل المكتبات في وقت التشغيل. يتيح لك ذلك طلب المكتبات المطلوبة في الوقت الذي تحتاج إليها فيه، بدلاً من طلبها كلها مرة واحدة في وقت التحميل. وتحمي صفحتك أيضًا من تحميل 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 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 في المثال التالي إلى تحميل واجهة برمجة التطبيقات Maps JavaScript API:

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

المَعلمات المطلوبة (مباشرة)

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

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

المَعلمات الاختيارية (مباشرة)

استخدِم هذه المَعلمات لطلب إصدار معيّن من 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() إلى بدء جميع طلبات المكتبة في الوقت نفسه، ما يقلّل من وقت استجابة الشبكة ويحسّن سرعة الإعداد.