کنترل ها

نمای کلی کنترل‌ها

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

نقشه زیر مجموعه پیش‌فرض کنترل‌های نمایش داده شده توسط Maps JavaScript API را نشان می‌دهد:

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

در زیر لیستی از مجموعه کامل کنترل‌هایی که می‌توانید در نقشه‌های خود استفاده کنید، آمده است:

• کنترل نوع نقشه (Map Type) به صورت کشویی یا نوار دکمه افقی موجود است و به کاربر امکان انتخاب نوع نقشه ( ROADMAP ، SATELLITE ، HYBRID یا TERRAIN ) را می‌دهد. این کنترل به طور پیش‌فرض در گوشه بالا سمت چپ نقشه ظاهر می‌شود.
• کنترل تمام صفحه (Fullscreen) گزینه‌ای برای باز کردن نقشه در حالت تمام صفحه ارائه می‌دهد. این کنترل به طور پیش‌فرض در دستگاه‌های دسکتاپ و موبایل فعال است. توجه: iOS از ویژگی تمام صفحه پشتیبانی نمی‌کند. بنابراین، کنترل تمام صفحه در دستگاه‌های iOS قابل مشاهده نیست.
• کنترل دوربین شامل کنترل‌های زوم و حرکت افقی است.
• کنترل نمای خیابان شامل یک آیکون Pegman است که می‌توان آن را روی نقشه کشید تا نمای خیابان فعال شود. این کنترل به طور پیش‌فرض در نزدیکی پایین سمت راست نقشه ظاهر می‌شود.
• کنترل چرخش (Rotate) ترکیبی از گزینه‌های کج کردن و چرخاندن را برای نقشه‌های حاوی تصاویر سه‌بعدی فراهم می‌کند. این کنترل به طور پیش‌فرض در نزدیکی پایین سمت راست نقشه ظاهر می‌شود. برای اطلاعات بیشتر به نمای کلی سه‌بعدی مراجعه کنید.
• کنترل Scale عنصر مقیاس نقشه را نمایش می‌دهد. این کنترل به طور پیش‌فرض غیرفعال است.
• کنترل میانبرهای صفحه کلید ، فهرستی از میانبرهای صفحه کلید را برای تعامل با نقشه نمایش می‌دهد.

شما مستقیماً به این کنترل‌های نقشه دسترسی ندارید یا آنها را تغییر نمی‌دهید. در عوض، فیلدهای MapOptions نقشه را تغییر می‌دهید که بر قابلیت مشاهده و نمایش کنترل‌ها تأثیر می‌گذارند. می‌توانید نمایش کنترل‌ها را پس از نمونه‌سازی نقشه خود (با MapOptions مناسب) تنظیم کنید یا با فراخوانی setOptions() برای تغییر گزینه‌های نقشه، یک نقشه را به صورت پویا تغییر دهید.

همه این کنترل‌ها به طور پیش‌فرض فعال نیستند. برای کسب اطلاعات در مورد رفتار پیش‌فرض رابط کاربری (و نحوه تغییر چنین رفتاری)، به رابط کاربری پیش‌فرض در زیر مراجعه کنید.

رابط کاربری پیش‌فرض

به طور پیش‌فرض، اگر نقشه خیلی کوچک باشد (200x200px)، تمام کنترل‌ها ناپدید می‌شوند. می‌توانید با تنظیم صریح قابل مشاهده بودن کنترل، این رفتار را لغو کنید. به افزودن کنترل‌ها به نقشه مراجعه کنید.

رفتار و ظاهر کنترل‌ها در دستگاه‌های موبایل و دسکتاپ یکسان است، به جز کنترل تمام‌صفحه (به رفتار شرح داده شده در فهرست کنترل‌ها مراجعه کنید).

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

رابط کاربری پیش‌فرض را غیرفعال کنید

شاید بخواهید دکمه‌های پیش‌فرض رابط کاربری API را به‌طور کامل غیرفعال کنید. برای انجام این کار، ویژگی disableDefaultUI نقشه (درون شیء MapOptions ) را روی true تنظیم کنید. این ویژگی هرگونه دکمه کنترل رابط کاربری را از API جاوا اسکریپت Maps غیرفعال می‌کند. با این حال، این ویژگی بر حرکات ماوس یا میانبرهای صفحه کلید روی نقشه پایه که به ترتیب توسط ویژگی‌های gestureHandling و keyboardShortcuts کنترل می‌شوند، تأثیری ندارد.

