الأشكال والخطوط

اختيار النظام الأساسي: Android‏ iOS‏ JavaScript‏

يمكنك إضافة أشكال مختلفة إلى خريطتك. الشكل هو عنصر على الخريطة مرتبط بإحداثيات خط العرض وخط الطول. تتوفّر الأشكال التالية: الخطوط والمضلّعات والدوائر والمستطيلات. يمكنك أيضًا ضبط الأشكال بحيث يتمكّن المستخدمون من تعديلها أو سحبها.

الخطوط المتعددة

لرسم خط على خريطتك، استخدِم خطًا متعدد الأضلاع. يحدّد الصف Polyline تراكبًا خطيًا لتقسيمات خطية متصلة على الخريطة. يتألف عنصر Polyline من مصفوفة من مواقع LatLng، وينشئ سلسلة من مقاطع الخطوط التي تربط هذه المواقع في تسلسل مرتّب.

إضافة خطوط متعددة

يأخذ الدالة الإنشائية Polyline مجموعة من PolylineOptions تحدّد إحداثيات LatLng الخط ومجموعة من الأنماط لتعديل السلوك المرئي للخط المتعدد الأضلاع.

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

• تحدّد strokeColor لون HTML سداسي عشري بالتنسيق "#FFFFFF". لا يتيح الصف Polyline استخدام الألوان المسماة.
• تحدّد strokeOpacity قيمة رقمية بين 0.0 و1.0 لتحديد درجة عتامة لون الخط. القيمة التلقائية هي 1.0.
• strokeWeight تحدّد عرض الخط بالبكسل.

تحدّد السمة editable الخاصة بالخط المتعدد الأضلاع ما إذا كان بإمكان المستخدمين تعديل الشكل. يمكنك الاطّلاع على الأشكال القابلة للتعديل من قِبل المستخدم أدناه. وبالمثل، يمكنك ضبط السمة draggable للسماح للمستخدمين بسحب الخط.

ينشئ هذا المثال خطًا متعدد الأضلاع أحمر بعرض بكسلَين يعرض مسار أول رحلة جوية عبر المحيط الهادئ بين أوكلاند في كاليفورنيا وبريسبان في أستراليا.

TypeScript

// This example creates a 2-pixel-wide red polyline showing the path of
// the first trans-Pacific flight between Oakland, CA, and Brisbane,
// Australia which was made by Charles Kingsford Smith.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 3,
      center: { lat: 0, lng: -180 },
      mapTypeId: "terrain",
    }
  );

  const flightPlanCoordinates = [
    { lat: 37.772, lng: -122.214 },
    { lat: 21.291, lng: -157.821 },
    { lat: -18.142, lng: 178.431 },
    { lat: -27.467, lng: 153.027 },
  ];
  const flightPath = new google.maps.Polyline({
    path: flightPlanCoordinates,
    geodesic: true,
    strokeColor: "#FF0000",
    strokeOpacity: 1.0,
    strokeWeight: 2,
  });

  flightPath.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates a 2-pixel-wide red polyline showing the path of
// the first trans-Pacific flight between Oakland, CA, and Brisbane,
// Australia which was made by Charles Kingsford Smith.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 3,
    center: { lat: 0, lng: -180 },
    mapTypeId: "terrain",
  });
  const flightPlanCoordinates = [
    { lat: 37.772, lng: -122.214 },
    { lat: 21.291, lng: -157.821 },
    { lat: -18.142, lng: 178.431 },
    { lat: -27.467, lng: 153.027 },
  ];
  const flightPath = new google.maps.Polyline({
    path: flightPlanCoordinates,
    geodesic: true,
    strokeColor: "#FF0000",
    strokeOpacity: 1.0,
    strokeWeight: 2,
  });

  flightPath.setMap(map);
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

إزالة خط متعدد الأضلاع

لإزالة خط متعدد الأضلاع من الخريطة، استدعِ طريقة setMap() مع تمرير null كمعلَمة. في المثال التالي، flightPath هو عنصر خطوط متعدّدة:

flightPath.setMap(null);

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

فحص خطوط متعددة

