کنترل ها

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

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

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

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

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

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

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

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

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

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

به‌طور پیش‌فرض، اگر نقشه خیلی کوچک باشد (۲۰۰×۲۰۰ پیکسل)، همه کنترل‌ها ناپدید می‌شوند. می‌توانید با تنظیم صریح کنترل برای نمایان بودن، این رفتار را لغو کنید. افزودن کنترل‌ها به نقشه را ببینید.

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

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

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

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

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

TypeScript

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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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
}

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

اندازه نقشه	cameraControl	نمایان است؟
همه	false	نه
همه	true	بله
>= ۲۰۰×۲۰۰ پیکسل	undefined	بله
< ۲۰۰×۲۰۰ پیکسل	undefined	نه

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

TypeScript

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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

مشاهده نمونه

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

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

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

برای مثال، گزینه‌های تغییر کنترل «نوع نقشه» در فیلد mapTypeControlOptions نشان داده شده است. کنترل «نوع نقشه» ممکن است در یکی از گزینه‌های style زیر نشان داده شود:

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

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

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

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

TypeScript

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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

مشاهده نمونه

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

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

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

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

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

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

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

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

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

جایگاه‌های چپ به راست

موقعیت	ثابت منطقی (توصیه‌شده)	ثابت قدیمی
بالا سمت راست	BLOCK_START_INLINE_START	TOP_LEFT
بالا وسط	BLOCK_START_INLINE_CENTER	TOP_CENTER
بالا سمت راست	BLOCK_START_INLINE_END	TOP_RIGHT
بالا سمت چپ	INLINE_START_BLOCK_START	LEFT_TOP
چپ مرکز	INLINE_START_BLOCK_CENTER	LEFT_CENTER
پایین سمت چپ	INLINE_START_BLOCK_END	LEFT_BOTTOM
بالا سمت راست	INLINE_END_BLOCK_START	RIGHT_TOP
مرکز راست	INLINE_END_BLOCK_CENTER	RIGHT_CENTER
پایین سمت راست	INLINE_END_BLOCK_END	RIGHT_BOTTOM
پایین سمت چپ	BLOCK_END_INLINE_START	BOTTOM_LEFT
پایین وسط	BLOCK_END_INLINE_CENTER	BOTTOM_CENTER
پایین سمت راست	BLOCK_END_INLINE_END	BOTTOM_RIGHT

جایگاه‌های راست به چپ

موقعیت	ثابت منطقی (توصیه‌شده)	ثابت قدیمی
بالا سمت راست	BLOCK_START_INLINE_START	TOP_RIGHT
بالا وسط	BLOCK_START_INLINE_CENTER	TOP_CENTER
بالا سمت راست	BLOCK_START_INLINE_END	TOP_LEFT
بالا سمت راست	INLINE_START_BLOCK_START	RIGHT_TOP
مرکز راست	INLINE_START_BLOCK_CENTER	RIGHT_CENTER
پایین سمت راست	INLINE_START_BLOCK_END	RIGHT_BOTTOM
بالا سمت چپ	INLINE_END_BLOCK_START	LEFT_TOP
چپ مرکز	INLINE_END_BLOCK_CENTER	LEFT_CENTER
پایین سمت چپ	INLINE_END_BLOCK_END	LEFT_BOTTOM
پایین سمت راست	BLOCK_END_INLINE_START	BOTTOM_RIGHT
پایین وسط	BLOCK_END_INLINE_CENTER	BOTTOM_CENTER
پایین سمت چپ	BLOCK_END_INLINE_END	BOTTOM_LEFT

روی برچسب‌ها کلیک کنید تا نقشه بین حالت‌های چپ‌به‌راست و راست‌به‌چپ جابه‌جا شود.

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

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

TypeScript

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

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

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

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

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

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

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.js

مشاهده نمونه

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

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

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

• 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 از کنترل‌های نمایش‌داده‌شده در آن جایگاه را ذخیره می‌کند. درنتیجه، وقتی کنترل‌ها به موقعیت اضافه یا از آن برداشته می‌شوند، میانای برنامه‌سازی کاربردی کنترل‌ها را به‌طور مقتضی به‌روز می‌کند.

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

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

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

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

TypeScript

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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

توجه: جاوا اسکریپت از قطعه TypeScript کامپایل شده است.

مشاهده نمونه

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

کنترل‌ها ممکن است وضعیت را نیز ذخیره کنند. مثال زیر مشابه مثالی است که قبلاً نشان داده شد، اما این کنترل حاوی دکمه اضافی «تنظیم خانه» است که کنترل را برای نمایش مکان خانه جدید تنظیم می‌کند. این کار را با ایجاد یک home_ ویژگی در کنترل برای ذخیره این حالت و ارائه گیرنده‌ها و تنظیم‌کننده‌ها برای آن حالت انجام می‌دهیم.

TypeScript

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

let center: google.maps.LatLngLiteral | google.maps.LatLng = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById(
        'btnCenterMap'
    ) as HTMLInputElement;
    const setCenterButton = document.getElementById(
        'btnSetCenter'
    ) as HTMLInputElement;

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

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

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

let center = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById('btnCenterMap');
    const setCenterButton = document.getElementById('btnSetCenter');

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

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

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.js

مشاهده نمونه