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

اختيار النظام الأساسي: 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 API في "خرائط 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 API في "خرائط Google" فئة محدّدة لكائنات Circle، وذلك لتبسيط عملية إنشائها.

إضافة دائرة

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

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

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

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

TypeScript

// This example creates circles on the map, representing populations in North
// America.

// First, create an object containing LatLng and population for each city.

interface City {
  center: google.maps.LatLngLiteral;
  population: number;
}

const citymap: Record<string, City> = {
  chicago: {
    center: { lat: 41.878, lng: -87.629 },
    population: 2714856,
  },
  newyork: {
    center: { lat: 40.714, lng: -74.005 },
    population: 8405837,
  },
  losangeles: {
    center: { lat: 34.052, lng: -118.243 },
    population: 3857799,
  },
  vancouver: {
    center: { lat: 49.25, lng: -123.1 },
    population: 603502,
  },
};

function initMap(): void {
  // Create the map.
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 37.09, lng: -95.712 },
      mapTypeId: "terrain",
    }
  );

  // Construct the circle for each value in citymap.
  // Note: We scale the area of the circle based on the population.
  for (const city in citymap) {
    // Add the circle for this city to the map.
    const cityCircle = new google.maps.Circle({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      center: citymap[city].center,
      radius: Math.sqrt(citymap[city].population) * 100,
    });
  }
}

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

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

JavaScript

const citymap = {
  chicago: {
    center: { lat: 41.878, lng: -87.629 },
    population: 2714856,
  },
  newyork: {
    center: { lat: 40.714, lng: -74.005 },
    population: 8405837,
  },
  losangeles: {
    center: { lat: 34.052, lng: -118.243 },
    population: 3857799,
  },
  vancouver: {
    center: { lat: 49.25, lng: -123.1 },
    population: 603502,
  },
};

function initMap() {
  // Create the map.
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 37.09, lng: -95.712 },
    mapTypeId: "terrain",
  });

  // Construct the circle for each value in citymap.
  // Note: We scale the area of the circle based on the population.
  for (const city in citymap) {
    // Add the circle for this city to the map.
    const cityCircle = new google.maps.Circle({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      center: citymap[city].center,
      radius: Math.sqrt(citymap[city].population) * 100,
    });
  }
}

window.initMap = initMap;
index.js

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

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

إزالة دائرة

لإزالة دائرة من الخريطة، استخدِم طريقة 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.

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

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

لمزيد من المعلومات عن أنظمة الإحداثيات، يمكنك الرجوع إلى دليل إحداثيات الخريطة وشريحة الخريطة.

تعرض الخريطة التالية مثلثَين بالحجم والقياسات نفسها تقريبًا. تم ضبط سمة 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	يتم تشغيله عندما يتوقف المستخدم عن سحب الشكل.

لمزيد من المعلومات عن معالجة الأحداث، اطّلِع على مستندات الأحداث.