کد زیر دکمه‌های رابط کاربری را غیرفعال می‌کند:

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.ts

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.js

اضافه کردن کنترل‌ها به نقشه

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

برخی از کنترل‌ها به طور پیش‌فرض روی نقشه ظاهر می‌شوند در حالی که برخی دیگر تا زمانی که شما به طور خاص آنها را درخواست نکنید، ظاهر نمی‌شوند. اضافه کردن یا حذف کنترل‌ها از نقشه در فیلدهای شیء MapOptions زیر مشخص شده است که برای قابل مشاهده بودن آنها، مقدار آنها را روی true و برای پنهان کردن آنها، مقدار آنها را روی false تنظیم می‌کنید:

{
  cameraControl: boolean,
  mapTypeControl: boolean,
  scaleControl: boolean,
  streetViewControl: boolean,
  rotateControl: boolean,
  fullscreenControl: boolean
}

به طور پیش‌فرض، اگر نقشه کوچکتر از ۲۰۰x۲۰۰px باشد، تمام کنترل‌ها ناپدید می‌شوند. شما می‌توانید با تنظیم صریح کنترل به حالت قابل مشاهده، این رفتار را لغو کنید. برای مثال، جدول زیر نشان می‌دهد که آیا کنترل دوربین بر اساس اندازه نقشه و تنظیمات فیلد cameraControl قابل مشاهده است یا خیر:

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

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.ts

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.js

گزینه‌های کنترل

چندین کنترل قابل تنظیم هستند و به شما امکان می‌دهند رفتار یا ظاهر آنها را تغییر دهید. برای مثال، کنترل Map Type ممکن است به صورت یک نوار افقی یا یک منوی کشویی ظاهر شود.

این کنترل‌ها با تغییر فیلدهای گزینه‌های کنترلی مناسب در شیء MapOptions پس از ایجاد نقشه، اصلاح می‌شوند.

برای مثال، گزینه‌های تغییر کنترل Map Type در فیلد mapTypeControlOptions نشان داده شده‌اند. کنترل Map Type ممکن است در یکی از گزینه‌های style زیر ظاهر شود:

• google.maps.MapTypeControlStyle.HORIZONTAL_BAR آرایه‌ای از کنترل‌ها را به صورت دکمه‌هایی در یک نوار افقی، همانطور که در نقشه‌های گوگل نشان داده شده است، نمایش می‌دهد.
• google.maps.MapTypeControlStyle.DROPDOWN_MENU یک کنترل تک دکمه‌ای را نمایش می‌دهد که به شما امکان می‌دهد نوع نقشه را با استفاده از یک منوی کشویی انتخاب کنید.
• google.maps.MapTypeControlStyle.DEFAULT رفتار پیش‌فرض را نمایش می‌دهد که به اندازه صفحه نمایش بستگی دارد و ممکن است در نسخه‌های بعدی API تغییر کند.

توجه داشته باشید که اگر هر یک از گزینه‌های کنترل را تغییر می‌دهید، باید با تنظیم مقدار مناسب MapOptions به true ، آن کنترل را نیز به طور صریح فعال کنید. برای مثال، برای تنظیم یک کنترل Map Type برای نمایش سبک DROPDOWN_MENU ، از کد زیر در شیء MapOptions استفاده کنید:

  ...
  mapTypeControl: true,
  mapTypeControlOptions: {
    style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
  }
  ...

مثال زیر نحوه تغییر موقعیت و سبک پیش‌فرض کنترل‌ها را نشان می‌دهد.

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [
            google.maps.MapTypeId.ROADMAP,
            google.maps.MapTypeId.TERRAIN,
        ],
        position: google.maps.ControlPosition.TOP_CENTER,
    },
});
index.ts

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [
            google.maps.MapTypeId.ROADMAP,
            google.maps.MapTypeId.TERRAIN,
        ],
        position: google.maps.ControlPosition.TOP_CENTER,
    },
});
index.js

کنترل‌ها معمولاً هنگام ایجاد نقشه پیکربندی می‌شوند. با این حال، می‌توانید با فراخوانی متد setOptions() در Map و ارسال گزینه‌های کنترلی جدید، نحوه نمایش کنترل‌ها را به صورت پویا تغییر دهید.

اصلاح کنترل‌ها

