تحميل Maps JavaScript API

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

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

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

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

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

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

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

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

لتحميل Google 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>

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

تكون المَعلمات التالية مطلوبة عند تحميل واجهة برمجة التطبيقات JavaScript لـ "خرائط Google".

• 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: الإصدار من واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" المطلوب استخدامه.

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

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

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

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