تحميل Maps JavaScript API

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

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

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

يتيح استيراد المكتبات الديناميكية إمكانية تحميل المكتبات في وقت التشغيل. يتيح لك ذلك طلب المكتبات المطلوبة عند الحاجة إليها، بدلاً من طلبها كلها مرة واحدة عند مدّة التحميل. وتحمي هذه الميزة صفحتك أيضًا من تحميل واجهة برمجة تطبيقات 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>

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

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

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
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 بمفتاح واجهة برمجة التطبيقات. لن يتم تحميل Maps JavaScript API ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

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

• استبدِل v بالإصدار من Maps JavaScript API الذي تريد تحميله. إذا لم تحدّد قناة أو إصدارًا بشكلٍ صريح، ستتلقّى القناة الأسبوعية تلقائيًا. إذا نقلت بياناتك من الخطة المدفوعة ولم تحدّد قناة أو إصدارًا بشكل صريح، ستتلقّى القناة الربع سنوية تلقائيًا. إذا حدّدت إصدارًا غير صالح، ستتلقّى القناة التلقائية. مزيد من المعلومات

• ‫libraries: مصفوفة من المكتبات الإضافية في Maps JavaScript API التي سيتم البدء في التحميل المُسبَق لها. لا ننصح بشكل عام بتحديد مجموعة ثابتة من المكتبات، ولكن هذا الخيار متاح للمطوّرين الذين يريدون ضبط سلوك التخزين المؤقت بدقة على مواقعهم الإلكترونية. سيظل من المهم استدعاء google.maps.importLibrary() لكل مكتبة تم اختيارها قبل استخدامها.

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

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

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

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

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

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

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

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

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

المَعلمات المطلوبة (مباشرة) {:.hide-from-toc}

يجب توفير المَعلمات التالية عند تحميل Maps JavaScript API.

• استبدِل key بمفتاح واجهة برمجة التطبيقات. لن يتم تحميل Maps JavaScript API ما لم يتم تحديد مفتاح صالح لواجهة برمجة التطبيقات.

المَعلمات الاختيارية (مباشرة) {:.hide-from-toc}

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

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

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

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

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

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

npm install @googlemaps/js-api-loader

استورِد الحزمة كما هو موضّح هنا:

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

يستخدم برنامج التحميل Promises لإتاحة المكتبات. حمِّل المكتبات باستخدام الطريقة importLibrary(). يوضّح المثال التالي كيفية استخدام أداة التحميل لتحميل خريطة:

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

الاطّلاع على مثال الرمز الكامل

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