شما هنگام ایجاد نقشه خود از طریق فیلدهای درون شیء MapOptions نقشه، نحوه نمایش یک کنترل را مشخص می‌کنید. این فیلدها در زیر نشان داده شده‌اند:

• cameraControl کنترل دوربین را که به کاربر امکان بزرگنمایی و حرکت در نقشه را می‌دهد، فعال/غیرفعال می‌کند. این کنترل به طور پیش‌فرض در همه نقشه‌ها قابل مشاهده است. فیلد cameraControlOptions علاوه بر این، CameraControlOptions مورد استفاده برای این کنترل را نیز مشخص می‌کند.
• mapTypeControl کنترل Map Type را فعال/غیرفعال می‌کند که به کاربر اجازه می‌دهد بین انواع نقشه (مانند نقشه و ماهواره) جابجا شود. به طور پیش‌فرض، این کنترل قابل مشاهده است و در گوشه بالا سمت چپ نقشه ظاهر می‌شود. فیلد mapTypeControlOptions علاوه بر این، MapTypeControlOptions مورد استفاده برای این کنترل را مشخص می‌کند.
• streetViewControl کنترل Pegman را فعال/غیرفعال می‌کند که به کاربر اجازه می‌دهد پانورامای نمای خیابان را فعال کند. به طور پیش‌فرض، این کنترل قابل مشاهده است و در نزدیکی پایین سمت راست نقشه ظاهر می‌شود. فیلد streetViewControlOptions علاوه بر این، StreetViewControlOptions را برای استفاده برای این کنترل مشخص می‌کند.
• rotateControl ظاهر کنترل Rotate را برای کنترل جهت تصاویر سه‌بعدی فعال/غیرفعال می‌کند. به‌طور پیش‌فرض، وجود این کنترل با وجود یا عدم وجود تصاویر سه‌بعدی برای نوع نقشه داده‌شده در بزرگنمایی و مکان فعلی تعیین می‌شود. می‌توانید با تنظیم rotateControlOptions نقشه برای مشخص کردن RotateControlOptions مورد استفاده، رفتار کنترل را تغییر دهید. این کنترل فقط در نقشه‌های پایه سه‌بعدی ظاهر می‌شود.
• scaleControl کنترل Scale را که مقیاس نقشه را ارائه می‌دهد، فعال/غیرفعال می‌کند. به طور پیش‌فرض، این کنترل قابل مشاهده نیست. وقتی فعال باشد، همیشه در گوشه پایین سمت راست نقشه ظاهر می‌شود. scaleControlOptions علاوه بر این، ScaleControlOptions را برای استفاده برای این کنترل مشخص می‌کند.
• fullscreenControl کنترلی را که نقشه را در حالت تمام صفحه باز می‌کند، فعال/غیرفعال می‌کند. به طور پیش‌فرض، این کنترل به طور پیش‌فرض در دستگاه‌های دسکتاپ و اندروید فعال است. وقتی فعال باشد، کنترل در نزدیکی سمت راست بالای نقشه ظاهر می‌شود. fullscreenControlOptions علاوه بر این، FullscreenControlOptions را برای استفاده برای این کنترل مشخص می‌کند.

توجه داشته باشید که می‌توانید گزینه‌هایی را برای کنترل‌هایی که در ابتدا غیرفعال می‌کنید، مشخص کنید.

موقعیت یابی کنترل

بیشتر گزینه‌های کنترلی حاوی یک ویژگی position (از نوع ControlPosition ) هستند که نشان می‌دهد کنترل در کجای نقشه قرار گیرد. موقعیت‌یابی این کنترل‌ها مطلق نیست. در عوض، API با جابجایی کنترل‌ها در اطراف عناصر نقشه موجود یا سایر کنترل‌ها، در محدوده محدودیت‌های داده شده (مانند اندازه نقشه)، آنها را هوشمندانه طرح‌بندی می‌کند.

دو نوع موقعیت کنترلی وجود دارد: قدیمی و منطقی. استفاده از مقادیر منطقی توصیه می‌شود تا بتوان به طور خودکار از هر دو زمینه طرح‌بندی چپ به راست (LTR) و راست به چپ (RTL) پشتیبانی کرد. به راهنمای مرجع مراجعه کنید .

جداول زیر موقعیت‌های کنترلی پشتیبانی‌شده در متن‌های چپ به راست و راست به چپ (LTR) را نشان می‌دهند.

