تحميل Maps JavaScript API

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

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

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

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

حمِّل 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>

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

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

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. بدون المتغيّر، يجب استخدام مسارات مؤهَّلة، مثل 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 بمفتاح واجهة برمجة التطبيقات. لن يتم تحميل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  ملاحظة: مَعلمة طلب البحث هذه مخصّصة للاستخدام من قِبل Google. يمكنك الاطّلاع على مَعلمة حلول "منصة خرائط Google" لمزيد من المعلومات.

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

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

npm install @googlemaps/js-api-loader

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

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

يعرض برنامج التحميل واجهة Promise وواجهة ردّ الاتصال. يوضّح المثال التالي كيفية استخدام طريقة 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,
  });
});
index.ts

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

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

نقل البيانات إلى 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();