سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط Google". يتضمن هذا التحديث على تصميم الخريطة لوحة ألوان تلقائية جديدة وتحسينات على تجارب الخرائط وسهولة الاستخدام. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. للمزيد من المعلومات عن مدى التوفّر وكيفية تفعيل الميزة في وقت سابق، يُرجى الاطّلاع على نمط الخريطة الجديد في "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يوضِّح لك هذا الدليل كيفية تحميل "واجهة برمجة تطبيقات 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.>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

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

إذا أضفت خريطة باستخدام العنصر gmp-map، ستتمكن الدالة initMap() من تحميل المكتبات بدون تحديد متغيّر للفئات المطلوبة:

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: إصدار واجهة برمجة تطبيقات JavaScript للخرائط المطلوب تحميلها.
libraries: قائمة مفصولة بفواصل لمكتبات واجهة برمجة تطبيقات JavaScript الإضافية لتحميلها. ولا يُنصح عمومًا بتحديد مجموعة ثابتة من المكتبات، ولكنّه متاح للمطوّرين الذين يريدون ضبط سلوك التخزين المؤقت على مواقعهم الإلكترونية.
language: اللغة المطلوب استخدامها. يؤثر هذا في أسماء عناصر التحكم وإشعارات حقوق الطبع والنشر واتجاهات القيادة وتصنيفات عناصر التحكم والاستجابة لطلبات الخدمة. اطّلِع على قائمة اللغات المتاحة.
region: رمز المنطقة المطلوب استخدامه. يؤدي هذا إلى تغيير سلوك الخريطة بناءً على بلد أو إقليم معين.
authReferrerPolicy: يمكن لعملاء JavaScript (JS) تطبيق "خرائط Google" ضبط "قيود مُحيل HTTP" في Cloud Console لتحديد عناوين URL المسموح لها باستخدام مفتاح معيّن لواجهة برمجة التطبيقات. بشكل تلقائي، يمكن ضبط هذه القيود للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة التطبيقات. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط authReferrerPolicy: "origin" للحدّ من كمية البيانات المُرسَلة عند منح الإذن بالطلبات من Maps JavaScript API. عند تحديد هذه المَعلمة وتفعيل "قيود مُحيل HTTP" على Cloud Console، لن تتمكّن واجهة Maps JavaScript API من التحميل إلا في حال توفّر قيود على مُحيل HTTP تطابق نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.
mapIds: مصفوفة من معرّفات الخرائط. يؤدي ذلك إلى تحميل إعداد معرّفات الخريطة المحددة مسبقًا.
channel: راجِع تتبُّع الاستخدام لكل قناة.
solutionChannel: توفّر "منصة خرائط Google" أنواعًا عديدة من الرموز البرمجية لمساعدتك في بدء عملية النقل بسرعة. ولتتبُّع اعتماد نماذج الرموز الأكثر تعقيدًا وتحسين جودة الحلول، يُدرج محرّك بحث Google معلَمة طلب البحث solutionChannel في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز البرمجي.

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

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

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

لتحميل واجهة برمجة التطبيقات 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 الذي يحمل النص البرمجي عند تحميل واجهة برمجة تطبيقات 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"
&region="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.55
callback: اسم دالة عمومية سيتم استدعاؤها بعد تحميل واجهة برمجة تطبيقات JavaScript للخرائط بشكل كامل.
v: إصدار واجهة برمجة تطبيقات JavaScript للخرائط المستخدَمة.
libraries: قائمة مفصولة بفواصل لمكتبات واجهة برمجة تطبيقات JavaScript الإضافية لتحميلها.
language: اللغة المطلوب استخدامها. ويؤثر هذا في أسماء عناصر التحكم وإشعارات حقوق الطبع والنشر واتجاهات القيادة وتصنيفات عناصر التحكم، بالإضافة إلى الاستجابات لطلبات الخدمة. اطّلِع على قائمة اللغات المتاحة.
region: رمز المنطقة المطلوب استخدامه. يؤدي هذا إلى تغيير سلوك الخريطة بناءً على بلد أو إقليم معين.
auth_referrer_policy: يمكن للعملاء ضبط "قيود مُحيل HTTP" في Cloud Console لتحديد عناوين URL المسموح لها باستخدام مفتاح معيّن لواجهة برمجة التطبيقات. بشكل تلقائي، يمكن ضبط هذه القيود للسماح لمسارات معيّنة فقط باستخدام مفتاح واجهة برمجة التطبيقات. إذا كان بإمكان أي عنوان URL على النطاق أو المصدر نفسه استخدام مفتاح واجهة برمجة التطبيقات، يمكنك ضبط auth_referrer_policy=origin للحدّ من كمية البيانات المُرسَلة عند منح الإذن بالطلبات من Maps JavaScript API. تتوفر هذه الميزة بدءًا من الإصدار 3.46. عند تحديد هذه المَعلمة وتفعيل "قيود مُحيل HTTP" على Cloud Console، لن تتمكّن واجهة برمجة تطبيقات JavaScript للخرائط من التحميل إلا في حال توفُّر قيد على مُحيل HTTP يطابق نطاق الموقع الإلكتروني الحالي بدون تحديد مسار.
mapIds: قائمة بمعرّفات الخريطة مفصولة بفواصل. يؤدي ذلك إلى تحميل إعداد معرّفات الخريطة المحددة مسبقًا.
channel: راجِع تتبُّع الاستخدام لكل قناة.
solution_channel: توفّر "منصة خرائط Google" أنواعًا عديدة من الرموز البرمجية لمساعدتك في بدء عملية النقل بسرعة. ولتتبُّع اعتماد نماذج الرموز الأكثر تعقيدًا وتحسين جودة الحلول، يُدرج محرّك بحث Google معلَمة طلب البحث solution_channel في طلبات البيانات من واجهة برمجة التطبيقات في نموذج الرمز البرمجي.

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

استخدام حزمة 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

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.

يوضّح المثال التالي استخدام 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.>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();