شکل‌ها و خط‌ها

پلاتفرم را انتخاب کنید: Android iOS JavaScript

می‌توانید شکل‌های مختلفی به نقشه‌تان اضافه کنید. شکل شیئی روی نقشه است که به مختصات عرض جغرافیایی/طول جغرافیایی وابسته است. شکل‌های زیر دردسترس هستند: خطوط، چندضلعی‌ها، دایره‌ها و مستطیل‌ها. همچنین می‌توانید شکل‌هایتان را به‌گونه‌ای پیکربندی کنید که کاربران بتوانند آن‌ها را ویرایش یا بکشند، یا شکل‌ها را با کتابخانه هندسه (google.maps.GeometryLibrary) ترکیب کنید تا حصارکشی‌های جغرافیایی و مرزهای منطقه امن را بررسی کنید.

چندخطی‌ها

برای ترسیم خط روی نقشه، از چندخطی استفاده کنید. کلاس 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.
const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    const { Polyline } = await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;

    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 Polyline({
        path: flightPlanCoordinates,
        geodesic: true,
        strokeColor: '#FF0000',
        strokeOpacity: 1.0,
        strokeWeight: 2,
    });

    flightPath.setMap(innerMap);
}

void init();

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.
const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    const { Polyline } = await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;

    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 Polyline({
        path: flightPlanCoordinates,
        geodesic: true,
        strokeColor: '#FF0000',
        strokeOpacity: 1.0,
        strokeWeight: 2,
    });

    flightPath.setMap(innerMap);
}

void init();
مشاهده نمونه

برداشتن چندخطی

برای برداشتن چندخطی از نقشه، روش setMap() را فراخوانی کنید و null را به‌عنوان شناسه ارسال کنید. در مثال زیر، flightPath یک شیء چندخطی است:

flightPath.setMap(null);

توجه داشته باشید که روش بالا چندخطی را حذف نمی‌کند. این روش چندخطی را از نقشه برمی‌دارد. اگر درعوض می‌خواهید چندخطی را حذف کنید، باید آن را از نقشه بردارید و سپس خود چندخطی را روی null تنظیم کنید.

بازرسی چندخطی

چندخطی مجموعه‌ای از مختصات را به‌عنوان آرایه‌ای از اشیای LatLng مشخص می‌کند. این مختصات مسیر خط را تعیین می‌کند. برای بازیابی مختصات، getPath() را فراخوانی کنید که آرایه‌ای از نوع MVCArray را برمی‌گرداند. می‌توانید بااستفاده از عملیات زیر، آرایه را دستکاری و بازرسی کنید:

  • getAt() مقدار LatLng را در مقدار نمایه صفرپایه داده‌شده برمی‌گرداند.
  • insertAt() یک LatLng ارسال‌شده را در مقدار نمایه مبتنی بر صفر داده‌شده درج می‌کند. توجه داشته باشید که هرگونه مختصات موجود در آن مقدار نمایه به جلو منتقل می‌شود.
  • ‫removeAt() یک LatLng را در مقدار نمایه مبتنی بر صفر داده‌شده برمی‌دارد.

مثال زیر ساختن چندخطی براساس کلیک‌ها را نشان می‌دهد (برای افزودن رأس، روی نقشه کلیک کنید).

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;
const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Import the needed libraries.
    const [{ Polyline }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    innerMap = mapElement.innerMap;

    poly = new Polyline({
        strokeColor: '#000000',
        strokeOpacity: 1.0,
        strokeWeight: 3,
    });
    poly.setMap(innerMap);

    // Handles click events on a map, and adds a new point to the Polyline.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        const latLng = event.latLng;
        if (!latLng) return;

        const path = poly.getPath();

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

        // Add a new marker at the new plotted point on the polyline.
        new AdvancedMarkerElement({
            position: latLng,
            title: '#' + path.getLength(),
            map: innerMap,
        });
    });
}

void init();

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;
const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Import the needed libraries.
    const [{ Polyline }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    innerMap = mapElement.innerMap;

    poly = new Polyline({
        strokeColor: '#000000',
        strokeOpacity: 1.0,
        strokeWeight: 3,
    });
    poly.setMap(innerMap);

    // Handles click events on a map, and adds a new point to the Polyline.
    innerMap.addListener('click', (event) => {
        const latLng = event.latLng;
        if (!latLng) return;

        const path = poly.getPath();

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

        // Add a new marker at the new plotted point on the polyline.
        new AdvancedMarkerElement({
            position: latLng,
            title: '#' + path.getLength(),
            map: innerMap,
        });
    });
}

