إشعار الأمان: نما إلى علمنا بمشكلة أمنية قد تؤثر في المواقع الإلكترونية التي تستخدم مكتبات معيّنة تابعة لجهات خارجية (بما في ذلك polyfill.io). وقد تؤدي هذه المشكلة في بعض الأحيان إلى إعادة توجيه الزائرين بعيدًا عن الموقع الإلكتروني المقصود بدون معرفة مالك الموقع أو إذنه. وفي السابق، كان يتضمّن العديد من نماذج JavaScript تعريف النص البرمجي polyfill.io. تمت إزالة هذا المحتوى من نماذجنا. إذا كنت قد استخدمت نماذج JavaScript التي تحتوي على هذا التعريف، ننصحك بإزالة التعريف.

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

إضافة خريطة Google مع علامة باستخدام JavaScript

مقدمة

يشرح لك هذا البرنامج التعليمي كيفية إضافة خريطة Google بسيطة باستخدام محدِّد إلى صفحة ويب. وهي تناسب الأشخاص الذين لديهم معرفة مبتدئة أو متوسطة بـ HTML وCSS، ويعرفون القليل عن JavaScript.

فيما يلي الخريطة التي ستنشئها باستخدام هذا البرنامج التعليمي. يتم وضع العلامة في موقع أولورو (المعروف أيضًا باسم صخرة آيرز) في حديقة أولورو - كاتا تجوتا الوطنية.

الخطوات الأولى

هناك ثلاث خطوات لإنشاء خريطة Google باستخدام محدِّد على صفحة الويب الخاصة بك:

الحصول على مفتاح واجهة برمجة التطبيقات
إنشاء صفحة HTML
إضافة خريطة مع محدِّد موقع

تحتاج إلى متصفح ويب. اختَر متصفّحًا معروفًا، مثل Google Chrome (يُنصح به) أو Firefox أو Safari أو Edge، استنادًا إلى نظامك الأساسي من قائمة المتصفّحات المتوافقة.

الخطوة 1: الحصول على مفتاح واجهة برمجة التطبيقات

يشرح هذا القسم كيفية مصادقة تطبيقك مع واجهة برمجة تطبيقات JavaScript للخرائط باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك.

اتّبِع الخطوات التالية للحصول على مفتاح واجهة برمجة التطبيقات:

الانتقال إلى Google Cloud Console.
إنشاء مشروع أو اختياره
انقر على متابعة لتفعيل واجهة برمجة التطبيقات وأي خدمات ذات صلة.
في صفحة بيانات الاعتماد، احصل على مفتاح واجهة برمجة التطبيقات (واضبط قيود مفتاح واجهة برمجة التطبيقات). ملاحظة: إذا كان لديك مفتاح واجهة برمجة تطبيقات غير مقيّد حاليًا أو مفتاح يفرض قيودًا على المتصفّح، يمكنك استخدام هذا المفتاح.
لمنع سرقة الحصة وتأمين مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على استخدام مفاتيح واجهة برمجة التطبيقات.
تفعيل الفوترة راجِع الاستخدام والفوترة للحصول على مزيد من المعلومات.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك إضافته إلى المقتطف التالي بالنقر على "YOUR_API_KEY". انسخ علامة النص البرمجي لبرنامج الإقلاع والصقها لاستخدامها في صفحتك على الويب.

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

style="height: 400px"

الخطوة 2: إنشاء صفحة HTML

في ما يلي رمز صفحة ويب HTML أساسية:

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

يُرجى العِلم أنّ هذه الصفحة أساسية جدًا مع عنوان من المستوى الثالث (h3) وعنصر div واحد. يمكنك إضافة أي محتوى تريده إلى صفحة الويب.

فهم الرمز البرمجي

تُنشئ التعليمة البرمجية أدناه صفحة HTML تتألف من رأس ونص.

<html>
 <head>
 </head>
 <body>
 </body>
</html>

يمكنك إضافة عنوان من المستوى الثالث فوق الخريطة باستخدام الكود أدناه.

<h3>My Google Maps Demo</h3>

يحدد الرمز أدناه منطقة من الصفحة لخريطة Google.

<!--The div element for the map -->
<div id="map"></div>