يحدّد الخط المتعدد الأضلاع سلسلة من الإحداثيات كمصفوفة من عناصر LatLng. تحدّد هذه الإحداثيات مسار الخط. لاسترداد الإحداثيات، استدعِ الدالة getPath()، التي ستعرض مصفوفة من النوع MVCArray. يمكنك معالجة المصفوفة وفحصها باستخدام العمليات التالية:

• تعرض الدالة getAt() القيمة LatLng في فهرس معيّن مستند إلى الصفر.
• تُدرِج الدالة insertAt() LatLng في قيمة فهرس معيّنة تبدأ من صفر. يُرجى العِلم أنّه يتم نقل أي إحداثيات حالية في قيمة الفهرس هذه إلى الأمام.
• تزيل removeAt() LatLng في فهرس معيّن بقيمة صفرية.

ملاحظة: لا يمكنك استرداد العنصر i من مصفوفة باستخدام بنية mvcArray[i]. يجب استخدام mvcArray.getAt(i).

يوضّح المثال التالي كيفية إنشاء خط متعدّد الأضلاع استنادًا إلى النقرات (انقر على الخريطة لإضافة رأس).

TypeScript

// This example creates an interactive map which constructs a polyline based on
// user clicks. Note that the polyline only appears once its path property
// contains two LatLng coordinates.

let poly: google.maps.Polyline;
let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    zoom: 7,
    center: { lat: 41.879, lng: -87.624 }, // Center the map on Chicago, USA.
  });

  poly = new google.maps.Polyline({
    strokeColor: "#000000",
    strokeOpacity: 1.0,
    strokeWeight: 3,
  });
  poly.setMap(map);

  // Add a listener for the click event
  map.addListener("click", addLatLng);
}

// Handles click events on a map, and adds a new point to the Polyline.
function addLatLng(event: google.maps.MapMouseEvent) {
  const path = poly.getPath();

  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear.
  path.push(event.latLng as google.maps.LatLng);

  // Add a new marker at the new plotted point on the polyline.
  new google.maps.Marker({
    position: event.latLng,
    title: "#" + path.getLength(),
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates an interactive map which constructs a polyline based on
// user clicks. Note that the polyline only appears once its path property
// contains two LatLng coordinates.
let poly;
let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 7,
    center: { lat: 41.879, lng: -87.624 }, // Center the map on Chicago, USA.
  });
  poly = new google.maps.Polyline({
    strokeColor: "#000000",
    strokeOpacity: 1.0,
    strokeWeight: 3,
  });
  poly.setMap(map);
  // Add a listener for the click event
  map.addListener("click", addLatLng);
}