void init();
مشاهده نمونه

سفارشی‌سازی چندخطی

می‌توانید تصاویر برداری را به‌شکل نماد به چندخطی اضافه کنید. با ترکیبی از نمادها و کلاس PolylineOptions، کنترل زیادی بر ظاهر و احساس چندخطی‌ها در نقشه‌تان دارید. برای اطلاعات درباره پیکان‌ها، خط‌چین‌ها، نمادهای سفارشی و نمادهای پویانمایی‌شده، نمادها را ببینید.

چندضلعی‌ها

چندضلعی نشان‌دهنده منطقه‌ای است که با مسیر بسته (یا حلقه) محصور شده است، که با مجموعه‌ای از مختصات تعریف می‌شود. اشیاء Polygon شبیه اشیاء Polyline هستند از این نظر که از مجموعه‌ای از مختصات در یک توالی مرتب تشکیل شده‌اند. چندضلعی‌ها با خط و رنگ‌آمیزی کشیده می‌شوند. می‌توانید رنگ‌ها، ضخامت‌ها، و شفافیت‌های سفارشی برای لبه چندضلعی (خط) و رنگ‌ها و شفافیت‌های سفارشی برای ناحیه محصور (داخل) تعریف کنید. رنگ‌ها باید در قالب HTML شانزده‌شانزدهی نشان داده شوند. از نام رنگ‌ها پشتیبانی نمی‌شود.

اشیاء Polygon می‌توانند شکل‌های پیچیده را توصیف کنند، ازجمله:

  • چندین منطقه غیرمجاور که با یک چندضلعی تعریف شده‌اند.
  • مناطقی که در آن‌ها سوراخ وجود دارد.
  • تقاطع یک یا چند منطقه.

برای تعریف شکل پیچیده، از چندضلعی با چند مسیر استفاده می‌کنید.

توجه: لایه «داده‌ها» روش ساده‌ای برای رسم چندضلعی‌ها ارائه می‌دهد. این روش پیچش چندضلعی را برای شما مدیریت می‌کند و ترسیم چندضلعی‌های دارای سوراخ را آسان‌تر می‌کند. اسناد مربوط به لایه داده را ببینید.

افزودن چندضلعی

چون یک ناحیه چندضلعی ممکن است شامل چندین مسیر جداگانه باشد، ویژگی paths شیء Polygon آرایه‌ای از آرایه‌ها را مشخص می‌کند که هرکدام از نوع MVCArray هستند. هر آرایه توالی جداگانه‌ای از مختصات LatLng مرتب‌شده را تعریف می‌کند.

برای چندضلعی‌های ساده که فقط از یک مسیر تشکیل شده‌اند، می‌توانید Polygon را بااستفاده از یک آرایه از مختصات LatLng بسازید. The Maps JavaScript API will convert the simple array into an array of arrays upon construction when storing it within the paths property. این میانای برنامه‌سازی کاربردی روش getPath() ساده‌ای برای چندضلعی‌های متشکل از یک مسیر ارائه می‌دهد.

مشخصه 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;

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;
مشاهده نمونه

تکمیل خودکار چندضلعی

Polygon در مثال بالا از چهار مجموعه مختصات LatLng تشکیل شده است، اما توجه داشته باشید که مجموعه اول و آخر مکان یکسانی را تعریف می‌کنند که حلقه را تکمیل می‌کند. اما در عمل، چون چندضلعی‌ها نواحی بسته‌ای را تعریف می‌کنند، لازم نیست آخرین مجموعه مختصات را مشخص کنید. ‫Maps JavaScript API به‌طور خودکار چندضلعی را با کشیدن خطی که آخرین مکان را به اولین مکان در هر مسیر مشخص‌شده متصل می‌کند، تکمیل خواهد کرد.

مثال زیر با مثال قبلی یکسان است، با این تفاوت که LatLng آخر حذف شده است: مشاهده مثال.

برداشتن چندضلعی

