تحميل Maps JavaScript API

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

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

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

توفّر ميزة "الاستيراد الديناميكي للمكتبات" إمكانية تحميل المكتبات في وقت التشغيل. يتيح لك ذلك طلب المكتبات المطلوبة في الوقت الذي تحتاج إليها فيه، بدلاً من طلبها كلها مرة واحدة في وقت التحميل. كما تحمي هذه الميزة صفحتك من تحميل Maps JavaScript API عدة مرات.

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

عندما يحتاج تطبيقك إلى مكتبات متعددة في الوقت نفسه، استخدِم Promise.all() لطلبها بالتوازي:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

تجنَّب استدعاء await google.maps.importLibrary() على أسطر منفصلة بالتسلسل. تؤدي عبارات await المتسلسلة إلى حظر التنفيذ إلى أن ينتهي تنزيل كل مكتبة وتهيئتها قبل طلب المكتبة التالية، ما يؤدي إلى إنشاء سلسلة من طلبات الشبكة التي تزيد من وقت التحميل. تبدأ Promise.all() جميع عمليات تنزيل المكتبات في الوقت نفسه ويتم تنفيذها بمجرد أن تصبح جميعها جاهزة.

يمكن أن تحمّل دالتك أيضًا المكتبات بدون تعريف متغيّر للفئات المطلوبة، وهو أمر مفيد بشكل خاص إذا أضفت خريطة باستخدام عنصر gmp-map. بدون المتغيّر، يجب استخدام مسارات مؤهَّلة، مثل google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    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" في Cloud Console لتحديد عناوين URL المسموح لها باستخدام مفتاح واجهة برمجة تطبيقات معيّن. يمكن ضبط هذه القيود تلقائيًا للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة تطبيقات. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط authReferrerPolicy: "origin" للحدّ من مقدار البيانات المرسَلة عند منح الإذن للطلبات من Maps JavaScript API. عند تحديد هذه المَعلمة وتفعيل "قيود المحيل في HTTP" على Cloud Console، لن يتمكّن Maps JavaScript API من التحميل إلا إذا كان هناك قيد المحيل في HTTP يطابق نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.

• 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>

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

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

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

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

استخدِم هذه المَعلمات لطلب إصدار معيّن من 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: يمكنك الاطّلاع على تتبُّع الاستخدام حسب القناة.

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

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

تستخدم أداة التحميل الوعود لإتاحة المكتبات. يمكنك تحميل المكتبات باستخدام طريقة 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();

تحميل مكتبات متعددة

لتحميل أكثر من مكتبة واحدة، استخدِم Promise.all() لطلب المكتبات بالتوازي وفكّ بنية الفئات التي تم إرجاعها:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

لا تحمّل المكتبات بالتسلسل عن طريق ربط عبارات await منفصلة:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

عندما تستخدِم await لكل استدعاء importLibrary() واحدًا تلو الآخر، لا يبدأ طلب المكتبة الثانية إلا بعد أن يتم تنزيل المكتبة الأولى وتهيئتها بالكامل. يؤدي استخدام Promise.all() إلى بدء جميع طلبات المكتبات في الوقت نفسه، ما يقلّل من وقت استجابة الشبكة ويحسّن سرعة التهيئة.