control.SearchControl

Важно

Чтобы использовать саджест в JS API:

  1. Получите ключ для саджеста в Кабинете разработчика.
  2. Укажите его при подключении JS API в формате https://api-maps.yandex.ru/2.1/?lang=ru_RU&apikey=<ваш ключ для JS API>&suggest_apikey=<ваш ключ для Suggest API>.

Расширяет IControl, ICustomizable.

Элемент управления "Поиск по карте". Позволяет обрабатывать поисковый запрос пользователя и отображать результат в панели и на карте.

Каждый результат поиска представляется в панели элемента управления в виде двухстрочного блока. Для формирования блока используются поля name и description объекта-результата геокодирования.
Ключ элемента управления в хранилище control.storage — "searchControl".
Конструктор | Поля | События | Методы

Конструктор

control.SearchControl([parameters])

Параметры:

Параметр

Значение по умолчанию

Описание

parameters

Тип: Object

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

parameters.data

Тип: Object

Объект, описывающий данные элемента управления.

parameters.options

Тип: Object

Опции элемента управления.

parameters.options.adjustMapMargin

false

Тип: Boolean

Регистрирует ли элемент управления свои размеры в менеджере отступов карты map.margin.Manager.

parameters.options.boundedBy

Тип: Number[][]

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

parameters.options.fitMaxWidth

false

Тип: Boolean

Растягивать ли поисковую строку до максимального размера.

parameters.options.float

"right"

Тип: String

Сторона, по которой нужно выравнивать элемент управления. Может принимать три значения: "left", "right" или "none". При значении "left" или "right" элементы управления выстраиваются друг за другом, начиная от левого или правого края карты соответственно. При значении "none" элементы управления позиционируется только по значениям опций left, right, bottom, top относительно границ карты. Также смотрите описание опции position.

parameters.options.floatIndex

200

Тип: Number

Приоритет расположения элемента управления. Элемент с максимальным приоритетом находится ближе к указанному в свойстве float краю карты. Не работает при float = "none".

parameters.options.formLayout

'islands#searchControlFormLayout'

Тип: ILayout|String

Конструктор макета формы для реализации поиска в макете элемента управления по умолчанию или ключ в хранилище layout.storage.

В конструктор макета передается объект, содержащий поля:

  • control - ссылка на элемент управления;
  • options - менеджер опций элемента управления control.SearchControl.options;
  • data - менеджер данных элемента управления control.SearchControl.data;
  • state - менеджер состояния элемента управления control.SearchControl.state.

parameters.options.kind

'house'

Тип: String

Вид топонима (только для обратного геокодирования). Список возможных значений:

  • house - дом;
  • street - улица;
  • metro - станция метро;
  • district - район города;
  • locality - населенный пункт (город/поселок/деревня/село/...).

parameters.options.layout

'islands#searchControlLayout'

Тип: ISearchControlLayout|String

Макет элемента управления.

В конструктор макета передается объект, содержащий поля:

  • control - ссылка на элемент управления;
  • options - менеджер опций элемента управления control.SearchControl.options;
  • data - менеджер данных элемента управления control.SearchControl.data;
  • state - менеджер состояния элемента управления control.SearchControl.state.

Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей control.SearchControl.state в зависимости от полученных команд.

parameters.options.maxWidth

[30, 72, 315]

Тип: Number|Number[]

Максимальная ширина элемента управления в различных состояниях. Если задано число, то считается, что элемент управления имеет одинаковые максимальные размеры во всех состояниях. Если задан массив, то он будет трактоваться как максимальная ширина в различных состояниях - от меньшего к большему. Количество доступных состояний задается в экземпляре класса control.Manager через опцию states. Этот класс обычно является полем Map.controls. Для состояния 'large' ширина может быть в пределах от 280 до 660 пикселей. По умолчанию у элементов управления есть три состояния - ['small', 'medium', 'large'].

parameters.options.noCentering

false

Тип: Boolean

false - автоматически располагать центр карты так, чтобы объект был виден целиком. Значение true - не изменять центр карты при показе найденного объекта. Если указать noCentering = true и noPlacemark = true, то при щелчке по результату поиска никаких видимых изменений на карте не произойдет.