// Handles click events on a map, and adds a new point to the Polyline.
function addLatLng(event) {
  const path = poly.getPath();

  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear.
  path.push(event.latLng);
  // Add a new marker at the new plotted point on the polyline.
  new google.maps.Marker({
    position: event.latLng,
    title: "#" + path.getLength(),
    map: map,
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

تخصيص خط متعدد

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

المضلّعات

يمثّل المضلّع مساحة محاطة بمسار مغلق (أو حلقة)، ويتم تحديده من خلال سلسلة من الإحداثيات. تشبه عناصر Polygon عناصر Polyline من حيث أنّها تتألف من سلسلة من الإحداثيات في تسلسل مرتّب. يتم رسم المضلّعات باستخدام خطوط خارجية وتعبئة. يمكنك تحديد ألوان وأوزان ودرجات عتامة مخصّصة لحافة المضلّع (الحدود) وألوان ودرجات عتامة مخصّصة للمنطقة المحيطة (التعبئة). يجب تحديد الألوان بتنسيق HTML سداسي عشري. لا يمكن استخدام أسماء الألوان.

يمكن أن تصف عناصر Polygon الأشكال المعقّدة، بما في ذلك:

• مناطق متعدّدة غير متجاورة محدّدة بمضلّع واحد
• المناطق التي تحتوي على ثقوب
• تقاطعات منطقة واحدة أو أكثر

لتحديد شكل معقّد، يمكنك استخدام مضلّع يتضمّن مسارات متعدّدة.

ملاحظة: توفّر "طبقة البيانات" طريقة بسيطة لرسم المضلّعات. يتعامل هذا النوع مع عملية لف المضلّعات نيابةً عنك، ما يسهّل رسم المضلّعات التي تتضمّن ثقوبًا. راجِع المستندات المتعلّقة بطبقة البيانات.

إضافة مضلّع

بما أنّ المنطقة المضلّعة قد تتضمّن عدة مسارات منفصلة، تحدّد السمة paths الخاصة بالعنصر Polygon مصفوفة من المصفوفات، كل منها من النوع MVCArray. يحدّد كل صفيف تسلسلاً منفصلاً من إحداثيات LatLng مرتبة.

بالنسبة إلى المضلّعات البسيطة التي تتألف من مسار واحد فقط، يمكنك إنشاء Polygon باستخدام مصفوفة واحدة من إحداثيات LatLng. ستحوّل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" المصفوفة البسيطة إلى مصفوفة من المصفوفات عند إنشائها عند تخزينها ضمن السمة paths. توفّر واجهة برمجة التطبيقات طريقة بسيطة getPath() للمضلّعات التي تتضمّن مسارًا واحدًا.

ملاحظة: إذا أنشأت مضلّعًا بسيطًا بهذه الطريقة، سيظل عليك استرداد القيم من المضلّع من خلال تعديل المسار كـ MVCArray.

تحدّد السمة editable الخاصة بالمضلّع ما إذا كان بإمكان المستخدمين تعديل الشكل. يمكنك الاطّلاع على الأشكال القابلة للتعديل من قِبل المستخدم أدناه. وبالمثل، يمكنك ضبط السمة draggable للسماح للمستخدمين بسحب الشكل.

TypeScript

// This example creates a simple polygon representing the Bermuda Triangle.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 5,
      center: { lat: 24.886, lng: -70.268 },
      mapTypeId: "terrain",
    }
  );

  // Define the LatLng coordinates for the polygon's path.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
    { lat: 25.774, lng: -80.19 },
  ];

  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates a simple polygon representing the Bermuda Triangle.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });
  // Define the LatLng coordinates for the polygon's path.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
    { lat: 25.774, lng: -80.19 },
  ];
  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

الإكمال التلقائي للمضلّع

يتألف Polygon في المثال أعلاه من أربع مجموعات من إحداثيات LatLng، ولكن لاحظ أنّ المجموعتين الأولى والأخيرة تحدّدان الموقع الجغرافي نفسه، ما يكمل الحلقة. في الواقع، بما أنّ المضلّعات تحدّد مساحات مغلقة، ليس عليك تحديد المجموعة الأخيرة من الإحداثيات. ستُكمل واجهة برمجة تطبيقات JavaScript للخرائط المضلّع تلقائيًا من خلال رسم خط يصل بين آخر موقع جغرافي وأول موقع جغرافي لأي مسار محدّد.

المثال التالي مطابق للمثال السابق، باستثناء أنّه تم حذف السمة LatLng الأخيرة: عرض المثال.

إزالة مضلّع

لإزالة مضلّع من الخريطة، استدعِ طريقة setMap() مع تمرير null كمعلَمة. في المثال التالي، bermudaTriangle هو عنصر مضلّع:

bermudaTriangle.setMap(null);

يُرجى العِلم أنّ الطريقة المذكورة أعلاه لا تحذف المضلّع. تؤدي هذه العملية إلى إزالة المضلّع من الخريطة. إذا أردت حذف المضلّع، عليك إزالته من الخريطة، ثم ضبط المضلّع نفسه على null.

تشبه إزالة مضلّع إزالة خط متعدد الأضلاع. للاطّلاع على الرمز البرمجي أثناء عمله مع خط متعدد الأضلاع، يمكنك عرض المثال.

فحص مضلّع

يحدّد المضلّع سلسلة إحداثياته كمصفوفة من المصفوفات، حيث يكون كل مصفوفة من النوع MVCArray. كل مصفوفة "ورقة" هي مصفوفة من إحداثيات LatLng تحدّد مسارًا واحدًا. لاسترداد هذه الإحداثيات، استدعِ طريقة getPaths() الخاصة بالكائن Polygon. بما أنّ مصفوفة هي MVCArray، عليك تعديلها وفحصها باستخدام العمليات التالية:

• تعرض الدالة getAt() القيمة LatLng في فهرس معيّن مستند إلى الصفر.
• تُدرِج الدالة insertAt() LatLng في قيمة فهرس معيّنة تبدأ من صفر. يُرجى العِلم أنّه يتم نقل أي إحداثيات حالية في قيمة الفهرس هذه إلى الأمام.
• تزيل removeAt() LatLng في فهرس معيّن بقيمة صفرية.

ملاحظة: لا يمكنك استرداد العنصر i من مصفوفة باستخدام بنية mvcArray[i]. يجب استخدام mvcArray.getAt(i).

TypeScript

// This example creates a simple polygon representing the Bermuda Triangle.
// When the user clicks on the polygon an info window opens, showing
// information about the polygon's coordinates.

let map: google.maps.Map;

let infoWindow: google.maps.InfoWindow;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });

  // Define the LatLng coordinates for the polygon.
  const triangleCoords: google.maps.LatLngLiteral[] = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];

  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 3,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);

  // Add a listener for the click event.
  bermudaTriangle.addListener("click", showArrays);

  infoWindow = new google.maps.InfoWindow();
}

function showArrays(event: any) {
  // Since this polygon has only one path, we can call getPath() to return the
  // MVCArray of LatLngs.
  // @ts-ignore
  const polygon = this as google.maps.Polygon;
  const vertices = polygon.getPath();

  let contentString =
    "<b>Bermuda Triangle polygon</b><br>" +
    "Clicked location: <br>" +
    event.latLng.lat() +
    "," +
    event.latLng.lng() +
    "<br>";

  // Iterate over the vertices.
  for (let i = 0; i < vertices.getLength(); i++) {
    const xy = vertices.getAt(i);

    contentString +=
      "<br>" + "Coordinate " + i + ":<br>" + xy.lat() + "," + xy.lng();
  }

  // Replace the info window's content and position.
  infoWindow.setContent(contentString);
  infoWindow.setPosition(event.latLng);

  infoWindow.open(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates a simple polygon representing the Bermuda Triangle.
// When the user clicks on the polygon an info window opens, showing
// information about the polygon's coordinates.
let map;
let infoWindow;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });

  // Define the LatLng coordinates for the polygon.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];
  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 3,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
  // Add a listener for the click event.
  bermudaTriangle.addListener("click", showArrays);
  infoWindow = new google.maps.InfoWindow();
}