في هذه المرحلة من البرنامج التعليمي، تظهر علامة div ككتلة رمادية فقط، لأنّك لم تضِف خريطة بعد. يصف الرمز أدناه خدمة CSS التي تحدد حجم ولون div.

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

في الرمز أعلاه، يضبط عنصر style حجم div لخريطتك. يمكنك ضبط عرض وارتفاع div على أكبر من 0 بكسل حتى تكون الخريطة مرئية. في هذه الحالة، يتم ضبط div على ارتفاع 400 بكسل وعرض 100% لعرض صفحة الويب بطول الصفحة.

يُعِدّ برنامج الإقلاع واجهة برمجة تطبيقات JavaScript للخرائط للتحميل (لا يتم تحميل أي مكتبات حتى يتم استدعاء importLibrary()).

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

راجِع الخطوة الثالثة: الحصول على مفتاح واجهة برمجة التطبيقات للحصول على تعليمات حول الحصول على مفتاح واجهة برمجة التطبيقات الخاص بك.

الخطوة 3: إضافة خريطة باستخدام محدِّد

يوضح هذا القسم كيفية تحميل واجهة برمجة تطبيقات JavaScript للخرائط إلى صفحتك على الويب، وكيفية كتابة JavaScript الخاص بك الذي يستخدم واجهة برمجة التطبيقات لإضافة خريطة بها علامة.

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();index.js

في الرمز أعلاه، يتم تحميل المكتبتَين Map وAdvancedMarkerView عند استدعاء الدالة initMap().

فهم الرمز البرمجي

ينشئ الكود أدناه كائنًا جديدًا في خرائط Google، ويضيف خصائص إلى الخريطة بما في ذلك مستوى المركز ومستوى التكبير. اطّلِع على الوثائق الخاصة بالخيارات الأخرى.

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});
index.js

في الرمز أعلاه، ينشئ new Map() عنصرًا جديدًا في "خرائط Google". تحدّد السمة center لواجهة برمجة التطبيقات تحديد مركز الخريطة.

مزيد من المعلومات حول الحصول على إحداثيات خطوط الطول/العرض، أو تحويل عنوان إلى إحداثيات جغرافية.

تحدّد السمة zoom مستوى التكبير/التصغير للخريطة. التكبير/التصغير: 0 هو أقل مستوى تكبير، ويعرض الأرض بأكملها. اضبط قيمة التكبير/التصغير على مستوى أعلى لتكبير عرض Earth بدرجات دقة أعلى.

يضع الرمز أدناه علامة على الخريطة. تضبط السمة position موضع العلامة.

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});index.js

إكمال نموذج الرمز البرمجي

انظر مثال التعليمة البرمجية الكامل هنا:

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

HTML

<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>index.html

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell

مزيد من المعلومات عن العلامات:

النصائح وتحديد المشاكل وحلّها

يمكنك تعديل خيارات مثل النمط والخصائص لتخصيص الخريطة. لمزيد من المعلومات حول تخصيص الخرائط، يمكنك الاطّلاع على الأدلّة حول التصميم والرسم على الخريطة.
استخدِم وحدة تحكم أدوات مطوّري البرامج في متصفح الويب لاختبار الرمز وتشغيله وقراءة تقارير الأخطاء وحل المشاكل المتعلقة بالرموز.
استخدِم اختصارات لوحة المفاتيح التالية لفتح وحدة التحكّم في Chrome:
Command+Option+J (على Mac)، أو Control+Shift+J (على نظام التشغيل Windows).
اتبع الخطوات أدناه للحصول على إحداثيات خط العرض وخط الطول لموقع ما على "خرائط Google".
1. افتح "خرائط Google" في متصفّح.
2. انقر بزر الماوس الأيمن على الموقع الدقيق على الخريطة الذي تحتاج إلى إحداثيات له.
3. اختَر ماذا هنا من قائمة السياقات التي تظهر. تعرض الخريطة بطاقة في أسفل الشاشة. ابحث عن إحداثيات خط العرض وخط الطول في الصف الأخير من البطاقة.
يمكنك تحويل عنوان إلى إحداثيات خطوط الطول والعرض باستخدام خدمة الترميز الجغرافي. توفِّر أدلة المطوّرين معلومات تفصيلية حول بدء استخدام خدمة الترميز الجغرافي.