parameters.options.noPlacemark

false

Тип: Boolean

false - автоматически добавлять в центр найденного объекта метку с открытым балуном, true - не добавлять. Если указать noCentering = true и noPlacemark = true, то при щелчке по результату поиска никаких видимых изменений на карте не произойдет. Опция не работает с провайдером yandex#search.

parameters.options.noPopup

false

Тип: Boolean

true - не показывать выпадающий список результатов, false - показывать.

parameters.options.noSelect

false

Тип: Boolean

При значении false будет автоматически показываться результат поиска, если он является единственным найденным объектом, true — результат не будет выбираться.

parameters.options.noSuggestPanel

false

Тип: Boolean

true - не показывать панель с поисковыми подсказками, false - показывать.

parameters.options.placeholderContent

Тип: String

Текст-подсказка, показываемый в поле ввода элемента управления.

parameters.options.popupItemLayout

'islands#searchControlPopupItemLayout'

Тип: ILayout|String

Конструктор макета результата поиска в выпадающем списке в макете элемента управления по умолчанию или ключ в хранилище layout.storage.

В конструктор макета передается объект, содержащий поля:

  • control - ссылка на элемент управления;
  • options - менеджер опций элемента управления control.SearchControl.options;
  • data - менеджер данных элемента управления control.SearchControl.data;
  • state - менеджер состояния элемента управления control.SearchControl.state.

parameters.options.popupLayout

'islands#searchControlPopupLayout'

Тип: ILayout|String

Конструктор макета выпадающего списка с результатами поиска в макете элемента управления по умолчанию или ключ в хранилище layout.storage.

В конструктор макета передается объект, содержащий поля:

  • control - ссылка на элемент управления;
  • options - менеджер опций элемента управления control.SearchControl.options;
  • data - менеджер данных элемента управления control.SearchControl.data;
  • state - менеджер состояния элемента управления control.SearchControl.state.

parameters.options.position

Тип: Object

Объект, описывающий позицию элемента управления. При указании опции position значение опции float автоматически трактуется как "none".

parameters.options.position.bottom

'auto'

Тип: Number|String

Положение относительно нижнего края карты.

parameters.options.position.left

'auto'

Тип: Number|String

Положение относительно левого края карты.

parameters.options.position.right

'auto'

Тип: Number|String

Положение относительно правого края карты.

parameters.options.position.top

'auto'

Тип: Number|String

Положение относительно верхнего края карты.

parameters.options.provider

'yandex#map'

Тип: IGeocodeProvider|String

Провайдер геокодирования. Можно воспользоваться одним из стандартных провайдеров:

  • 'yandex#map' - поиск топонимов на карте карте;
  • 'yandex#search' - поиск по топонимам и организациям. Для поиска по организациям не работают следующие опции: «noPlacemark», «noCentering», «noSelect», «strictBounds», «kind». Кроме того, по умолчанию на карте показываются 20 объектов, если не указана опция «results» для элемента управления.

parameters.options.searchCoordOrder

'latlong'

Тип: String

Определяет каким образом нужно интерпретировать координаты в запросе. По умолчанию координаты будут обрабатываться как широта-долгота. Опция не работает с провайдером yandex#search.

parameters.options.size

'auto'

Тип: String

Параметр, отвечающий за внешний вид элемента управления. Может принимать значения:

  • 'small' — всегда показывать кнопку с иконкой;
  • 'medium' — всегда показывать кнопку с текстом;
  • 'large' — всегда показывать полную поисковую форму;
  • 'auto' — производить автоматический выбор размера элемента управления в зависимости от наличия свободного пространства в тулбаре.

parameters.options.strictBounds

Тип: Boolean

Искать только внутри области, заданной опцией boundedBy. Объекты вне указанной области попадать в выдачу не будут.

parameters.options.useMapBounds

Тип: Boolean

Флаг, позволяющий учитывать при поиске границы видимой области карты. При значении true рассчитанная область видимости имеет больший приоритет, чем заданная через boundedBy.

parameters.options.zoomMargin

0

