تحميل واجهة برمجة تطبيقات JavaScript للخرائط

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

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

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

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

إذا أضفت خريطة باستخدام العنصر gmp-map، يمكن للدالة initMap() تحميل المكتبات بدون الإعلان عن متغيّر للفئات المطلوبة:

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

initMap();

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

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

تعرَّف على كيفية نقل البيانات إلى واجهة برمجة التطبيقات الديناميكية لتحميل المكتبة.

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

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

  • v: إصدار من Maps JavaScript API المطلوب تحميله.

  • libraries: قائمة مفصولة بفواصل تتضمّن مكتبات واجهة برمجة تطبيقات JavaScript الإضافية المطلوب تحميلها. لا يُنصح عمومًا بتحديد مجموعة ثابتة من المكتبات، ولكنّ هذه الميزة متاحة للمطوّرين الذين يريدون تحسين سلوك التخزين المؤقت على مواقعهم الإلكترونية.

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

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

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

  • mapIds: مصفوفة من معرّفات الخرائط يؤدي إلى تحميل مُعرفات الخريطة المحددة مسبقًا.

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

  • solutionChannel: توفر "منصة خرائط Google" أنواعًا عديدة من الرموز النموذجية لمساعدتك في بدء العمل بسرعة. لتتبُّع استخدام عيّنات التعليمات البرمجية الأكثر تعقيدًا وتحسين جودة الحلول، ضمّنت Google مَعلمة طلب البحث solutionChannel في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز البرمجي الخاص بنا.

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

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

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

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

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

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

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

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

  • v: إصدار واجهة برمجة تطبيقات JavaScript للخرائط المطلوب استخدامه.

  • libraries: قائمة مفصولة بفواصل تتضمّن مكتبات واجهة برمجة تطبيقات JavaScript الإضافية المطلوب تحميلها.

  • 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 يطابق نطاق الموقع الإلكتروني الحالي بدون مسار محدد.

  • mapIds: قائمة بمعرّفات الخرائط مفصولة بفواصل. يؤدي إلى تحميل مُعرفات الخريطة المحددة مسبقًا.

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

  • solution_channel: توفر "منصة خرائط Google" أنواعًا عديدة من الرموز النموذجية لمساعدتك في بدء العمل بسرعة. لتتبُّع استخدام عيّنات التعليمات البرمجية الأكثر تعقيدًا وتحسين جودة الحلول، ضمّنت Google مَعلمة طلب البحث solution_channel في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز البرمجي الخاص بنا.

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

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

npm install @googlemaps/js-api-loader

يمكن استيراد هذه الحزمة إلى التطبيق باستخدام:

import { Loader } from "@googlemaps/js-api-loader"

يعرض برنامج التحميل واجهة الموعد وواجهة معاودة الاتصال. يوضح ما يلي استخدام طريقة Promise التلقائية load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

الاطّلاع على نموذج يعرض أداة تحميل js-api-load

يوضّح المثال التالي استخدام loader.importLibrary() لتحميل المكتبات:

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

نقل البيانات إلى واجهة برمجة التطبيقات "استيراد المكتبة الديناميكية"

يتناول هذا القسم الخطوات المطلوبة لنقل عملية الدمج لاستخدام واجهة برمجة التطبيقات Dynamic LibraryImport API.

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

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

قبل

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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();