Places UI Kit : یک کتابخانه آماده برای استفاده که فضایی را برای سفارشی‌سازی و توسعه کم کد فراهم می‌کند. آن را امتحان کنید و نظرات خود را در مورد تجربه کیت UI خود به اشتراک بگذارید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

رویداد

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

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

رویدادهای میانای کاربر

جاوا اسکریپت در مرورگر رویدادمحور است، یعنی جاوا اسکریپت با تولید رویدادها به تعاملات پاسخ می‌دهد و انتظار دارد برنامه‌ای به رویدادهای جالب گوش دهد. دو نوع رویداد وجود دارد:

رویدادهای کاربر (مانند رویدادهای «کلیک» موشواره) از DOM به Maps JavaScript API منتشر می‌شوند. این رویدادها جدا و متمایز از رویدادهای استاندارد DOM هستند.
اعلان‌های تغییر وضعیت MVC تغییرات را در اشیاء Maps JavaScript API منعکس می‌کنند و بااستفاده از قرارداد property_changed نام‌گذاری می‌شوند.

هر شیء Maps JavaScript API تعدادی رویداد نام‌گذاری‌شده را صادر می‌کند. برنامه‌هایی که به رویدادهای خاصی علاقه‌مند هستند، شنوندگان رویداد جاوا اسکریپت را برای آن رویدادها ثبت می‌کنند و هنگام دریافت آن رویدادها، با فراخوانی addListener() برای ثبت کنترل‌کننده‌های رویداد در شیء، کد را اجرا می‌کنند.

نمونه زیر نشان می‌دهد که کدام رویدادها توسط google.maps.Map هنگام تعامل با نقشه راه‌اندازی می‌شوند.

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

رویدادهای واسط کاربر

برخی‌از اشیاء در Maps JavaScript API برای پاسخ دادن به رویدادهای کاربر، مانند رویدادهای موشواره یا صفحه‌کلید، طراحی شده‌اند. برای مثال، این‌ها برخی‌از رویدادهای کاربر هستند که شیء google.maps.marker.AdvancedMarkerElement می‌تواند به آن‌ها گوش دهد:

'gmp-click'
'gmp-drag'
'gmp-dragstart'
'gmp-dragend'

برای مشاهده فهرست کامل، به کلاس AdvancedMarkerElement مراجعه کنید. These automatically added events are not visible to people with whom a calendar is shared. They are only visible to calendar owners. Sharing settings can be changed in Google Calendar settings or in individual events. Persian: English: These events may look like standard DOM events, but they are actually part of the Maps JavaScript API. Because different browsers implement different DOM event models, the Maps JavaScript API provides these mechanisms to listen for and respond to DOM events without needing to handle the various cross-browser peculiarities. این رویدادها معمولاً آرگومان‌هایی را نیز در رویداد ارسال می‌کنند که نشان‌دهنده برخی حالت‌های رابط کاربری (مانند موقعیت موشواره) است.

تغییرات وضعیت MVC

اشیاء MVC معمولاً حاوی وضعیت هستند. هرگاه ویژگی شیء تغییر کند، Maps JavaScript API رویدادی را فعال می‌کند که نشان می‌دهد ویژگی تغییر کرده است. برای مثال، وقتی سطح بزرگ‌نمایی نقشه تغییر می‌کند، میانای برنامه‌سازی کاربردی رویداد zoom_changed را در نقشه فعال می‌کند. می‌توانید با فراخوانی addListener()، این تغییرات وضعیت را رهگیری کنید تا گرداننده‌های رویداد را نیز در شیء ثبت کنید.

رویدادهای کاربر و تغییرات وضعیت MVC ممکن است مشابه به‌نظر برسند، اما باید در کدتان با آن‌ها به‌طور متفاوتی رفتار کنید. برای مثال، رویدادهای MVC ورودی‌ها را در رویداد خود ارسال نمی‌کنند. با فراخوانی روش getProperty مناسب در آن شیء، ویژگی‌ای را که در تغییر وضعیت MVC تغییر کرده است بررسی کنید.