Тип: Number

Отступы от границ видимой области карты при показе найденных результатов. Для того чтобы опция применилась, значение noCentering должно быть false. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left. При включенной опции "useMapMargin" значение "zoomMargin" складывается со значениями, которые были рассчитаны в менеджере отступов map.margin.Manager.

parameters.state

Тип: Object

Объект, описывающий состояние элемента управления.

options.useMapMargin

true

Тип: Boolean

Нужно ли учитывать отступы карты map.margin.Manager при показе результатов поиска на карте.

Примеры:

1.

// Пример 1.
// Создание элемента управления и добавление его на карту.

var searchControl = new ymaps.control.SearchControl({
     options: {
         float: 'right',
        floatIndex: 100,
         noPlacemark: true
     }
});
myMap.controls.add(searchControl);

2.

// Пример 2
// Если элемент управления уже добавлен на карту по ключу из хранилища control.storage,
// то его экземпляр можно получить с помощью метода control.Manager.get
// менеджера элементов управления control.Manager.

var searchControl = myMap.controls.get('searchControl');
searchControl.events.add('submit', function () {
    console.log('request: ' + searchControl.getRequestString());
}, this);

3.

// Пример 3.
// Включим поиск по организациям в элементе управления, уже добавленном на карту.
// Если элемент управления уже добавлен на карту по ключу из хранилища control.storage,
// то его экземпляр можно получить с помощью метода control.Manager.get.

var searchControl = myMap.controls.get('searchControl');
searchControl.options.set('provider', 'yandex#search');

4.

// Пример 4.
// Создадим элемент управления «поиск по карте» с включенным поиском по организациям.

var searchControl = new ymaps.control.SearchControl({
     options: {
         float: 'left',
         provider: 'yandex#search'
     }
});

5.

// Пример 5.
// Увеличим значение максимальной ширины для поисковой строки в состоянии 'large'.
map.options.set({
    // Максимальная ширина для трех состояний: [30, 72, 315].
    // Изменим ширину для состояния 'large'.
    searchControlMaxWidth: [30, 72, 500],
    // Расширим поисковую строку до максимального размера.
    fitMaxWidth: true
});

Поля

Имя

Тип

Описание

events

IEventManager

Менеджер событий.

Унаследовано от IEventEmitter.

options

IOptionManager

Менеджер опций.

Унаследовано от IControl.

state

data.Manager

Состояние элемента управления. Имена полей, доступных через метод data.Manager.get:

  • size — текущий размер элемента управления;
  • results — массив, содержащий результаты поиска;
  • currentIndex — индекс текущего выбранного элемента;
  • found — общее количество найденных результатов;
  • request — текущий активный запрос;
  • correction — исправленный запрос;
  • noSuggestPanel - флаг, скрывать ли панель поисковых подсказок.

События

Имя

Описание

clear

Событие очистки результатов поиска. Экземпляр класса Event.

error

Событие ошибки получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • error — информация об ошибке.

load

Событие получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • skip — сколько элементов было пропущено;
  • count — количество загруженных элементов.

optionschange

Изменение в опциях объекта.

Унаследовано от ICustomizable.

parentchange

Сменился родительский объект.

Поля данных:

  • oldParent - старый родитель;
  • newParent - новый родитель.

Унаследовано от IChild.

resultselect

Событие выбора результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • index — индекс выбранного результата.

resultshow

Событие показа результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • index — индекс выбранного результата.

submit

Событие отправления поискового запроса на сервер. Экземпляр класса Event.

Методы

Имя

Возвращает

Описание

clear()

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

getMap()

Map

Возвращает ссылку на карту.

getParent()

IControlParent|null

Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен.

Унаследован от IControl.

getRequestString()

String

Возвращает поисковый запрос.

getResponseMetaData()

Object

Возвращает метаданные геопоиска.

getResult(index)

vow.Promise

Получение результатов поиска.

getResultsArray()

Object[]

Возвращает массив, содержащий все текущие результаты.

getResultsCount()

Integer

Возвращает количество найденных результатов.

getSelectedIndex()

Integer

Возвращает индекс выбранного элемента.