برای تغییر حالت نقشه بین حالت‌های چپ به راست (LTR) و راست به چپ (RTL) روی برچسب‌ها کلیک کنید.

توجه داشته باشید که این موقعیت‌ها ممکن است با موقعیت‌های عناصر رابط کاربری که نمی‌توانید محل قرارگیری آنها را تغییر دهید (مانند حق چاپ و لوگوی گوگل) همزمان باشند. در این موارد، کنترل‌ها طبق منطق ذکر شده برای هر موقعیت جریان می‌یابند و تا حد امکان به موقعیت مشخص شده خود نزدیک می‌شوند. با توجه به طرح‌بندی‌های پیچیده، هیچ تضمینی وجود ندارد که کنترل‌ها با هم همپوشانی نداشته باشند، اگرچه API تلاش خواهد کرد تا آنها را هوشمندانه مرتب کند.

مثال زیر یک نقشه پایه را با تمام کنترل‌های فعال، در موقعیت‌های مختلف نشان می‌دهد.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: -28.643387, lng: 153.612224 },
      mapTypeControl: true,
      mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
        position: google.maps.ControlPosition.TOP_CENTER,
      },
      zoomControl: true,
      zoomControlOptions: {
        position: google.maps.ControlPosition.LEFT_CENTER,
      },
      scaleControl: true,
      streetViewControl: true,
      streetViewControlOptions: {
        position: google.maps.ControlPosition.LEFT_TOP,
      },
      fullscreenControl: true,
    }
  );
}

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

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: -28.643387, lng: 153.612224 },
    mapTypeControl: true,
    mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_CENTER,
    },
    zoomControl: true,
    zoomControlOptions: {
      position: google.maps.ControlPosition.LEFT_CENTER,
    },
    scaleControl: true,
    streetViewControl: true,
    streetViewControlOptions: {
      position: google.maps.ControlPosition.LEFT_TOP,
    },
    fullscreenControl: true,
  });
}

window.initMap = initMap;
index.js

کنترل‌های سفارشی

علاوه بر تغییر سبک و موقعیت کنترل‌های API موجود، می‌توانید کنترل‌های خودتان را برای مدیریت تعامل با کاربر ایجاد کنید. کنترل‌ها ویجت‌های ثابتی هستند که در موقعیت‌های مطلق روی نقشه شناور می‌شوند، برخلاف overlayها که با نقشه زیرین حرکت می‌کنند. اساساً، یک کنترل یک عنصر <div> است که موقعیت مطلقی روی نقشه دارد، رابط کاربری خاصی را به کاربر نمایش می‌دهد و تعامل با کاربر یا نقشه را معمولاً از طریق یک event handler مدیریت می‌کند.

برای ایجاد کنترل سفارشی خودتان، چند قانون لازم است. با این حال، دستورالعمل‌های زیر می‌توانند به عنوان بهترین روش عمل کنند:

• CSS مناسب برای عنصر(های) کنترلی که قرار است نمایش داده شود را تعریف کنید.
• تعامل با کاربر یا نقشه را از طریق کنترل‌کننده‌های رویداد برای تغییرات ویژگی‌های نقشه یا رویدادهای کاربر (برای مثال، رویدادهای 'click' ) مدیریت کنید.
• یک عنصر <div> برای نگهداری کنترل ایجاد کنید و این عنصر را به ویژگی controls مربوط به Map اضافه کنید.

در ادامه به هر یک از این نگرانی‌ها پرداخته شده است.

کنترل‌های سفارشی را رسم کنید

نحوه‌ی رسم کنترل به خودتان بستگی دارد. به‌طورکلی، توصیه می‌کنیم تمام نمایش کنترل خود را درون یک عنصر <div> قرار دهید تا بتوانید کنترل خود را به‌عنوان یک واحد مدیریت کنید. ما از این الگوی طراحی در نمونه‌های نشان داده‌شده در زیر استفاده خواهیم کرد.

طراحی کنترل‌های جذاب نیاز به دانشی از CSS و ساختار DOM دارد. مثال‌های کد زیر، افزودن یک کنترل سفارشی را با استفاده از HTML اعلانی و روش‌های برنامه‌نویسی نشان می‌دهند.

CSS اعلانی

سبک‌های CSS زیر ظاهری سازگار با کنترل‌های پیش‌فرض ارائه می‌دهند. از این سبک‌ها با هر دو مثال زیر استفاده کنید:

.streetview-toggle-button {
  align-items: center;
  background: white;
  border: none;
  border-radius: 2px;
  box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3);
  color: rgb(86, 86, 86);
  cursor: pointer;
  display: flex;
  font-family: Roboto, Arial, sans-serif;
  font-size: 18px;
  font-weight: 400;
  height: 40px;
  justify-content: center;
  margin: 10px 0;
  padding: 0 17px;
}

.streetview-toggle-button:hover {
  background: #f4f4f4;
  color: #000;
}

HTML اعلانی

این قطعه کدها نحوه ایجاد یک کنترل سفارشی را به صورت اعلانی نشان می‌دهند. در HTML، از یک DIV با شناسه container برای قرار دادن کنترل استفاده می‌شود؛ این DIV درون عنصر gmp-map قرار می‌گیرد و دکمه به DIV اضافه می‌شود. ویژگی slot روی control-inline-start-block-start تنظیم شده است تا کنترل در گوشه بالا سمت چپ نقشه قرار گیرد.

<gmp-map
  center="41.027748173921374, -92.41852445367961"
  zoom="13"
  map-id="DEMO_MAP_ID">
  <div id="container" slot="control-inline-start-block-start">
    <input type="button"
    id="streetview-toggle-button"
    class="button"
    value="Click this button" />
  </div>
</gmp-map>

در جاوا اسکریپت، getElementById() برای یافتن DIV و دکمه استفاده می‌شود، یک شنونده رویداد به دکمه اضافه می‌شود و دکمه به DIV الحاق می‌شود.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Get the control button from the HTML page.
const controlButton = document.getElementById("streetview-toggle-button");

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(controlButton);

جاوا اسکریپت برنامه‌نویسی‌شده

این قطعه کد، ایجاد یک کنترل دکمه را به صورت برنامه‌نویسی شده نشان می‌دهد. استایل‌های CSS در بالا تعریف شده‌اند.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Position the control in the top left corner of the map.
container.slot = "control-block-start-inline-start";

// Create the control.
const controlButton = document.createElement("button");
controlButton.classList.add("streetview-toggle-button");
controlButton.textContent = "Click this button";
controlButton.type = "button";

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(controlButton);

مدیریت رویدادها از کنترل‌های سفارشی

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

برای پاسخ به ورودی کاربر، از addEventListener() استفاده کنید که رویدادهای DOM پشتیبانی‌شده را مدیریت می‌کند. قطعه کد زیر یک شنونده برای رویداد 'click' مرورگر اضافه می‌کند. توجه داشته باشید که این رویداد از DOM دریافت می‌شود، نه از نقشه.

// Setup the click event listener: set the map to center on Chicago
var chicago = {lat: 41.850, lng: -87.650};

controlButton.addEventListener('click', () => {
  map.setCenter(chicago);
});

کنترل‌های سفارشی را در دسترس قرار دهید

برای اطمینان از اینکه کنترل‌ها رویدادهای صفحه کلید را دریافت می‌کنند و به درستی برای خوانندگان صفحه نمایش نمایش داده می‌شوند:

• همیشه از عناصر HTML بومی برای دکمه‌ها، عناصر فرم و برچسب‌ها استفاده کنید. فقط از یک عنصر DIV به عنوان ظرفی برای نگهداری کنترل‌های بومی استفاده کنید؛ هرگز از یک DIV به عنوان یک عنصر رابط کاربری تعاملی استفاده مجدد نکنید.
• در صورت لزوم، از عنصر label ، ویژگی title یا ویژگی aria-label برای ارائه اطلاعات در مورد یک عنصر رابط کاربری استفاده کنید.

کنترل‌های سفارشی موقعیت

از ویژگی slot برای تعیین موقعیت کنترل‌های سفارشی و مشخص کردن موقعیت کنترل مورد نیاز استفاده کنید. برای اطلاعات بیشتر در مورد این موقعیت‌ها، به بخش «موقعیت‌یابی کنترل» در بالا مراجعه کنید.

هر ControlPosition یک MVCArray از کنترل‌های نمایش داده شده در آن موقعیت را ذخیره می‌کند. در نتیجه، وقتی کنترل‌هایی به آن موقعیت اضافه یا حذف می‌شوند، API کنترل‌ها را بر اساس آن به‌روزرسانی می‌کند.

