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

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

<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: استراتيجية تحميل الرمز التي يمكن أن تستخدمها واجهة برمجة تطبيقات JavaScript لـ "خرائط Google". اضبط القيمة على async للإشارة إلى أنّه لم يتم تحميل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" بشكل متزامن وأنّه لم يتم تشغيل أي رمز JavaScript من خلال حدث load للنص البرمجي. يُنصح بشدة بضبط هذه القيمة على async كلما أمكن ذلك لتحسين الأداء. (استخدِم المَعلمة callback بدلاً من ذلك لتنفيذ إجراءات عندما تكون واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" متاحة). تتوفّر هذه المَعلمة بدءًا من الإصدار 3.55.

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

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

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

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

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

• auth_referrer_policy: يمكن للعملاء ضبط قيود برنامج الإحالة الناجحة عبر HTTP في Cloud Console للحدّ من عناوين URL المسموح لها باستخدام مفتاح API معيّن. وبشكل تلقائي، يمكن ضبط هذه القيود للسماح لمسارات معيّنة فقط باستخدام مفتاح API. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح API، يمكنك ضبط 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 = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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 = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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