Элементы управления

Обзор элементов управления

Карты в Maps JavaScript API содержат элементы графического интерфейса, позволяющие пользователям взаимодействовать с картой. Они известны как элементы управления, и вы можете добавлять их в свое приложение. Однако это необязательно – если вы используете Maps JavaScript API, он будет контролировать поведение всех элементов управления.

На следующей карте показан набор элементов управления по умолчанию, доступный в Maps JavaScript API.

По часовой стрелке, начиная с левого верхнего угла: "Тип карты", "Полноэкранный режим", "Камера", "Просмотр улиц", "Быстрые клавиши".

Ниже приведен список всех элементов управления, которые вы можете использовать на своих картах.

• Тип карты – раскрывающийся список или горизонтальная кнопка для выбора типа карты (ROADMAP, SATELLITE, HYBRID или TERRAIN). По умолчанию располагается в верхнем левом углу карты.
• Полный экран – открывает карту в полноэкранном режиме. В версиях для компьютеров и мобильных устройств этот элемент включен по умолчанию. Примечание. Полноэкранный режим не поддерживается на устройствах iOS, По этой причине элемент управления для перехода в полноэкранный режим на устройствах iOS не отображается.
• В управлении камерой есть элементы управления масштабированием и панорамированием.
• Просмотр улиц – значок человечка, который можно перетащить на карту, чтобы открыть Просмотр улиц. По умолчанию этот элемент управления находится в правом нижнем углу карты.
• Ориентация – комбинация настроек наклона и ориентации. Действует, если для карты доступны 3D-изображения. По умолчанию этот элемент можно найти рядом с правым нижним углом карты. Подробнее о 3D-режиме…
• Линейка масштаба – по умолчанию этот элемент управления отключен.
• Быстрые клавиши – список клавиатурных сокращений для взаимодействия с картой.

Получить прямой доступ к элементам управления (в том числе для их модификации) нельзя. Однако вы можете изменять поля карты MapOptions, которые отвечают за видимость и представление элементов управления. Визуальное представление элементов управления можно задавать при создании экземпляров карты (параметры MapOptions) или изменять динамически через вызов настроек карты setOptions().

Не все эти элементы управления включены по умолчанию. Подробнее о поведении по умолчанию и возможностях его изменения…

Пользовательский интерфейс по умолчанию

По умолчанию, если размер карты слишком мал (200 х 200 пикс.), никакие элементы управления на ней не показываются. Это поведение можно изменить, явно указав, что элементы должны быть видны. Дополнительную информацию можно найти в разделе Как добавить элементы управления на карту.

Поведение и внешний вид элементов управления одинаковы для мобильных устройств и компьютеров, за исключением перехода в полноэкранный режим (см. описание в списке элементов управления).

Кроме того, на всех устройствах по умолчанию включена обработка команд клавиатуры.

Отключение пользовательского интерфейса по умолчанию

Вы можете полностью отключить кнопки, заданные API по умолчанию, установив для свойства карты disableDefaultUI (внутри объекта MapOptions) значение true. Это свойство отключает в Maps JavaScript API все кнопки элементов управления пользовательского интерфейса. не затрагивая при этом жесты мыши и быстрые клавиши (контролируются свойствами 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
}

По умолчанию, если размер карты слишком мал (200 х 200 пикс.), никакие элементы управления на ней не показываются. Это поведение можно изменить, явно указав, что элементы должны быть видны. Например, следующая таблица показывает, будет ли элемент управления камерой доступен на карте в зависимости от размера карты и значения в поле cameraControl.

В следующем примере показано, как скрыть элемент управления камерой и добавить линейку масштаба. Отметим, что здесь мы не отключаем интерфейс по умолчанию напрямую, а меняем его поведение.

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

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

Параметры элементов управления

Некоторые элементы управления можно настраивать, изменяя их поведение и внешний вид. Например, элемент Тип карты может иметь форму горизонтальной полосы или раскрывающегося меню.

Изменить эти элементы управления можно с помощью параметров в объекте MapOptions при создании карты.

Например, параметры для изменения типа карты указаны в поле mapTypeControlOptions. Элемент выбора типа карты можно задать одним из следующих вариантов переменной style:

• google.maps.MapTypeControlStyle.HORIZONTAL_BAR – кнопки на горизонтальной панели, как в Google Картах.
• google.maps.MapTypeControlStyle.DROPDOWN_MENU – одна кнопка, где тип карты можно выбрать из раскрывающегося меню.
• google.maps.MapTypeControlStyle.DEFAULT отображает режим работы по умолчанию, который зависит от размера экрана и может измениться в будущих версиях API.