رویدادهای نام کاربری

برای ثبت‌نام برای اعلان‌های رویداد، از addListener() گرداننده رویداد استفاده کنید. این روش رویدادی را برای گوش دادن و تابعی را برای فراخوانی هنگام وقوع رویداد مشخص‌شده دریافت می‌کند.

مثال: رویدادهای نقشه و نشانگر

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

TypeScript

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

    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map')!;

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

    const originalPosition = new LatLng(mapElement.center!);

    const marker = new AdvancedMarkerElement({
        position: originalPosition,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });

    innerMap.addListener('center_changed', () => {
        // 3 seconds after the center of the map has changed,
        // pan back to the marker.
        window.setTimeout(() => {
            innerMap.panTo(originalPosition);
        }, 3000);
    });

    // Zoom in when the marker is clicked.
    marker.addEventListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(originalPosition);
    });
}

void init();index.ts

JavaScript

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

    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map');

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

    const originalPosition = new LatLng(mapElement.center);

    const marker = new AdvancedMarkerElement({
        position: originalPosition,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });

    innerMap.addListener('center_changed', () => {
        // 3 seconds after the center of the map has changed,
        // pan back to the marker.
        window.setTimeout(() => {
            innerMap.panTo(originalPosition);
        }, 3000);
    });

    // Zoom in when the marker is clicked.
    marker.addEventListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(originalPosition);
    });
}

void init();index.js

مشاهده نمونه

نکته: اگر می‌خواهید تغییری را در نمای هدف تشخیص دهید، حتماً از رویداد bounds_changed خاص به‌جای رویدادهای تشکیل‌دهنده zoom_changed و center_changed استفاده کنید. چون Maps JavaScript API این رویدادهای اخیر را به‌طور مستقل فعال می‌کند، getBounds() ممکن است نتایج مفیدی را تا زمانی که نمای هدف به‌طور معتبر تغییر نکرده باشد گزارش نکند. اگر می‌خواهید getBounds() پس‌از چنین رویدادی، حتماً درعوض به رویداد bounds_changed گوش کنید.

مثال: رویدادهای ویرایش و کشیدن شکل

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

مشاهده نمونه (rectangle-event.html)

دسترسی به متغیرهای مستقل در رویدادهای واسط کاربر

رویدادهای میانای کاربر در Maps JavaScript API معمولاً یک شناسه رویداد را ارسال می‌کنند که شنونده رویداد می‌تواند به آن دسترسی داشته باشد و وضعیت میانای کاربر را هنگام وقوع رویداد ثبت کند. برای مثال، رویداد 'click' UI معمولاً MouseEvent حاوی ویژگی latLng را که نشان‌دهنده مکان کلیک‌شده روی نقشه است ارسال می‌کند. توجه داشته باشید که این رفتار مختص رویدادهای UI است؛ تغییرات وضعیت MVC آرگومان‌ها را در رویدادهای خود منتقل نمی‌کنند.

می‌توانید به آرگومان‌های رویداد در شنونده رویداد دسترسی داشته باشید، همان‌طور که به ویژگی‌های یک شیء دسترسی دارید. مثال زیر یک شنونده رویداد برای نقشه اضافه می‌کند و وقتی کاربر روی نقشه کلیک می‌کند، نشانگری در مکان کلیک‌شده ایجاد می‌کند.

TypeScript

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

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

    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (!event.latLng) return;
        new AdvancedMarkerElement({
            position: event.latLng,
            map: innerMap,
        });
        innerMap.panTo(event.latLng);
    });
}

void init();index.ts

JavaScript

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

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

    innerMap.addListener('click', (event) => {
        if (!event.latLng) return;
        new AdvancedMarkerElement({
            position: event.latLng,
            map: innerMap,
        });
        innerMap.panTo(event.latLng);
    });
}