کد زیر یک کنترل سفارشی جدید ایجاد می‌کند (سازنده‌ی آن نمایش داده نشده است) و آن را به نقشه در موقعیت BLOCK_START_INLINE_END (بالا سمت راست در متن LTR) اضافه می‌کند.

// Create a DIV to attach the control UI to the Map.
const centerControlDiv = document.createElement("div");

// Create the control. This code calls a function that
// creates a new instance of a button control.
const centerControl = createCenterControl(map);

// Append the control to the DIV.
centerControlDiv.appendChild(centerControl);

// Push the control to the BLOCK_START_INLINE_END position.
innerMap.controls[google.maps.ControlPosition.BLOCK_START_INLINE_END].push(centerControlDiv);

برای تنظیم موقعیت یک کنترل سفارشی به صورت اعلانی، ویژگی slot را در HTML تنظیم کنید:

<gmp-map center="30.72851568848909, -81.54675994068873" zoom="12">
  <div slot="control-block-start-inline-end">
    <!-- Control HTML -->
  </div>
</gmp-map>

یک مثال کنترل سفارشی

کنترل زیر ساده است (هرچند خیلی مفید نیست) و الگوهای نشان داده شده در بالا را ترکیب می‌کند. این کنترل با قرار دادن نقشه در مرکز یک مکان پیش‌فرض خاص، به رویدادهای 'click' DOM پاسخ می‌دهد:

let map: google.maps.Map;

const chicago = { lat: 41.85, lng: -87.65 };

/**
 * Creates a control that recenters the map on Chicago.
 */
 function createCenterControl(map) {
  const controlButton = document.createElement('button');

  // Set CSS for the control.
  controlButton.style.backgroundColor = '#fff';
  controlButton.style.border = '2px solid #fff';
  controlButton.style.borderRadius = '3px';
  controlButton.style.boxShadow = '0 2px 6px rgba(0,0,0,.3)';
  controlButton.style.color = 'rgb(25,25,25)';
  controlButton.style.cursor = 'pointer';
  controlButton.style.fontFamily = 'Roboto,Arial,sans-serif';
  controlButton.style.fontSize = '16px';
  controlButton.style.lineHeight = '38px';
  controlButton.style.margin = '8px 0 22px';
  controlButton.style.padding = '0 5px';
  controlButton.style.textAlign = 'center';

  controlButton.textContent = 'Center Map';
  controlButton.title = 'Click to recenter the map';
  controlButton.type = 'button';

  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener('click', () => {
    map.setCenter(chicago);
  });

  return controlButton;
}

function initMap() {
  map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control.
  const centerControlDiv = document.createElement('div');
  // Create the control.
  const centerControl = createCenterControl(map);
  // Append the control to the DIV.
  centerControlDiv.appendChild(centerControl);

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

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

let map;
const chicago = { lat: 41.85, lng: -87.65 };

/**
 * Creates a control that recenters the map on Chicago.
 */
function createCenterControl(map) {
  const controlButton = document.createElement("button");

  // Set CSS for the control.
  controlButton.style.backgroundColor = "#fff";
  controlButton.style.border = "2px solid #fff";
  controlButton.style.borderRadius = "3px";
  controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)";
  controlButton.style.color = "rgb(25,25,25)";
  controlButton.style.cursor = "pointer";
  controlButton.style.fontFamily = "Roboto,Arial,sans-serif";
  controlButton.style.fontSize = "16px";
  controlButton.style.lineHeight = "38px";
  controlButton.style.margin = "8px 0 22px";
  controlButton.style.padding = "0 5px";
  controlButton.style.textAlign = "center";
  controlButton.textContent = "Center Map";
  controlButton.title = "Click to recenter the map";
  controlButton.type = "button";
  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener("click", () => {
    map.setCenter(chicago);
  });
  return controlButton;
}

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control.
  const centerControlDiv = document.createElement("div");
  // Create the control.
  const centerControl = createCenterControl(map);

  // Append the control to the DIV.
  centerControlDiv.appendChild(centerControl);
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

window.initMap = initMap;
index.js

اضافه کردن وضعیت به کنترل‌ها

کنترل‌ها همچنین می‌توانند وضعیت را ذخیره کنند. مثال زیر مشابه مثال قبلی است، اما کنترل شامل یک دکمه "تنظیم خانه" اضافی است که کنترل را برای نمایش یک مکان خانه جدید تنظیم می‌کند. ما این کار را با ایجاد یک ویژگی home_ در کنترل انجام می‌دهیم تا این وضعیت را ذخیره کرده و getterها و setterها را برای آن وضعیت فراهم کنیم.

