control.SearchControl
Важно
Чтобы использовать саджест в JS API:
- Получите ключ для саджеста в Кабинете разработчика.
- Укажите его при подключении 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])
Параметры:
Параметр |
Значение по умолчанию |
Описание |
— |
Тип: Object Параметры элемента управления. |
|
— |
Тип: Object Объект, описывающий данные элемента управления. |
|
— |
Тип: Object Опции элемента управления. |
|
false |
Тип: Boolean Регистрирует ли элемент управления свои размеры в менеджере отступов карты map.margin.Manager. |
|
— |
Тип: Number[][] Прямоугольная область на карте, где предположительно находится искомый объект. При ранжировании объекты, находящиеся внутри указанной области, будут получать больший приоритет. |
|
false |
Тип: Boolean Растягивать ли поисковую строку до максимального размера. |
|
"right" |
Тип: String Сторона, по которой нужно выравнивать элемент управления. Может принимать три значения: "left", "right" или "none". При значении "left" или "right" элементы управления выстраиваются друг за другом, начиная от левого или правого края карты соответственно. При значении "none" элементы управления позиционируется только по значениям опций left, right, bottom, top относительно границ карты. Также смотрите описание опции position. |
|
200 |
Тип: Number Приоритет расположения элемента управления. Элемент с максимальным приоритетом находится ближе к указанному в свойстве float краю карты. Не работает при float = "none". |
|
'islands#searchControlFormLayout' |
Тип: ILayout|String Конструктор макета формы для реализации поиска в макете элемента управления по умолчанию или ключ в хранилище layout.storage. В конструктор макета передается объект, содержащий поля:
|
|
'house' |
Тип: String Вид топонима (только для обратного геокодирования). Список возможных значений:
|
|
'islands#searchControlLayout' |
Тип: ISearchControlLayout|String Макет элемента управления. В конструктор макета передается объект, содержащий поля:
Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей control.SearchControl.state в зависимости от полученных команд. |
|
[30, 72, 315] |
Тип: Number|Number[] Максимальная ширина элемента управления в различных состояниях. Если задано число, то считается, что элемент управления имеет одинаковые максимальные размеры во всех состояниях. Если задан массив, то он будет трактоваться как максимальная ширина в различных состояниях - от меньшего к большему. Количество доступных состояний задается в экземпляре класса control.Manager через опцию states. Этот класс обычно является полем Map.controls. Для состояния 'large' ширина может быть в пределах от 280 до 660 пикселей. По умолчанию у элементов управления есть три состояния - ['small', 'medium', 'large']. |
|
false |
Тип: Boolean false - автоматически располагать центр карты так, чтобы объект был виден целиком. Значение true - не изменять центр карты при показе найденного объекта. Если указать noCentering = true и noPlacemark = true, то при щелчке по результату поиска никаких видимых изменений на карте не произойдет. |
|
false |
Тип: Boolean false - автоматически добавлять в центр найденного объекта метку с открытым балуном, true - не добавлять. Если указать noCentering = true и noPlacemark = true, то при щелчке по результату поиска никаких видимых изменений на карте не произойдет. Опция не работает с провайдером yandex#search. |
|
false |
Тип: Boolean true - не показывать выпадающий список результатов, false - показывать. |
|
false |
Тип: Boolean При значении false будет автоматически показываться результат поиска, если он является единственным найденным объектом, true — результат не будет выбираться. |
|
false |
Тип: Boolean true - не показывать панель с поисковыми подсказками, false - показывать. |
|
— |
Тип: String Текст-подсказка, показываемый в поле ввода элемента управления. |
|
'islands#searchControlPopupItemLayout' |
Тип: ILayout|String Конструктор макета результата поиска в выпадающем списке в макете элемента управления по умолчанию или ключ в хранилище layout.storage. В конструктор макета передается объект, содержащий поля:
|
|
'islands#searchControlPopupLayout' |
Тип: ILayout|String Конструктор макета выпадающего списка с результатами поиска в макете элемента управления по умолчанию или ключ в хранилище layout.storage. В конструктор макета передается объект, содержащий поля:
|
|
— |
Тип: Object Объект, описывающий позицию элемента управления. При указании опции position значение опции float автоматически трактуется как "none". |
|
'auto' |
Тип: Number|String Положение относительно нижнего края карты. |
|
'auto' |
Тип: Number|String Положение относительно левого края карты. |
|
'auto' |
Тип: Number|String Положение относительно правого края карты. |
|
'auto' |
Тип: Number|String Положение относительно верхнего края карты. |
|
'yandex#map' |
Тип: IGeocodeProvider|String Провайдер геокодирования. Можно воспользоваться одним из стандартных провайдеров:
|
|
'latlong' |
Тип: String Определяет каким образом нужно интерпретировать координаты в запросе. По умолчанию координаты будут обрабатываться как широта-долгота. Опция не работает с провайдером yandex#search. |
|
'auto' |
Тип: String Параметр, отвечающий за внешний вид элемента управления. Может принимать значения:
|
|
— |
Тип: Boolean Искать только внутри области, заданной опцией boundedBy. Объекты вне указанной области попадать в выдачу не будут. |
|
— |
Тип: Boolean Флаг, позволяющий учитывать при поиске границы видимой области карты. При значении true рассчитанная область видимости имеет больший приоритет, чем заданная через boundedBy. |
|
0 |
Тип: Number Отступы от границ видимой области карты при показе найденных результатов. Для того чтобы опция применилась, значение noCentering должно быть false. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left. При включенной опции "useMapMargin" значение "zoomMargin" складывается со значениями, которые были рассчитаны в менеджере отступов map.margin.Manager. |
|
— |
Тип: Object Объект, описывающий состояние элемента управления. |
|
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
});
Поля
Имя |
Тип |
Описание |
Менеджер событий. Унаследовано от IEventEmitter. |
||
Менеджер опций. Унаследовано от IControl. |
||
Состояние элемента управления. Имена полей, доступных через метод data.Manager.get:
|
События
Имя |
Описание |
Событие очистки результатов поиска. Экземпляр класса Event. |
|
Событие ошибки получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
|
|
Событие получения результатов поиска с сервера. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
|
|
Изменение в опциях объекта. Унаследовано от ICustomizable. |
|
Сменился родительский объект. Поля данных:
Унаследовано от IChild. |
|
Событие выбора результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
|
|
Событие показа результата поиска. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
|
|
Событие отправления поискового запроса на сервер. Экземпляр класса Event. |
Методы
Имя |
Возвращает |
Описание |
clear() |
Очищает результаты поиска, а также содержимое поисковой строки элемента управления. |
|
getMap() |
Возвращает ссылку на карту. |
|
IControlParent|null |
Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен. Унаследован от IControl. |
|
String |
Возвращает поисковый запрос. |
|
Object |
Возвращает метаданные геопоиска. |
|
Получение результатов поиска. |
||
Object[] |
Возвращает массив, содержащий все текущие результаты. |
|
Integer |
Возвращает количество найденных результатов. |
|
Integer |
Возвращает индекс выбранного элемента. |
|
Скрывает результат, показанный на карте. |
||
Осуществляет поиск. |
||
Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта. Унаследован от IControl. |
||
Отображает результат с заданным индексом. |
Описание полей
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.
Параметры:
Параметр |
Значение по умолчанию |
Описание |
— |
Тип: 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 });
search
{vow.Promise} search(request, options)
Осуществляет поиск.
Возвращает объект типа vow.Promise.
Параметры:
Параметр |
Значение по умолчанию |
Описание |
— |
Тип: String Запрос. |
|
— |
Тип: 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)
Отображает результат с заданным индексом.
Возвращает ссылку на себя.
Параметры:
Параметр |
Значение по умолчанию |
Описание |
— |
Тип: 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);
}
});
Обязательный параметр.