Учтите, что при изменении параметров элемента управления этот элемент нужно явным образом включить, присвоив значение true соответствующему полю MapOptions. Например, чтобы установить для элемента выбора типа карты стиль DROPDOWN_MENU, используйте следующий код внутри объекта MapOptions:

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

В следующем примере показано, как изменить расположение и стиль элементов управления по умолчанию.

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

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 – включает/отключает элемент управления "Ориентация" для просмотра 3D-изображений. Наличие этого элемента зависит от доступности 3D-изображений для выбранного типа карты, масштаба и показанной на карте территории. Его поведение можно изменить, задав настройки rotateControlOptions в объекте RotateControlOptions. Элемент управления будет показываться только на базовых 3D-картах.
• scaleControl – включает/отключает линейку масштаба. По умолчанию этот элемент управления недоступен. Если вы его включите, он появляется в правом нижнем углу карты. Поле scaleControlOptions дополнительно задает параметры ScaleControlOptions для этого элемента управления.
• fullscreenControl – включает/отключает кнопку перехода карты в полноэкранный режим. Этот элемент управления по умолчанию включен в версии для компьютеров и устройств Android (находится в верхней правой части карты). Поле fullscreenControlOptions дополнительно задает параметры FullscreenControlOptions для этого элемента управления.

Учтите, что вы можете задавать параметры элементов управления, которые сами отключили.

Расположение элементов управления

Большинство элементов управления содержат свойство position (типа ControlPosition), указывающее расположение элемента управления на карте. Оно не задается абсолютными значениями. Вместо этого API распределяет элементы управления на экране так, чтобы они, с учетом размера карты и других ограничений, не перекрывали объекты на карте и другие элементы управления.

Существует два типа позиций элементов управления: устаревшие и логические. Рекомендуется использовать логические значения, чтобы автоматически поддерживать макеты с написанием слева направо (LTR) и справа налево (RTL). Ознакомьтесь с руководством.

В таблицах ниже показаны поддерживаемые позиции элементов управления для языков с письмом слева направо и справа налево.

Нажимайте на ярлыки, чтобы переключать карту между режимами LTR и RTL.

Следует отметить, что перечисленные варианты расположения могут совпадать с позициями элементов пользовательского интерфейса, которые нельзя изменять (например, предупреждением об авторских правах и логотипом Google). В таких случаях элементы управления размещаются в соответствии с логикой, заданной для каждой позиции, и отображаются максимально близко к ней. Хотя в API предусмотрены механизмы, препятствующие наложению элементов, мы не можем гарантировать, что этого не произойдет.

В следующем примере показана простая карта, на которой включены все элементы управления в разных позициях.

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

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

Пользовательские элементы управления

Вы можете не только изменять стиль и расположение существующих элементов управления API, но и создавать собственные. Элементы управления представляют собой статичные виджеты. Их положение на карте не меняется (в отличие от наложений, которые перемещаются вместе с картой). Таким образом, элемент управления – это тег <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. Он вложен в элемент 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>

В коде JavaScript 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);

Алгоритмическая продажа (JavaScript)

В этом фрагменте кода показано, как программно создать элемент управления кнопкой. Стили 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 в качестве контейнера только для нативных элементов управления (и никогда как интерактивный элемент).
• Для добавления информации об элементе интерфейса используйте label и атрибуты title или aria-label (если применимо).

Расположение пользовательских элементов управления

Чтобы разместить пользовательские элементы управления, используйте атрибут slot, указав нужное положение. Подробнее об этом рассказывается в разделе Расположение элементов управления.

Каждое значение ControlPosition содержит массив MVCArray для элементов управления, расположенных в данной позиции. В результате, когда элементы управления добавляются в позицию или удаляются из нее, API меняет расположение остальных элементов управления.

В примере ниже создается персонализированный элемент управления (конструктор не показан), который затем добавляется на карту в позицию 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>

Пример пользовательского элемента управления

Следующий простой (хотя не особенно полезный) элемент управления приведен для иллюстрации описанных выше правил. Он реагирует на события '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

Состояния элементов управления

Элементы управления также могут включать в себя состояния. Пример ниже аналогичен предыдущему с той лишь разницей, что элемент управления содержит кнопку "Set Home" для указания нового домашнего адреса. Для этого в элементе управления создается свойство home_, которое хранит состояние элемента и реализует методы его чтения и записи.

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

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