let map: google.maps.Map;

const chicago: google.maps.LatLngLiteral = { lat: 41.85, lng: -87.65 };

/**
 * The CenterControl adds a control to the map that recenters the map on
 * Chicago.
 */
class CenterControl {
  private map_: google.maps.Map;
  private center_: google.maps.LatLng;
  constructor(
    controlDiv: HTMLElement,
    map: google.maps.Map,
    center: google.maps.LatLngLiteral
  ) {
    this.map_ = map;
    // Set the center property upon construction
    this.center_ = new google.maps.LatLng(center);
    controlDiv.style.clear = "both";

    // Set CSS for the control border
    const goCenterUI = document.createElement("button");

    goCenterUI.id = "goCenterUI";
    goCenterUI.title = "Click to recenter the map";
    controlDiv.appendChild(goCenterUI);

    // Set CSS for the control interior
    const goCenterText = document.createElement("div");

    goCenterText.id = "goCenterText";
    goCenterText.innerHTML = "Center Map";
    goCenterUI.appendChild(goCenterText);

    // Set CSS for the setCenter control border
    const setCenterUI = document.createElement("button");

    setCenterUI.id = "setCenterUI";
    setCenterUI.title = "Click to change the center of the map";
    controlDiv.appendChild(setCenterUI);

    // Set CSS for the control interior
    const setCenterText = document.createElement("div");

    setCenterText.id = "setCenterText";
    setCenterText.innerHTML = "Set Center";
    setCenterUI.appendChild(setCenterText);

    // Set up the click event listener for 'Center Map': Set the center of
    // the map
    // to the current center of the control.
    goCenterUI.addEventListener("click", () => {
      const currentCenter = this.center_;

      this.map_.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterUI.addEventListener("click", () => {
      const newCenter = this.map_.getCenter()!;

      if (newCenter) {
        this.center_ = newCenter;
      }
    });
  }
}

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control and call the CenterControl()
  // constructor passing in this DIV.
  const centerControlDiv = document.createElement("div");
  const control = new CenterControl(centerControlDiv, map, chicago);

  // @ts-ignore
  centerControlDiv.index = 1;
  centerControlDiv.style.paddingTop = "10px";
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

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

let map;
const chicago = { lat: 41.85, lng: -87.65 };

/**
 * The CenterControl adds a control to the map that recenters the map on
 * Chicago.
 */
class CenterControl {
  map_;
  center_;
  constructor(controlDiv, map, center) {
    this.map_ = map;
    // Set the center property upon construction
    this.center_ = new google.maps.LatLng(center);
    controlDiv.style.clear = "both";

    // Set CSS for the control border
    const goCenterUI = document.createElement("button");

    goCenterUI.id = "goCenterUI";
    goCenterUI.title = "Click to recenter the map";
    controlDiv.appendChild(goCenterUI);

    // Set CSS for the control interior
    const goCenterText = document.createElement("div");

    goCenterText.id = "goCenterText";
    goCenterText.innerHTML = "Center Map";
    goCenterUI.appendChild(goCenterText);

    // Set CSS for the setCenter control border
    const setCenterUI = document.createElement("button");

    setCenterUI.id = "setCenterUI";
    setCenterUI.title = "Click to change the center of the map";
    controlDiv.appendChild(setCenterUI);

    // Set CSS for the control interior
    const setCenterText = document.createElement("div");

    setCenterText.id = "setCenterText";
    setCenterText.innerHTML = "Set Center";
    setCenterUI.appendChild(setCenterText);
    // Set up the click event listener for 'Center Map': Set the center of
    // the map
    // to the current center of the control.
    goCenterUI.addEventListener("click", () => {
      const currentCenter = this.center_;

      this.map_.setCenter(currentCenter);
    });
    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterUI.addEventListener("click", () => {
      const newCenter = this.map_.getCenter();

      if (newCenter) {
        this.center_ = newCenter;
      }
    });
  }
}

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control and call the CenterControl()
  // constructor passing in this DIV.
  const centerControlDiv = document.createElement("div");
  const control = new CenterControl(centerControlDiv, map, chicago);

  // @ts-ignore
  centerControlDiv.index = 1;
  centerControlDiv.style.paddingTop = "10px";
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

window.initMap = initMap;
index.js