hideResult()

Скрывает результат, показанный на карте.

search(request, options)

vow.Promise

Осуществляет поиск.

setParent(parent)

IChildOnMap

Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта.

Унаследован от IControl.

showResult(index)

control.SearchControl

Отображает результат с заданным индексом.

Описание полей

state

{data.Manager} state

Состояние элемента управления. Имена полей, доступных через метод data.Manager.get:

  • size — текущий размер элемента управления;
  • results — массив, содержащий результаты поиска;
  • currentIndex — индекс текущего выбранного элемента;
  • found — общее количество найденных результатов;
  • request — текущий активный запрос;
  • correction — исправленный запрос;
  • noSuggestPanel - флаг, скрывать ли панель поисковых подсказок.

Описание событий

clear

Событие очистки результатов поиска. Экземпляр класса Event.

error

Событие ошибки получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • error — информация об ошибке.

load

Событие получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • skip — сколько элементов было пропущено;
  • count — количество загруженных элементов.

resultselect

Событие выбора результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • index — индекс выбранного результата.

resultshow

Событие показа результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:

  • index — индекс выбранного результата.

submit {#}

Событие отправления поискового запроса на сервер. Экземпляр класса Event.

Описание методов

clear

{} clear()

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

getMap

{Map} getMap()

Возвращает ссылку на карту.

getRequestString

{String} getRequestString()

Возвращает поисковый запрос.

getResponseMetaData

{Object} getResponseMetaData()

Возвращает метаданные геопоиска.

getResult

{vow.Promise} getResult(index)

Получение результатов поиска.

Возвращает объект типа vow.Promise.

Параметры:

Параметр

Значение по умолчанию

Описание

index*

Тип: Integer

Индекс результата, начинается с 0.

* Обязательный параметр/опция.

getResultsArray

{Object[]} getResultsArray()

Возвращает массив, содержащий все текущие результаты.

getResultsCount

{Integer} getResultsCount()

Возвращает количество найденных результатов.

getSelectedIndex

{Integer} getSelectedIndex()

Возвращает индекс выбранного элемента.

hideResult

{} hideResult()

Скрывает результат, показанный на карте.

Пример:

// Если мы показали какой-то результат на карте с помощью  control.SearchControl.showResult,
// или он был показан автоматически при поиске, мы можем скрыть его, например,
// по клику на кнопку.
var myButton = new ymaps.control.Button("Hide results");
myButton.events.add('click', function () {
    searchControl.hideResult();
}, this);
myMap.controls.add(myButton, { selectOnClick: false });
{vow.Promise} search(request, options)

Осуществляет поиск.

Возвращает объект типа vow.Promise.

Параметры:

Параметр

Значение по умолчанию

Описание

request*

Тип: String

Запрос.

options*

Тип: Object

Дополнительные опции провайдера.

* Обязательный параметр/опция.

Пример:

// Попробуем найти Москву и вывести поле name
// первого найденного результата в консоль.
searchControl.search('Москва').then(function () {
    var geoObjectsArray = searchControl.getResultsArray();
    if (geoObjectsArray.length) {
        // Выводит свойство name первого геообъекта из результатов запроса.
        console.log(geoObjectsArray[0].properties.get('name'));
    }
});

showResult

{control.SearchControl} showResult(index)

Отображает результат с заданным индексом.

Возвращает ссылку на себя.

Параметры:

Параметр

Значение по умолчанию

Описание

index*

Тип: Integer

Индекс результата, начинается с 0.

* Обязательный параметр/опция.

Пример:

// Мы хотим показывать всегда первый результат,
// вне зависимости от количества найденных
// объектов на карте (1 или более).
var searchControl = new ymaps.control.SearchControl({
    // Опция отключает автоматический выбор результата поиска.
    options: { noSelect: true }
});
searchControl.events.add('load', function (event) {
    // Проверяем, что это событие не "дозагрузки" результатов и
    // по запросу найден хотя бы один результат.
    if (!event.get('skip') && searchControl.getResultsCount()) {
        searchControl.showResult(0);
    }
});
Предыдущая
Следующая