function showArrays(event) {
  // Since this polygon has only one path, we can call getPath() to return the
  // MVCArray of LatLngs.
  // @ts-ignore
  const polygon = this;
  const vertices = polygon.getPath();
  let contentString =
    "<b>Bermuda Triangle polygon</b><br>" +
    "Clicked location: <br>" +
    event.latLng.lat() +
    "," +
    event.latLng.lng() +
    "<br>";

  // Iterate over the vertices.
  for (let i = 0; i < vertices.getLength(); i++) {
    const xy = vertices.getAt(i);

    contentString +=
      "<br>" + "Coordinate " + i + ":<br>" + xy.lat() + "," + xy.lng();
  }

  // Replace the info window's content and position.
  infoWindow.setContent(contentString);
  infoWindow.setPosition(event.latLng);
  infoWindow.open(map);
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

إنشاء ثقب في مضلّع

لإنشاء مساحة فارغة داخل مضلّع، عليك إنشاء مسارَين، أحدهما داخل الآخر. لإنشاء الثقب، يجب أن تكون الإحداثيات التي تحدّد المسار الداخلي بترتيب معاكس للإحداثيات التي تحدّد المسار الخارجي. على سبيل المثال، إذا كانت إحداثيات المسار الخارجي مرتّبة باتجاه عقارب الساعة، يجب أن يكون المسار الداخلي عكس اتجاه عقارب الساعة.

ملاحظة: تتعامل "طبقة البيانات" مع ترتيب المسارات الداخلية والخارجية، ما يسهّل رسم المضلّعات التي تتضمّن ثقوبًا. راجِع المستندات المتعلّقة بطبقة البيانات.

يرسم المثال التالي مضلّعًا يتضمّن مسارين، حيث يكون المسار الداخلي ملتفًا في الاتجاه المعاكس للمسار الخارجي.

TypeScript

// This example creates a triangular polygon with a hole in it.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 5,
      center: { lat: 24.886, lng: -70.268 },
    }
  );

  // Define the LatLng coordinates for the polygon's  outer path.
  const outerCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];

  // Define the LatLng coordinates for the polygon's inner path.
  // Note that the points forming the inner path are wound in the
  // opposite direction to those in the outer path, to form the hole.
  const innerCoords = [
    { lat: 28.745, lng: -70.579 },
    { lat: 29.57, lng: -67.514 },
    { lat: 27.339, lng: -66.668 },
  ];

  // Construct the polygon, including both paths.
  const bermudaTriangle = new google.maps.Polygon({
    paths: [outerCoords, innerCoords],
    strokeColor: "#FFC107",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FFC107",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates a triangular polygon with a hole in it.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
  });
  // Define the LatLng coordinates for the polygon's  outer path.
  const outerCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];
  // Define the LatLng coordinates for the polygon's inner path.
  // Note that the points forming the inner path are wound in the
  // opposite direction to those in the outer path, to form the hole.
  const innerCoords = [
    { lat: 28.745, lng: -70.579 },
    { lat: 29.57, lng: -67.514 },
    { lat: 27.339, lng: -66.668 },
  ];
  // Construct the polygon, including both paths.
  const bermudaTriangle = new google.maps.Polygon({
    paths: [outerCoords, innerCoords],
    strokeColor: "#FFC107",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FFC107",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

مستطيلات

بالإضافة إلى فئة Polygon العامة، تتضمّن واجهة برمجة تطبيقات JavaScript الخاصة بـ "خرائط Google" فئة خاصة لكائنات Rectangle، وذلك لتبسيط عملية إنشائها.

إضافة مستطيل

يشبه Rectangle Polygon في إمكانية تحديد ألوان وأوزان ودرجات عتامة مخصّصة لحافة المستطيل (الحد) وألوان ودرجات عتامة مخصّصة للمساحة داخل المستطيل (التعبئة). يجب الإشارة إلى الألوان بنمط HTML رقمي سداسي عشري.

على عكس Polygon، لا تحدّد paths لـ Rectangle. بدلاً من ذلك، يحتوي المستطيل على السمة bounds التي تحدّد شكله من خلال تحديد google.maps.LatLngBounds للمستطيل.

تحدّد السمة editable الخاصة بالمستطيل ما إذا كان بإمكان المستخدمين تعديل الشكل. يمكنك الاطّلاع على الأشكال القابلة للتعديل من قِبل المستخدم أدناه. وبالمثل، يمكنك ضبط السمة draggable للسماح للمستخدمين بسحب المستطيل.

TypeScript

// This example adds a red rectangle to a map.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 33.678, lng: -116.243 },
      mapTypeId: "terrain",
    }
  );

  const rectangle = new google.maps.Rectangle({
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
    map,
    bounds: {
      north: 33.685,
      south: 33.671,
      east: -116.234,
      west: -116.251,
    },
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example adds a red rectangle to a map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 33.678, lng: -116.243 },
    mapTypeId: "terrain",
  });
  const rectangle = new google.maps.Rectangle({
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
    map,
    bounds: {
      north: 33.685,
      south: 33.671,
      east: -116.234,
      west: -116.251,
    },
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

ينشئ الرمز التالي مستطيلاً في كل مرة يغيّر فيها المستخدم مستوى التكبير/التصغير على الخريطة. يتم تحديد حجم المستطيل من خلال إطار العرض.

TypeScript

// This example creates a rectangle based on the viewport
// on any 'zoom-changed' event.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 40.74852, lng: -73.981687 },
      mapTypeId: "terrain",
    }
  );

  const rectangle = new google.maps.Rectangle();

  map.addListener("zoom_changed", () => {
    // Get the current bounds, which reflect the bounds before the zoom.
    rectangle.setOptions({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      bounds: map.getBounds() as google.maps.LatLngBounds,
    });
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// This example creates a rectangle based on the viewport
// on any 'zoom-changed' event.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 40.74852, lng: -73.981687 },
    mapTypeId: "terrain",
  });
  const rectangle = new google.maps.Rectangle();

  map.addListener("zoom_changed", () => {
    // Get the current bounds, which reflect the bounds before the zoom.
    rectangle.setOptions({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      bounds: map.getBounds(),
    });
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

إزالة مستطيل

لإزالة مستطيل من الخريطة، استدعِ الدالة setMap() مع تمرير null كمعلَمة.

rectangle.setMap(null);

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

تشبه عملية إزالة مستطيل عملية إزالة خط متعدد الأضلاع. للاطّلاع على الرمز البرمجي أثناء عمله مع خط متعدد الأضلاع، يمكنك عرض المثال.

دوائر

بالإضافة إلى الفئة العامة Polygon، تتضمّن واجهة برمجة تطبيقات JavaScript الخاصة بـ "خرائط Google" فئة خاصة لعناصر Circle، وذلك لتبسيط عملية إنشائها.

إضافة دائرة

يشبه Circle Polygon من حيث أنّه يمكنك تحديد ألوان وأوزان ودرجات عتامة مخصّصة لحافة الدائرة (الحدود) وألوان ودرجات عتامة مخصّصة للمساحة داخل الدائرة (التعبئة). يجب الإشارة إلى الألوان بنمط HTML الرقمي السداسي العشري.

على عكس Polygon، لا تحدّد paths لـ Circle. بدلاً من ذلك، يتضمّن الدائرة سمتَين إضافيتَين تحدّدان شكلها:

• تحدّد center google.maps.LatLng مركز الدائرة.
• تمثّل radius نصف قطر الدائرة بالأمتار.

تحدّد السمة editable للدائرة ما إذا كان بإمكان المستخدمين تعديل الشكل. يمكنك الاطّلاع على الأشكال القابلة للتعديل من قِبل المستخدم أدناه. وبالمثل، يمكنك ضبط السمة draggable للسماح للمستخدمين بسحب الدائرة.

يستخدم المثال التالي دوائر لعرض أوقات المشي التقريبية بين المواقع الجغرافية في كيوتو، اليابان. اختَر المسافة المطلوبة من القائمة، وانقر على الخريطة لإعادة توسيط الدائرة، ثم اسحب الدائرة لتغيير موضعها.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap;

async function initMap() {
    // Import the needed libraries.
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;
    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    const buttons = document.querySelectorAll('input[name="radius"]');

    const walkingCircle = new google.maps.Circle({
        strokeColor: '#ffdd00ff',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ffdd00ff',
        fillOpacity: 0.35,
        map: innerMap,
        center: initialCenter,
        radius: 400,
        draggable: true,
        editable: false,
    });

    // Define a "Crosshair" vector icon
    const parser = new DOMParser();
    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="-6 -6 12 12"><path d="M -6,0 L 6,0 M 0,-6 L 0,6" stroke="black" stroke-width="1"/></svg>`;

    const pinSvg = parser.parseFromString(
        svgString,
        'image/svg+xml'
    ).documentElement;

    const centerMarker = new google.maps.marker.AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        //@ts-ignore
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);

    // Wait for the map to finish drawing its tiles.
    google.maps.event.addListenerOnce(innerMap, 'tilesloaded', function () {
        // Get the controls div
        const controls = document.getElementById('control-panel');

        // Display controls once map is loaded.
        if (controls) {
            controls.style.display = 'block';
        }
    });

    // Add event listener to update the radius based on user selection.
    buttons.forEach((button) => {
        button.addEventListener('change', (event) => {
            const target = event.target as HTMLInputElement;
            walkingCircle.setRadius(Number(target.value));
        });
    });

    // Handle user click, reset the map center and position the circle.
    innerMap.addListener('click', (mapsMouseEvent) => {
        const newCenter = mapsMouseEvent.latLng;
        walkingCircle.setCenter(newCenter);
        centerMarker.position = newCenter;
        innerMap.panTo(newCenter);
    });

    // Handle user dragging the circle, update the center marker position.
    walkingCircle.addListener('center_changed', () => {
        centerMarker.position = walkingCircle.getCenter();
    });
}

initMap();
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
async function initMap() {
    // Import the needed libraries.
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    const buttons = document.querySelectorAll('input[name="radius"]');
    const walkingCircle = new google.maps.Circle({
        strokeColor: '#ffdd00ff',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ffdd00ff',
        fillOpacity: 0.35,
        map: innerMap,
        center: initialCenter,
        radius: 400,
        draggable: true,
        editable: false,
    });
    // Define a "Crosshair" vector icon
    const parser = new DOMParser();
    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="-6 -6 12 12"><path d="M -6,0 L 6,0 M 0,-6 L 0,6" stroke="black" stroke-width="1"/></svg>`;
    const pinSvg = parser.parseFromString(svgString, 'image/svg+xml').documentElement;
    const centerMarker = new google.maps.marker.AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        //@ts-ignore
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);
    // Wait for the map to finish drawing its tiles.
    google.maps.event.addListenerOnce(innerMap, 'tilesloaded', function () {
        // Get the controls div
        const controls = document.getElementById('control-panel');
        // Display controls once map is loaded.
        if (controls) {
            controls.style.display = 'block';
        }
    });
    // Add event listener to update the radius based on user selection.
    buttons.forEach((button) => {
        button.addEventListener('change', (event) => {
            const target = event.target;
            walkingCircle.setRadius(Number(target.value));
        });
    });
    // Handle user click, reset the map center and position the circle.
    innerMap.addListener('click', (mapsMouseEvent) => {
        const newCenter = mapsMouseEvent.latLng;
        walkingCircle.setCenter(newCenter);
        centerMarker.position = newCenter;
        innerMap.panTo(newCenter);
    });
    // Handle user dragging the circle, update the center marker position.
    walkingCircle.addListener('center_changed', () => {
        centerMarker.position = walkingCircle.getCenter();
    });
}
initMap();
index.js

CSS

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

#control-panel {
  display: none; /* Set to 'display: block' after the map loads. */
  background-color: #fff;
  border: 2px solid #fff;
  border-radius: 3px;
  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
  font-family: "Roboto", "sans-serif";
  font-size: medium;
  margin: 10px;
  padding: 10px;
}
style.css

