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

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

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

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

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

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

<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>

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

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

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();
index.ts

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();
index.js

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

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

initMap();

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

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

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

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

• key: مفتاح واجهة برمجة التطبيقات. لن يتم تحميل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

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

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

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

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

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

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

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

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

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

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

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

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

لتحميل واجهة برمجة تطبيقات JavaScript للخرائط بشكل مضمّن في ملف HTML، أضف علامة script كما هو موضّح أدناه.

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

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

يناقش هذا القسم جميع المعلمات التي يمكنك تحديدها في طلب البحث سلسلة من عنوان URL لتحميل النص البرمجي عند تحميل واجهة برمجة تطبيقات JavaScript للخرائط. تكون بعض المعلمات مطلوبة بينما البعض الآخر اختياريًا. كما هو قياسي في عناوين 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>

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

تكون المَعلمات التالية مطلوبة عند تحميل واجهة برمجة التطبيقات Maps JavaScript API.

• key: مفتاح واجهة برمجة التطبيقات. تشير رسالة الأشكال البيانية لن يتم تحميل واجهة برمجة تطبيقات JavaScript للخرائط ما لم يتم استخدام مفتاح صالح لواجهة برمجة التطبيقات المحددة.

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

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

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

• callback: اسم الدالة العمومية التي سيتم طلبها بعد واجهة برمجة تطبيقات JavaScript للخرائط بالكامل.

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

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

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

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

• auth_referrer_policy: يمكن للعملاء ضبط مُحيل HTTP القيود في Cloud Console لتحديد عناوين URL المسموح لها باستخدام مفتاح واجهة برمجة تطبيقات معين. بشكل تلقائي، يمكن ضبط هذه القيود للسماح مسارات معينة فقط لاستخدام مفتاح واجهة برمجة التطبيقات. إذا كان هناك أي عنوان URL في النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط auth_referrer_policy=origin لتقييد مقدار البيانات المرسلة عند منح الإذن بالطلبات من واجهة برمجة تطبيقات JavaScript للخرائط. تتوفر هذه الميزة بدءًا من الإصدار 3.46. عند تحديد هذه المَعلمة وتفعيل قيود مُحيل HTTP في Cloud Console، لن تتمكّن واجهة برمجة التطبيقات JavaScript لـ "خرائط Google" من التحميل إلا إذا كان هناك قيد مُحيل 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().

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,
  });
});
index.ts

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,
  });
});
index.js

الاطّلاع على نموذج يعرض js-api-loader

يوضّح المثال التالي استخدام 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
});

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

يتناول هذا القسم الخطوات المطلوبة لنقل بيانات الدمج لاستخدامها. واجهة برمجة التطبيقات لاستيراد المكتبة الديناميكية.

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

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

قبل

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