void init();index.js

مشاهده نمونه

استفاده از بستارها در شنوندگان رویداد

هنگام اجرای شنونده رویداد، اغلب سودمند است که هم داده‌های خصوصی و هم داده‌های پایدار به شیء پیوست شوند. جاوا اسکریپت از داده‌های نمونه «خصوصی» پشتیبانی نمی‌کند، اما از بستارها پشتیبانی می‌کند که به توابع داخلی اجازه می‌دهد به متغیرهای خارجی دسترسی داشته باشند. بستارها در شنوندگان رویداد برای دسترسی به متغیرهایی که معمولاً به اشیایی که رویدادها در آن‌ها رخ می‌دهند متصل نیستند، مفید هستند.

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

TypeScript

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

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

    const bounds: google.maps.LatLngBoundsLiteral = {
        north: -25.363882,
        south: -31.203405,
        east: 131.044922,
        west: 125.244141,
    };

    // Display the area between the location southWest and northEast.
    innerMap.fitBounds(bounds);

    // Add 5 markers to map at random locations.
    // For each of these markers, give them a title with their index, and when
    // they are clicked they should open an infoWindow with text from a secret
    // message.
    const secretMessages = ['This', 'is', 'the', 'secret', 'message'];
    const lngSpan = bounds.east - bounds.west;
    const latSpan = bounds.north - bounds.south;

    for (const secretMessage of secretMessages) {
        const marker = new AdvancedMarkerElement({
            position: {
                lat: bounds.south + latSpan * Math.random(),
                lng: bounds.west + lngSpan * Math.random(),
            },
            map: innerMap,
            gmpClickable: true,
        });

        void attachSecretMessage(marker, secretMessage);
    }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
async function attachSecretMessage(
    marker: google.maps.marker.AdvancedMarkerElement,
    secretMessage: string
) {
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const infoWindow = new InfoWindow({
        content: secretMessage,
    });

    marker.addEventListener('gmp-click', () => {
        infoWindow.open(marker.map, marker);
    });
}

void init();index.ts

JavaScript

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

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

    const bounds = {
        north: -25.363882,
        south: -31.203405,
        east: 131.044922,
        west: 125.244141,
    };

    // Display the area between the location southWest and northEast.
    innerMap.fitBounds(bounds);

    // Add 5 markers to map at random locations.
    // For each of these markers, give them a title with their index, and when
    // they are clicked they should open an infoWindow with text from a secret
    // message.
    const secretMessages = ['This', 'is', 'the', 'secret', 'message'];
    const lngSpan = bounds.east - bounds.west;
    const latSpan = bounds.north - bounds.south;

    for (const secretMessage of secretMessages) {
        const marker = new AdvancedMarkerElement({
            position: {
                lat: bounds.south + latSpan * Math.random(),
                lng: bounds.west + lngSpan * Math.random(),
            },
            map: innerMap,
            gmpClickable: true,
        });

        void attachSecretMessage(marker, secretMessage);
    }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
async function attachSecretMessage(marker, secretMessage) {
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const infoWindow = new InfoWindow({
        content: secretMessage,
    });

    marker.addEventListener('gmp-click', () => {
        infoWindow.open(marker.map, marker);
    });
}

void init();index.js

مشاهده نمونه

دریافت کردن و تنظیم کردن ویژگی‌ها در «مدیران رویداد»

هیچ‌کدام از رویدادهای تغییر وضعیت MVC در سیستم رویداد Maps JavaScript API، هنگام راه‌اندازی رویداد، آرگومان‌ها را ارسال نمی‌کنند. (رویدادهای کاربر آرگومان‌هایی را ارسال می‌کنند که می‌توان آن‌ها را بررسی کرد.) اگر لازم است ویژگی‌ای را در تغییر وضعیت MVC بررسی کنید، باید صریحاً روش getProperty() مناسب را در آن شیء فراخوانی کنید. این بازرسی همیشه وضعیت فعلی شیء MVC را بازیابی می‌کند، که ممکن است وضعیتی نباشد که رویداد برای اولین‌بار راه‌اندازی شده است.

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