HTML

<html>
    <head>
        <title>Circles</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map
            center="34.98956821576194, 135.74239981260283"
            zoom="15"
            map-id="DEMO_MAP_ID">
            <div id="control-panel" slot="control-inline-start-block-start">
                <input
                    id="short-walk"
                    type="radio"
                    name="radius"
                    value="400"
                    checked />
                <label for="short-walk">Short Walk (~5 minutes)</label><br />
                <input
                    id="medium-walk"
                    type="radio"
                    name="radius"
                    value="800" />
                <label for="medium-walk">Medium Walk (~15 minutes)</label><br />
                <input id="long-walk" type="radio" name="radius" value="1600" />
                <label for="long-walk">Long Walk (~30 minutes) </label>
            </div>
        </gmp-map>
    </body>
</html>
index.html

عرض مثال

تجربة عيّنة

JSFiddle.net

إزالة دائرة

لإزالة دائرة من الخريطة، استدعِ الدالة setMap() مع تمرير null كمعلَمة.

circle.setMap(null);

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

تشبه إزالة دائرة إزالة خط متعدد الأضلاع. للاطّلاع على الرمز البرمجي أثناء عمله مع خط متعدد الأضلاع، يمكنك عرض المثال.

أشكال قابلة للتعديل والسحب

عندما تجعل الشكل قابلاً للتعديل، تتم إضافة مقابض إليه، ويمكن للمستخدمين استخدامها لتغيير موضع الشكل وتعديل شكله وتغيير حجمه مباشرةً على الخريطة. يمكنك أيضًا جعل الشكل قابلاً للسحب، ليتمكّن المستخدمون من نقله إلى مكان مختلف على الخريطة.