برای برداشتن چندضلعی از نقشه، متد setMap() را فراخوانی کنید و null را به‌عنوان آرگومان ارسال کنید. در مثال زیر، bermudaTriangle یک شیء چندضلعی است:

bermudaTriangle.setMap(null);

توجه داشته باشید که روش بالا چندضلعی را حذف نمی‌کند. این کار چندضلعی را از نقشه برمی‌دارد. اگر درعوض می‌خواهید چندضلعی را حذف کنید، باید آن را از نقشه بردارید و سپس خود چندضلعی را روی null تنظیم کنید.

بازرسی چندضلعی

چندضلعی مجموعه مختصات خود را به‌صورت آرایه‌ای از آرایه‌ها مشخص می‌کند، که هر آرایه از نوع MVCArray است. هر آرایه «برگ» آرایه‌ای از مختصات LatLng است که یک مسیر را مشخص می‌کند. برای بازیابی این مختصات، روش getPaths() شیء Polygon را فراخوانی کنید. ازآنجایی‌که آرایه یک MVCArray است، باید آن را بااستفاده از عملیات زیر دستکاری و بازرسی کنید:

  • getAt() مقدار LatLng را در مقدار نمایه صفرپایه داده‌شده برمی‌گرداند.
  • insertAt() یک LatLng ارسال‌شده را در مقدار نمایه مبتنی بر صفر داده‌شده درج می‌کند. توجه داشته باشید که هرگونه مختصات موجود در آن مقدار نمایه به جلو منتقل می‌شود.
  • ‫removeAt() یک LatLng را در مقدار نمایه مبتنی بر صفر داده‌شده برمی‌دارد.

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;

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;
مشاهده نمونه

ایجاد سوراخ در چندضلعی

برای ایجاد یک منطقه خالی در یک چندضلعی، باید دو مسیر ایجاد کنید، یکی داخل دیگری. برای ایجاد سوراخ، مختصاتی که مسیر داخلی را تعریف می‌کنند باید در جهت مخالف مختصاتی باشند که مسیر خارجی را تعریف می‌کنند. برای مثال، اگر مختصات مسیر بیرونی در جهت ساعت‌گرد باشد، مسیر درونی باید پادساعت‌گرد باشد.

توجه: لایه «داده» ترتیب مسیرهای داخلی و خارجی را برای شما مدیریت می‌کند و ترسیم چندضلعی‌های دارای سوراخ را آسان‌تر می‌کند. اسناد مربوط به لایه داده را ببینید.

مثال زیر چندضلعی‌ای را با دو مسیر ترسیم می‌کند که مسیر داخلی آن در جهت مخالف مسیر خارجی پیچیده است.

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;

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;
مشاهده نمونه

مستطیل‌ها

علاوه‌بر کلاس عمومی Polygon، Google Maps JavaScript API شامل کلاس خاصی برای 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;

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;
مشاهده نمونه

کد زیر هر بار که کاربر بزرگ‌نمایی را در نقشه تغییر می‌دهد، مستطیلی ایجاد می‌کند. اندازه مستطیل را ناحیه نمایش تعیین می‌کند.

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;

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;
مشاهده نمونه

برداشتن مستطیل

برای برداشتن مستطیل از نقشه، روش setMap() را فراخوانی کنید و null را به‌عنوان شناسه ارسال کنید.

rectangle.setMap(null);

توجه داشته باشید که روش بالا مستطیل را حذف نمی‌کند. این کار مستطیل را از نقشه برمی‌دارد. اگر درعوض می‌خواهید مستطیل را حذف کنید، باید آن را از نقشه بردارید و سپس خود مستطیل را روی null تنظیم کنید.

حلقه

علاوه‌بر کلاس عمومی Polygon، Google Maps JavaScript API شامل کلاس خاصی برای اشیاء Circle است تا ساخت آن‌ها را ساده کند.

افزودن دایره

Circle شبیه به Polygon است، از این جهت که می‌توانید رنگ‌ها، وزن‌ها، و شفافیت‌های سفارشی را برای لبه دایره (خط) و رنگ‌ها و شفافیت‌های سفارشی را برای ناحیه داخل دایره (پر کردن) تعریف کنید. رنگ‌ها باید به سبک HTML عددی شانزده‌شانزدهی نشان داده شوند.

