يوضِّح لك هذا الدليل كيفية تحميل "واجهة برمجة تطبيقات 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();
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();
يمكن للدالة أيضًا تحميل المكتبات بدون الإعلان عن المتغير
للفئات المطلوبة، وهو أمر مفيد بشكل خاص إذا أضفت خريطة باستخدام
العنصر 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
عن طريق إلغاء الحاجة إلى طلب المكتبات بشكل صريح
وقت التشغيل. نظرًا لأن علامة تحميل النص البرمجي المباشر تُحمّل جميع المكتبات المطلوبة في
عندما يتم تحميل النص البرمجي، قد يتأثر الأداء عند بعض
التطبيقات. ضمِّن علامة تحميل النص البرمجي المباشر مرة واحدة فقط لكل تحميل صفحة.
إضافة علامة نص برمجي
لتحميل واجهة برمجة تطبيقات 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"
®ion="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.55callback
: اسم الدالة العمومية التي سيتم طلبها بعد واجهة برمجة تطبيقات 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
في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز.
استخدام حزمة 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, }); });
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, }); });
اطّلِع على نموذج يعرض 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();