لا تستمر التغييرات التي يجريها المستخدم على العنصر بين الجلسات. إذا كنت تريد حفظ تعديلات المستخدم، عليك تسجيل المعلومات وتخزينها بنفسك.

إتاحة إمكانية تعديل شكل

يمكن ضبط أي شكل (خطوط متعددة الأضلاع ومضلعات ودوائر ومستطيلات) على أن يكون قابلاً للتعديل من قِبل المستخدم، وذلك من خلال ضبط editable على true في خيارات الشكل.

var bounds = {
  north: 44.599,
  south: 44.490,
  east: -78.443,
  west: -78.649
};

// Define a rectangle and set its editable property to true.
var rectangle = new google.maps.Rectangle({
  bounds: bounds,
  editable: true
});

عرض مثال

جعل شكل قابلاً للسحب

بشكلٍ تلقائي، سيتم تثبيت موضع الشكل المرسوم على الخريطة. للسماح للمستخدمين بسحب شكل إلى موقع مختلف على الخريطة، اضبط draggable على true في خيارات الشكل.

var redCoords = [
  {lat: 25.774, lng: -80.190},
  {lat: 18.466, lng: -66.118},
  {lat: 32.321, lng: -64.757}
];

// Construct a draggable red triangle with geodesic set to true.
new google.maps.Polygon({
  map: map,
  paths: redCoords,
  strokeColor: '#FF0000',
  strokeOpacity: 0.8,
  strokeWeight: 2,
  fillColor: '#FF0000',
  fillOpacity: 0.35,
  draggable: true,
  geodesic: true
});

