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

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

• استخدام استيراد مكتبة ديناميكية
• استخدِم علامة تحميل النص البرمجي المباشر.
• استخدام حزمة 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>

يمكنك أيضًا إضافة رمز برنامج الإقلاع مباشرةً إلى رمز JavaScript.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لتحميل واجهة برمجة تطبيقات 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 للخرائط:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدام حزمة 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,
  });
});
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
});

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

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

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

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

قبل

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