برخلاف Polygon، شما paths را برای Circle تعریف نمی‌کنید. درعوض، دایره دو ویژگی دیگر دارد که شکل آن را تعریف می‌کند:

  • center google.maps.LatLng مرکز دایره را مشخص می‌کند.
  • radius شعاع دایره را به متر مشخص می‌کند.

مشخصه editable دایره تعیین می‌کند که آیا کاربران می‌توانند شکل را ویرایش کنند یا نه. شکل‌های قابل‌ویرایش توسط کاربر را در زیر ببینید. به‌طور مشابه، می‌توانید ویژگی draggable را تنظیم کنید تا به کاربران اجازه دهید دایره را بکشند.

مثال زیر از دایره‌ها برای نشان دادن زمان تقریبی پیاده‌روی بین مکان‌ها در کیوتو، ژاپن استفاده می‌کند. فاصله موردنیاز را از منو انتخاب کنید، روی نقشه کلیک کنید تا دایره دوباره در مرکز قرار گیرد، و دایره را بکشید تا موقعیت آن تغییر کند.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Request needed libraries.
    const [{ Circle }, { AdvancedMarkerElement }, { event }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('core'),
        ]);

    // Set the initial map center point.
    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan

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

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

    // Create the circle.
    const walkingCircle = new 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 AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);

    // Wait for the map to finish drawing its tiles.
    event.addListenerOnce(innerMap, 'tilesloaded', () => {
        // 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', (changeEvent) => {
            const target = changeEvent.target as HTMLInputElement;
            walkingCircle.setRadius(Number(target.value));
        });
    });

    // Handle user click, reset the map center and position the circle.
    innerMap.addListener(
        'click',
        (
            mapsMouseEvent:
                google.maps.MapMouseEvent | google.maps.IconMouseEvent
        ) => {
            const newCenter = mapsMouseEvent.latLng;
            if (!newCenter) return;
            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();
    });
}

void init();

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Request needed libraries.
    const [{ Circle }, { AdvancedMarkerElement }, { event }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('core'),
        ]);

    // Set the initial map center point.
    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan

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

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

    // Create the circle.
    const walkingCircle = new 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 AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);

    // Wait for the map to finish drawing its tiles.
    event.addListenerOnce(innerMap, 'tilesloaded', () => {
        // 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', (changeEvent) => {
            const target = changeEvent.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;
        if (!newCenter) return;
        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();
    });
}

void init();

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

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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>
مشاهده نمونه

برداشتن حلقه

برای برداشتن دایره از نقشه، روش 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 وقتی کاربر کشیدن شکل را متوقف می‌کند، فعال می‌شود.

برای اطلاعات بیشتر درباره مدیریت رویدادها، اسناد مربوط به رویدادها را ببینید.

حصارکشی جغرافیایی و مرزهای منطقه امن

«پلاتفرم Google Maps» میانای برنامه‌سازی کاربردی «حصار جغرافیایی» مستقل ارائه نمی‌دهد. برای نمایش شعاع حصار جغرافیایی یا منطقه امن در نقشه وب و بررسی اینکه آیا مختصات زنده در داخل آن مرز قرار دارد یا نه، شکل‌ها را با کتابخانه هندسه (google.maps.GeometryLibrary) بارشده ازطریق google.maps.importLibrary("geometry") ترکیب کنید:

مثال زیر یک منطقه امن دایره‌ای و یک حصار جغرافیایی چندضلعی را ترسیم می‌کند، سپس بررسی می‌کند که آیا مختصات زنده درون هر مرز قرار دارد یا نه:

const {Circle, Polygon} = await google.maps.importLibrary("maps");
const {poly} = await google.maps.importLibrary("geometry");

const livePosition = {lat: 37.424, lng: -122.085};

// 1. Circular geofence (500-meter radius)
const circularGeofence = new Circle({
  map,
  center: {lat: 37.422, lng: -122.084},
  radius: 500,
});
const isInsideCircle = poly.containsLocation(livePosition, circularGeofence);

// 2. Polygonal geofence
const polygonGeofence = new Polygon({
  map,
  paths: [
    {lat: 37.420, lng: -122.088},
    {lat: 37.420, lng: -122.080},
    {lat: 37.426, lng: -122.080},
    {lat: 37.426, lng: -122.088},
  ],
});
const isInsidePolygon = poly.containsLocation(livePosition, polygonGeofence);