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

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

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

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

يمكنك تحميل 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();
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

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

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

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

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

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

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

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

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

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

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

تتوفّر الحزمة @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.

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

لا تزال علامة تحميل النص البرمجي القديمة متاحة. تم توفير هذا القسم لدعم عمليات الدمج باستخدام علامة تحميل النص البرمجي القديمة. ينصح محرّك بحث Google بالانتقال إلى واجهة برمجة التطبيقات الديناميكية لتحميل المكتبة.

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

لتحميل Maps JavaScript API بشكل مضمّن في ملف HTML، أضِف علامة script كما هو موضّح أدناه.

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

معلمات عنوان URL لتحميل النص البرمجي القديم

يناقش هذا القسم جميع المعلَمات التي يمكنك تحديدها في سلسلة طلب البحث للنص البرمجي الذي يتم تحميله لعنوان URL عند تحميل Maps JavaScript API. بعض المعلمات مطلوبة والبعض الآخر اختيارية. وكما هو الحال في عناوين URL، يتم فصل جميع المعلمات باستخدام حرف العطف (&).

يتضمن المثال التالي لعنوان URL عناصر نائبة لكل المعلمات المحتملة:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

يعمل عنوان URL في العلامة script في المثال التالي على تحميل واجهة برمجة التطبيقات JavaScript JavaScript للخرائط:

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

المَعلمات المطلوبة (قديمة)

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

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

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

المَعلمات الاختيارية (قديمة)

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

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

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

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

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

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

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

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

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

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

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

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

قبل

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