مثال زیر نشان می‌دهد که چگونه می‌توان یک کنترل‌کننده رویداد را برای پاسخ به رویدادهای بزرگ‌نمایی با نمایش یک پنجره اطلاعاتی که آن سطح را نشان می‌دهد، راه‌اندازی کرد.

TypeScript

async function init() {
    // Request needed libraries.
    const { InfoWindow } = await google.maps.importLibrary('maps');

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

    const infoWindow = new InfoWindow({
        content: 'Change the zoom level',
        position: mapElement.center,
    });

    infoWindow.open(innerMap);

    innerMap.addListener('zoom_changed', () => {
        infoWindow.setContent('Zoom: ' + innerMap.getZoom()!);
    });
}

void init();index.ts

JavaScript

async function init() {
    // Request needed libraries.
    const { InfoWindow } = await google.maps.importLibrary('maps');

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

    const infoWindow = new InfoWindow({
        content: 'Change the zoom level',
        position: mapElement.center,
    });

    infoWindow.open(innerMap);

    innerMap.addListener('zoom_changed', () => {
        infoWindow.setContent('Zoom: ' + innerMap.getZoom());
    });
}

void init();index.js

مشاهده نمونه

برداشتن شنوندگان رویداد

برای برداشتن شنونده رویداد خاص، باید به متغیری اختصاص داده شده باشد. سپس می‌توانید removeListener() را فراخوانی کنید، و نام متغیری را که شنونده به آن اختصاص داده شده است ارسال کنید.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

برای برداشتن همه شنوندگان از یک نمونه خاص، clearInstanceListeners() را فراخوانی کنید و نام نمونه را ارسال کنید.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

برای برداشتن همه شنوندگان برای نوع رویداد خاص برای نمونه خاص، clearListeners() را فراخوانی کنید و نام نمونه و نام رویداد را ارسال کنید.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

برای اطلاعات بیشتر، به اسناد مرجع برای فضای نام google.maps.event مراجعه کنید.

گوش دادن به خطاهای اصالت‌سنجی

اگر می‌خواهید به‌صورت برنامه‌نویسی‌شده عدم موفقیت در اصالت‌سنجی را شناسایی کنید (برای مثال برای ارسال خودکار فانوسقه) می‌توانید تابع بازخوانی آماده کنید. اگر تابع سراسری زیر تعریف شده باشد، درصورت ناموفق بودن اصالت‌سنجی، فراخوانده می‌شود. function gm_authFailure() { /* Code */ };

در TypeScript، ممکن است لازم باشد تابع را به دامنه سراسری اضافه کنید، همان‌طور که در زیر نشان داده شده است:

// Define the callback function.
window.gm_authFailure = () => {
  console.error("Google Maps failed to authenticate.");
  /* Code */
};

// Add gm_authFailure to the global scope.
declare global {
  interface Window {
    gm_authFailure?: () => void;
  }
}
export {};

رویداد با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

رویدادهای میانای کاربر

رویدادهای واسط کاربر

تغییرات وضعیت MVC

رویدادهای نام کاربری

مثال: رویدادهای نقشه و نشانگر

TypeScript

JavaScript

مثال: رویدادهای ویرایش و کشیدن شکل

دسترسی به متغیرهای مستقل در رویدادهای واسط کاربر

TypeScript

JavaScript

استفاده از بستارها در شنوندگان رویداد

TypeScript

JavaScript

دریافت کردن و تنظیم کردن ویژگی‌ها در «مدیران رویداد»

TypeScript

JavaScript

برداشتن شنوندگان رویداد

گوش دادن به خطاهای اصالت‌سنجی

رویداد