عند تفعيل إمكانية سحب شكل مضلّع أو متعدّد الخطوط، يجب أيضًا مراعاة جعل الشكل المضلّع أو المتعدّد الخطوط جيوديسيًا من خلال ضبط الخاصية geodesic على true.

سيحتفظ المضلّع الجيوديسي بشكله الجغرافي الحقيقي عند نقله، ما يؤدي إلى ظهور المضلّع مشوّهًا عند نقله إلى الشمال أو الجنوب في إسقاط مركاتور. ستحتفظ المضلّعات غير الجيوديسية دائمًا بمظهرها الأوّلي على الشاشة.

في خطوط متعددة الأضلاع جيوديسية، يتم رسم أجزاء الخطوط المتعددة الأضلاع كأقصر مسار بين نقطتين على سطح الأرض، على افتراض أنّ الأرض عبارة عن كرة، وذلك على عكس الخطوط المستقيمة على إسقاط مركاتور.

لمزيد من المعلومات حول أنظمة الإحداثيات، يُرجى الرجوع إلى دليل إحداثيات الخرائط والمربّعات.

تعرض الخريطة التالية مثلثَين لهما الحجم والأبعاد نفسها تقريبًا. تم ضبط السمة geodesic للمثلث الأحمر على true. لاحظ كيف يتغير شكله أثناء تحرّكه شمالاً.

عرض مثال

الاستماع إلى أحداث التعديل

عند تعديل شكل، يتم إطلاق حدث عند اكتمال التعديل. وفي ما يلي قائمة بهذه الأحداث.

الشكل	الفعاليات
دائرة	radius_changed center_changed
مضلّع	insert_at remove_at set_at يجب ضبط أداة معالجة الأحداث على مسار المضلّع. إذا كان المضلّع يتضمّن مسارات متعدّدة، يجب ضبط أداة معالجة الأحداث على كل مسار.
خط متعدد	insert_at remove_at set_at يجب ضبط أداة معالجة الأحداث على مسار الخط المتعدد الأضلاع.
مستطيل	bounds_changed

في ما يلي بعض مقتطفات الرموز البرمجية المفيدة:

google.maps.event.addListener(circle, 'radius_changed', function() {
  console.log(circle.getRadius());
});

google.maps.event.addListener(outerPath, 'set_at', function() {
  console.log('Vertex moved on outer path.');
});

google.maps.event.addListener(innerPath, 'insert_at', function() {
  console.log('Vertex removed from inner path.');
});

google.maps.event.addListener(rectangle, 'bounds_changed', function() {
  console.log('Bounds changed.');
});

يمكنك الاطّلاع على مثال على معالجة حدث تعديل على مستطيل: عرض المثال.

الاستماع إلى أحداث السحب

عند سحب شكل، يتم تنشيط الأحداث عند بدء عملية السحب وعند انتهائها، وكذلك أثناء السحب. يتم تنشيط الأحداث التالية للخطوط المتعددة والمضلّعات والدوائر والمستطيلات.

الحدث	الوصف
dragstart	يتم تنشيط هذا الحدث عندما يبدأ المستخدم في سحب الشكل.
drag	يتم تنشيطه بشكل متكرّر أثناء سحب المستخدم للشكل.
dragend	يتم تنشيط هذا الحدث عندما يتوقف المستخدم عن سحب الشكل.

لمزيد من المعلومات حول التعامل مع الأحداث، راجِع المستندات حول الأحداث.