-----
Эта статья относится к API Яндекс.Карт 1.x. Рекомендуем почитать аналогичную инструкцию для новой версии API — 2.0.
-----

Последнее время достаточно часто нас просят помимо документации, рассказывать про различные примеры использования API Яндекс.Карт, с пояснениями каких-либо моментов с фрагментами кода. Время от времени мы будем публиковать такие статьи в этом клубе, а также будем рады видеть нечто подобное и от разработчиков, которые разобрались с нашим АПИ, и хотели бы поделиться опытом с другими веб-разработчиками.

Сегодня мы рассмотрим то, как устроена карта с несколькими метками с заданным стилем на карте мира.

Рассмотрим вот такой пример: Все офисы Яндекса на карте мира

Показать несколько меток на интерактивной карте (как в примере) можно двумя способами: задать их с помощью функций Javascript API (подробнее см. раздел "Метки") или описать их при помощи специального XML-файла ("YMapsML" — Yandex Maps Markup Language).

Первый способ можно использовать тогда, когда html-страница генерируется на сервере, и для метки можно на уровне вызовов Javascript указывать различные параметры. А второй — когда сама страница на сайте статическая, а XML либо сформирована один раз, или генерируется на сервере.

Сегодня мы рассмотрим второй способ добавления меток на карту.

Для этого потребуется создать 2 файла: html — страница на которой помещён вызов карты и все необходимые параметры, чтобы показать метки из xml-файла.

Итак, что потребуется:

1) API-ключ для использования Яндекс.Карт - его нужно получить на этой странице.Кстати, при получении ключа, вам будет предложен простой html-код страницы с картой с центром Москвы и уже с вашим ключом, код можно вставить в пустой HTML-файл на локальном диске или на хостинге, и посмотреть, что получилось.

2) стандартный текстовый редактор или любой другой редактор текста с возможностью править XML и HTML файлы.

3) Если вы хотите использовать для обозначения меток собственные значки, то сами значки и тень для значка. Это может быть любая картинка (gif, png, jpg) для интернета с небольшими размерами.

В нашем примере:

Значок

Тень значка:

Кроме этого, нужно знать какого размера картинки, и координаты точки (в пикселях, от левого верхнего угла), которая должна указывать место на карте — "хвостик" точки.

Создание XML-файла с метками

Рассмотрим уже созданный XML-файл с метками: http://company.yandex.ru/inside/address.xml 

Этот файл состоит из двух основных частей, вложенных в корневой элемент ymaps :  repr:Repsentation — здесь задается представление и ymaps:GeoObjectCollection — здесь описываются географические данные (в нашем случае метки).

Подробная схема YMapsML документа здесь 

Обратите внимание, для элементов важно понятие namespace, имена и значения задаются атрибутами xmlns для корневого элемента так:

<ymaps:ymaps xmlns:gml="http://www.opengis.net/gml" xmlns:ymaps="http://maps.yandex.ru/ymaps/1.x" xmlns:repr="http://maps.yandex.ru/representation/1.x">

Это значит, что для того или иного набора тегов будет использоваться соответсвующая схема (правила описания этого тега).

Задание меток

Для того, чтобы описать метку (точку), в тег ymaps:GeoObjectCollection нужно описать вложенный тег:

  <gml:featureMember>
   <ymaps:GeoObject id="taganka">
    <gml:description>
     Москва, ул. Станиславского, дом 21, строение 3
    </gml:description>
    <gml:name>
     Офис Яндекса на Станиславского
    </gml:name>

    <gml:Point>
    <gml:pos>37.662335 55.745376</gml:pos>
     </gml:Point>
    <ymaps:style>#companyStyle</ymaps:style>
   </ymaps:GeoObject>
  </gml:featureMember>

Подробнее о тегах внутри:

ymaps:GeoObject — непосредственно описание геообъекта (точки)

gml:description — описание геообъекта

gml:name — название объекта

gml:Point — указание типа геообъекта "метка"

gml:pos — географические координаты в формате - "долгота широта" (через пробел), например "37.662335 55.745376"

ymaps:style — идентификатор стиля данной метки

Где взять географические координаты?

Если у вас есть почтовый адрес, вы можете задать http-запрос к Геокодеру, либо можно просто узнать их, перетащив метку на карте в этом примере

Задание стиля метки

Стиль метки здается тегом  задаются в теге  repr:Repsentation

<repr:Style gml:id="companyStyle">
        <repr:iconStyle>
            <repr:href>http://company.yandex.ru/i/ya.png</repr:href>
            <repr:size x="57" y="55"/>
            <repr:offset x="-37" y="0"/>
            <repr:shadow>

                <repr:href>http://company.yandex.ru/i/shadow.png</repr:href>
                <repr:size x="57" y="55"/>
                <repr:offset x="-37" y="0"/>
            </repr:shadow>
        </repr:iconStyle>
    <repr:balloonContentStyle>
        <repr:template>#companyTemplate</repr:template>

    </repr:balloonContentStyle>
</repr:Style>

В этом теге:

repr:iconStyle — описание значка для метки, оно содержит тег repr:href — ссылка на картинку со значком. Путь до картинки нужно указывать полностью, с "http://..". А так же: repr:size — размер картинки, и repr:offset — смещение значка от точки на карте.

Если у значка есть тень, то в тег repr:iconStyle нужно вложить тег repr:shadow, в котром также нужно указать href, size и offset.

repr:balloonContentStyle — стиль содержимого всплывающего окна (balloon) по клику на метке, содержит тег repr:template (с маленькой буквы) — идентификатор шаблона.

Сам же шаблон задается с помощью repr:Template (с большой буквы), в данном случае значения $name и $description подставляются в подзаголовок, и текст под ним:

<repr:Template gml:id="companyTemplate">
        <repr:text><![CDATA[<div><h4>$[name]</h4><span>$[description]</span></div>]]></repr:text>
    </repr:Template>

Важно: Созданный YMapsML-файл можно визуализировать с помощью Javascript API только в том случае, если он будет доступен для серверов Яндекса по http. Если сайта у вас пока нет, тестовые xml-файлы вы можете опубликовать, например, на Народе 

Визуализация YMapsML-файла на карте

Рассмотрим интересующие нас вызовы API в коде страницы

Подключение Javascript API

Простое подключение API происходит при помощи загрузки Javascript (внутри тега <head>):

<script charset="utf-8" type="text/javascript" src="http://api-maps.yandex.ru/1.0/?key=API-ключ">

"1.0" — версия API (Подробнее о версиях Javascript API)

"API-ключ" — ключ, полученный для вашего сайта, получить ключ можно здесь, подробнее о ключах — в "Вопросах и ответах" 

Задание параметров карты и вызовы

<script type="text/javascript"><!--
var map; //декларируем имя объекта для карты
var ml; //декларируем имя слоя с метками из XML


function init (lat,long) { //функция имеет входные параметры - широта и долгота, куда спозиционировать карту
    map = new YMaps.Map(document.getElementById("YMapsID") //создание карты
    map.setCenter(new YMaps.GeoPoint(long, lat), 2); //задание параметров для карты (центр и уровень масштабирования)

    ml = new YMaps.YMapsML( 'http://company.yandex.ru/inside/address.xml' //создание слоя с метками из XML

    map.addOverlay(ml); //добавление слоя на карту

    map.addControl(new YMaps.TypeControl() //добавляем элемент управления переключения типов карты
    map.addControl(new YMaps.ToolBar() //добавление тулбара
    map.addControl(new YMaps.Zoom() //добавление элемента управления масштабом
    map.addControl(new YMaps.ScaleLine() //добавление масштабного отрезка

    YMaps.Events.observe(ml, ml.Events.Fault, function (error) {
        alert('Ошибка' + error); //если XML документ не загрузился или загрузился с ошибками, выведется сообщение об этом
    }
};
    //--></script>

Добавление html-элемента с картой на страницу

<div id="YMapsID" style="height:400px; width:100%;"></div>

Инициализация карты
Карта иницилизируется по загрузке страницы, с центром в указанных ниже координатах:
<body onload="init('45.758255','-22.00');">
Это все :)
PS: Пишите вопросы, если чего-то было непонятно. 

===Эта статья относится к старой версии API Яндекс.Карт — 1.х. Рекомендуем использовать API 2.0 Яндекс.Карт.=== 

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

Обратное геокодирование - это процесс преобразования географических координат объекта в почтовый адрес.

Вызов обратного геокодирования отличается от прямого только тем, что вместо строки с адресом передаются координаты объекта.

Осуществлять обратное геокодирование можно с использованием любого из двух интерфейсов: http и javascript.

Пример использования обратного геокодера по http-интерфейсу.
http://geocode-maps.yandex.ru/1.x/?geocode=37.611706,55.75862&key=API-ключ

Пример использования обратного геокодера по javascript-интерфейсу.

var geocoder = new YMaps.Geocoder(new YMaps.GeoPoint(37.611706,55.75862)

map.addOverlay(geocoder);

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

На основе javascript-интерфейса создадим инструмент "Информация".
 
Инструмент "Информация" - это элемент управления, который позволяет по координатам щелчка мыши пользователя определять почтовый адрес объекта (или ближайший адрес к нему). Посмотреть инструмент в действии можно на странице maps.yandex.ru.

Используя javascript-интерефейс, т. е. объект YMaps.Geocoder можно создать аналог инструмента "Информация".

Создадим элемент управления (назовем его InformationControl), для этого реализуем интерфейс YMasp.IControl.

// Элемент управления "Информация"
function InformationControl () {
// Вызывается при добавлении элемента управления на карту
this.onAddToMap = function (parentMap) {}

// Вызывается при удалении элемента управления с карты
this.onRemoveFromMap = function () {}
}

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

// Вызывается при добавлении элемента управления на карту
this.onAddToMap = function (parentMap) {
  map = parentMap;
   
// Создание обработчика кликов по карте
listener = YMaps.Events.observe(map, map.Events.Click, function (map, mEvent) {
// Выключаем обработчиков событий, чтобы к геокодеру ушло не более одного запроса
// (по окончанию геокодированияю включаем обработчик вновь)
listener.disable(

// Координаты клика мышью
var clickPoint = mEvent.getGeoPoint(

 ...

// Отмечаем точку по которой щелкнул пользователь
clickPlace = new YMaps.Placemark(clickPoint, {style: anchorStyle}
clickPlace.description = clickPoint.toString(
map.addOverlay(clickPlace);

// Запуск процесс геокодирования
this.geocode(clickPoint);
}, this);
}

Метод geocode() запускает процесс геокодирования и добавляет результат на карту. В данном методе создаются обработчики для событий геокодера Load и Fault, в которых происходит обработка результатов поиска (в частности, включается обработчиков кликов по карте).

При успешном результате геокодирования наиболее релевантный результат геокодирования (если он был найден с помощью метода getResult()) добавляется на карту. 

 

 // Геокодирует точку
this.geocode = function (clickPoint) {
// Запуск процесса геокодирования
var geocoder = new YMaps.Geocoder(clickPoint);

// Обработчик успешного завершения геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Load, function (geocoder) {
// Получение результата поиска
geoResult = this.getResult(geocoder);

if (geoResult) {
   map.addOverlay(geoResult);
geoResult.openBalloon(
} else {
alert("Ничего не найдено!");
}

// Включаем обработчик кликов по карте
listener.enable(
}, this);

// Обработчик неудачного геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Fault, function (geocoder, err) {
alert("Произошла ошибка при геокодировании: " + err);

// Включаем обработчик кликов по карте
listener.enable(
}

Метод getResult() возвращает результат с различной точностью в зависимости от масштаба.
 

// Возвращает результат различной точности в зависимости от масштаба
this.getResult = function (geocoder) {
    // Точность: страна, область, город
    function isCountry (result) {
        return result.kind == "country" || result.kind == "province" || result.kind == "locality";
    }

    // Точность: улица
    function isStreet (result) {
        return result.kind == "street" || result.kind == "district";
    }

    // Точность: дом
    function isHouse (result) {
        return !isCountry(result) && !isStreet(result);
    };

    // Выбор точности поиска
    var filter = isHouse;
    if (map.getZoom() < 10) {
        filter = isCountry;
    } else if (map.getZoom() < 15) {
        filter = isStreet;
    }

    // Возвращает первый найденный результат
    return geocoder.filter(filter)[0];
}

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

// Создание элемента управления "Информация"
var informationControl = new InformationControl(

// Создание новой кнопки
// Добавляем ее к стандартной группе кнопок на панеле инструментов
var buttonInformation = new YMaps.ToolBarRadioButton(YMaps.ToolBar.DEFAULT_GROUP, {
icon: "http://maps.yandex.ru/i/info-button.png",
hint: "Информация"
}

// Включение/выключение инструмента "Информация"
YMaps.Events.observe(buttonInformation, buttonInformation.Events.Select, function () {
map.addControl(informationControl);
}

YMaps.Events.observe(buttonInformation, buttonInformation.Events.Deselect, function () {
map.removeControl(informationControl);
}

// Добавление элементов управления на карту
var toolBar = new YMaps.ToolBar(
toolBar.add(buttonInformation);
map.addControl(toolBar);

Посмотреть пример в действии можно по адресу: http://ymaps.narod2.ru/examples/reversegeocoderinformation.html

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

Если задать в поиске "улица Победы", то получим достаточно длинный список из 95 объектов.

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

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

// Область Москвы и Московской области
var moscowBounds = new YMaps.GeoBounds(
    new YMaps.GeoPoint(37.13268871914181, 55.55945544545429),
    new YMaps.GeoPoint(38.085747336675574, 55.946698202860325)


// По умолчанию геокодер возвращает первые 10 результатов поиска. Спомощью параметра results можно задать максимальное количество возвращаемых результатов.
map.addOverlay(new YMaps.Geocoder("победы", {boundedBy : moscowBounds, results : 100})

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

В решении данной задачи поможет параметр геокодера strictBounds, который указывает, что необходимо производить поиск только внутри области, заданной опцией boundedBy.

Немного изменим код:

// Область Москвы и Московской области
var moscowBounds = new YMaps.GeoBounds(
    new YMaps.GeoPoint(37.13268871914181, 55.55945544545429),
    new YMaps.GeoPoint(38.085747336675574, 55.946698202860325)

map.addOverlay(new YMaps.Geocoder("победы", {boundedBy : moscowBounds, strictBounds : true, results : 100})

В результате работы этого примера на карте будут отображены только те объекты, которые вошли в заданную область.

В http-геокодере можно задать область поиска с помощью параметров ll и spn, а с помощью параметра rspn ограничить поиск только заданной областью.

Более расширенный пример по работе с геокодером можно посмотреть по адресу:

http://ymaps.narod2.ru/examples/geocode-search.html

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

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

 Градусная сетка на обзорных масштабах на Яндекс.Картах — пример такого слоя.

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

Слой с координатной сеткой можно добавить на карту и на своём сайте. Для этого необходимо создать источник данных для тайлов и передать его в качестве параметра в конструктор класса YMaps.Layer для создания слоя. Более подробно о создании слоев можно прочитать в Руководстве разработчика.

При создании источника для тайлов с помощью класса YMaps.TileDataSource необходимо задать шаблон, по которому будет строиться URL для получения тайла.

В этом шаблоне можно использовать следующие специальные конструкции:

• %d - заменяется на число от 1 до 4, в зависимости от номера тайла. Используется для распределения нагрузки между несколькими доменами.
• %c - заменяется на x&y&z, где x - номер тайла по горизонтали, y - номер тайла по вертикали, z - коэффициент масштабирования.

Для построения URL'a тайла воспользуемся второй специальной конструкцией.

// Создание источника данных для тайла
var dataSource = new YMaps.TileDataSource("http://lrs.maps.yandex.net/tiles/?l=grd&v=1.0&%c", true, false),

    // Создание слоя
    gridLayer = new YMaps.Layer(dataSource);

// Добавление слоя на карту
map.addLayer(gridLayer);

Более расширенный пример, с возможностью включения и выключения отображения градусной сетки можно найти по этому адресу:
http://ymaps.narod2.ru/examples/grids.html

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

Стиль – это набор параметров, который позволяет задать внешний вид объектов на карте. Чтобы создать стиль, необходимо создать экземпляр класса YMaps.Style.

Сам стиль является контейнером, содержащем в себе стили для конкретных объектов (значка метки, ломанной линии и т. д.).
Например, за оформление значка метки отвечает поле iconStyle, в которое должен быть записан указатель на объект класса YMaps.IconStyle.

// Создание нового стиля
var style = new YMaps.Style();
 
// Стиль для оформления значка метки
style.iconStyle = new YMaps.IconStyle();

 

При создании любого оверлея в конструктор класса можно передавать как указатель на стиль, так и ключ.

Ключ – это строка, которая является уникальным идентификатором стиля.

В наименовании ключа можно использовать любые символы, однако рекомендуется создавать свое пространство имен и в нем задавать пользовательские стили. Пространство имен и имя стиля разделятся символом "#" (решетка). Все стандартные стили находятся в пространстве имен “default”. Например, «deafult#greenPoint”, «deafult#redPoint”, «deafult#smallWhitePoint” и т. д.

Продемонстрируем на фрагменте кода оба способа задания стиля.

// Создание стиля
// Подробнее о смене значка на любое изображение будет рассказано далее
var style = new YMaps.Style();
style.iconStyle = new YMaps.IconStyle();
style.iconStyle.href = "http://api-maps.yandex.ru/i/0.3/micro/pmgns.png";
style.iconStyle.size = new YMaps.Point(28, 29);
style.iconStyle.offset = = new YMaps.Point(-7, -28);
 
// В конструктор класса передается указатель на стиль
var placemark = new YMaps.Placemark(map.getCenter(), {style : emptyStyle});
 
// Стиль задан с помощью ключа
var placemark2 = new YMaps.Placemark(map.getCenter(), {style : "default#greenPoint"});

Ключ используется для того, чтобы выбрать нужный стиль из хранилища стилей YMaps.Styles.
Использовать хранилище стилей удобно, когда необходимо обращаться к стилям до их создания. Например, когда стили создаются в отдельном файле и загружаются после создания меток.

В хранилище можно добавить свои стили с помощью метода add(), а удалять – с помощью метода remove().

// Добавим созданный стиль в хранилище
YMaps.Styles.add("example#blueIcon", styleExample);

Теперь к добавленному стилю можно получить доступ по его ключу:

var style = YMaps.Styles.get("example#blueIcon");

Стиль можно задавать не только в конструкторе оверлея в виде параметра, но и с помощью метода setStyle().

placemark.setStyle("default#smallRedPoint");

С помощью метода setStyle() можно менять стиль оверлеев динамически во время выполнения скрипта.

Рассмотрим подробнее механизм стилей на примере смены значка у метки.

В API существует ряд стандартных, предопределенных стилей для значков с различными цветовыми решениями и размерами. Полный их список приведен в Справочнике по программному интерфейсу.

Возьмем стандартный стиль с ключом «deafult#greenPoint» и зададим его метке, тем самым поменяем цвет стандартного значка с светлого-голубого на зеленый.

var placemark = new YMasp.Placemark(map.getCenter(), {style : "default#greenPoint"});
map.addOverlay(placemark);

В качестве значка метки можно использовать любое пользовательское изображение.

Сменим значок на произвольное изображение.
Для этого необходимо создать экземпляр класса YMaps.IconStyle и определить у него три поля: ссылку на изображение (href), размер значка (size) и смещение изображения относительно точки позиционирования значка (offset).

// Создание стиля для метки
var styleExample = new YMaps.Style();
styleExample.iconStyle = new YMaps.IconStyle();
styleExample.iconStyle.href = "http://info.maps.yandex.net/api/i/steelblue/dot.png";
styleExample.iconStyle.size = new YMaps.Point(26, 46);
styleExample.iconStyle.offset = new YMaps.Point(-22, -46);
 
// Создание метки с измененным значком
var placemark = new YMasp.Placemark(map.getCenter(), {style : styleExample});
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Создадим пустой стиль:

var styleEmpty = new YMaps.Style();

Если применить вышеприведенный стиль к любому из оверлеев, то их внешний вид не изменится, хотя подстили не были определены.

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

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

Рассмотрим наследование стилей. Для этого разместим на карте несколько меток со значками футбольного, баскетбольного и теннисного мячей. Их размеры одинаковы и равны 20х20 px. Чтобы не дублировать описание стилей для каждой метки, создадим базовый стиль, который будет содержать информацию о размерах и смещении меток. Стили всех меток унаследуем от базового стиля.

// Создание базового стиля
var baseStyle = new YMaps.Style();
baseStyle.iconStyle = new YMaps.IconStyle();
baseStyle.iconStyle.offset = new YMaps.Point(-10, -10);
baseStyle.iconStyle.size = new YMaps.Point(20, 20);
 
// Наследуемся от базового стиля
var styleFootBall = new YMaps.Style(baseStyle);
styleFootBall.iconStyle = new YMaps.IconStyle();
styleFootBall.iconStyle.href = "/img/football.png";
 
// Наследуемся от базового стиля
var styleBasketBall = new YMaps.Style(baseStyle);
styleBasketBall.iconStyle = new YMaps.IconStyle();
styleBasketBall.iconStyle.href = "/img/basketball.png";
 
// Наследуемся от базового стиля
var styleTennis = new YMaps.Style(baseStyle);
styleTennis.iconStyle = new YMaps.IconStyle();
styleTennis.iconStyle.href = "/img/tennis.png";

Посмотреть пример отдельном окне 

Для элементов группы можно задать единый стиль. Для этого нужно передать ключ стиля (или указатель на стиль) в качестве параметра в конструктор класса YMaps.GeoObjectCollection и он будет применен ко всем элементам группы автоматически (стиль для группы можно также задать с помощью метода setStyle()):

var gCollection = new YMaps.GeoObjectCollection("default#greenPoint");

Посмотреть пример в отдельном окне

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

// Для всех меток группы задается зеленый значок
var gCollection = new YMaps.GeoObjectCollection("default#greenPoint");
gCollection.add([
    // У этой метки определен стиль - красный значок
    // Стиль группы не перекроет стиль этого объекта
    new YMaps.Placemark(new YMaps.GeoPoint(37.518234,55.708937), {style: "default#redPoint"}),
    new YMaps.Placemark(new YMaps.GeoPoint(37.514146,55.722294))
]));

Таким образом группа будет содержать две метки с красным и зеленым значками соответственно.

Стоит отметить, что если группы вложены одна в другую, то при формировании стиля для элементов группы будет учитываться и стиль родительской группы. Таким образом могут быть созданы целые цепочки наследования. По той же схеме происходит наследовании стилей, т. е. когда родительский стиль сам имеет своего родителя.

Рассмотрим цепочку наследования из трех стилей. В первом определим стиль обводки многоугольника, во втором – стиль заливки, а в третьем – стиль для значка метки. Пусть третий стиль наследуется от второго, а второй – от первого.

// Стиль обводки многоугольника
var stylePolygonOutline = new YMaps.Style();
stylePolygonOutline.polygonStyle = new YMaps.PolygonStyle();
stylePolygonOutline.polygonStyle.outline = true;
stylePolygonOutline.polygonStyle.strokeColor = "0000ff88";
stylePolygonOutline.polygonStyle.strokeWidth = 3;
 
// Стиль заливки многоугольника
// Наследуется от stylePolygonOutline
var stylePolygon = new YMaps.Style(stylePolygonOutline);
stylePolygon.polygonStyle = new YMaps.PolygonStyle();
stylePolygon.polygonStyle.fill = true;
stylePolygon.polygonStyle.fillColor = "0000ff33";
 
// Стиль значка метки
// Наследуется от stylePolygon
var styleIcon = new YMaps.Style(stylePolygon);
styleIcon.iconStyle = new YMaps.IconStyle();
styleIcon.iconStyle.href = "http://info.maps.yandex.net/api/i/steelblue/dot.png";
styleIcon.iconStyle.size = new YMaps.Point(26, 46);
styleIcon.iconStyle.offset = new YMaps.Point(-22, -46);

Теперь если применить третий стиль (styleIcon) к группе, состоящей из метки и многоугольника, то внешний вид обоих объектов будет изменен:

// Создание группы с заданным стилем для значка метки и многоугольника
var group = new YMaps.GeoObjectCollection(styleIcon);
group.add([
    new YMaps.Placemark(map.getCenter()),
    new YMaps.Polygon([new YMaps.GeoPoint(37.53, 55.77), new YMaps.GeoPoint(37.53, 55.83),new YMaps.GeoPoint(37.75, 55.83)])
]);
map.addOverlay(group);

Посмотреть пример в отдельном окне 

Создавать стили можно как обычные объекты Javascript, т. е. без вызова конструктора. Перепишем стиль styleIcon.

var styleIcon = {
    parentStyle : stylePolygon,
    iconStyle : {
        href : "http://info.maps.yandex.net/api/i/steelblue/dot.png",
        size : new YMaps.Point(26, 46),
        offset : new YMaps.Point(-22, -46
    }
}

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

 

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

Рассмотрим как можно менять адрес страницы, используя JavaScript. Для манипуляций с адресом страницы обратимся к глобальному объекту document.location, который содержит информацию об адресе текущего документа. Адрес текущей загруженной страницы можно изменить, используя свойство href объекта document.location.

Адрес на текущий фрагмент карты будем сохранять в HTML-элементе «Ссылка» в атрибуте href. Код для создания данного HTML-элемента выглядит следующим образом:

<a id="YMapsLink" href="#">Получить ссылку на карту</a>

Чтобы сформировать адрес на фрагмент карты, необходимо сохранять в ссылке центр карты, линейный размер области, а также тип карты.

Для перевода типа карты в строковое представление и обратно напишем небольшой класс TypeConverter, для перевода остальных параметров воспользуемся стандартным методом toString().

// Конвертер типов карт
// Если тип карты не был определен, то по умолчанию возвращается тип карты YMaps.MapType.MAP (или имя "map")
function TypeConverter () {
        // Доступные типы карты
    var types = [YMaps.MapType.MAP, YMaps.MapType.SATELLITE, YMaps.MapType.HYBRID],
 
        // Имена карт
        names = ["map", "sat", "hyb"];
 
    // Возвращает имя карты по ее типу
    this.typeToName = function (type) {
        return names[valid(YMaps.jQuery.inArray(type, types))];
    };
 
    // Возвращает тип карты по имени
    this.nameToType = function (name) {
        return types[valid(YMaps.jQuery.inArray(name, names))];
    };
 
    // Проверяет правильность полученного индекса
    function valid (index) {
        return (index == -1) ? 0 : index;
    }
};

Теперь приступим к формированию адреса на фрагмент карты. Сделать это несложно, для этого необходимо установить обработчики для событий карты BoundsChange и TypeChange.

// Динамически формируем URL
YMaps.Events.observe(map, [map.Events.BoundsChange, map.Events.TypeChange],  function () {
    YMaps.jQuery("#YMapsLink")
        .attr("href", "?l=" + typeConverter.typeToName(map.getType()) +
                      "&ll=" + map.getCenter().toString() +
                      "&spn=" + map.getBounds().getSpan().toString(6)
        );
});

В итоге ссылка будет иметь следующий вид:

?l=hyb&ll=37.664725,55.842762&spn=0.823971,0.309084

Напишем код, который будет обрабатывать параметры из ссылки и изменять параметры карты.

Для начала необходимо получить параметры из URL'а. Для этого напишем функцию, которая по имени параметра будет возвращать его значение.

// Получение параметра из URL'а
function getParam (name, location) {
    location = location || window.location.hash;
    var res = location.match(new RegExp('[#&]' + name + '=([^&]*)', 'i'));
    return (res && res[1] ? res[1] : '');
}

Далее создадим объект, который будет содержать все параметры, обнаруженные в URL'е.

// Получаем параметры из URL'а
var params = {
    ll : getParam("ll"),    // Центр карты
    spn : getParam("spn"),  // Линейный размер области
    t : getParam("t")       // Тип карты
};

С помощью метода fromString() можно создать объекты классов YMaps.GeoPoint и YMaps.Size из строкового представления.

По координатам центра и линейному размеру области с помощью метода класса YMaps.GeoBounds fromCenterAndSpan() можно определить область, которую необходимо отобразить на карте.

// Центрируем карту в нужном месте
map.setBounds(YMaps.GeoBounds.fromCenterAndSpan(YMaps.GeoPoint.fromString(params.ll), YMaps.Size.fromString(params.spn)));

Тип карты из строкового вида в объект переводим с помощью описанного выше класса TypeConverter:

// Устанавливаем требуемый тип карты
map.setType(typeConverter.nameToType(params.l));

Посмотреть пример в новом окне 

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

Посмотреть пример в новом окне

 

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

Текстовый шаблон – это HTML-строка (верстка), которая может содержать элементы вида $[имя_поля|значение_по_умолчанию]. Такие элементы заменяются данными из объекта-контекста, который передается в метод build() при разборе конкретного шаблона.

Под объектом-контекстом понимается объект, из которого должны браться данные для подстановки. Если объект не содержит данных, путь к которым указан в элементе, то элемент будет заменен пустой строкой или значением по умолчанию, если оно указано. Значение по умолчанию указывается сразу после символа "|".

Создадим свой шаблон для значка метки.

// Создание текстового шаблона для метки
var template = new YMaps.Template('<div><img src="http://info.maps.yandex.net/api/i/steelblue/dot.png"/>\
<div class="b-point-name">$[name|0]</div></div>');

Свяжем стиль с созданным текстовым шаблоном и применим его к метке.

// Создание стиля для значка метки
var styleIcon = new YMaps.Style();
 
// В конструктор стиля значка метки передается указатель на текстовый шаблон
styleIcon.iconStyle = new YMaps.IconStyle(template);
 
// Создание метки
var placemark = new YMaps.Placemark(map.getCenter(), {style: styleIcon});
placemark.name = 5;
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

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

 

YMaps.Templates.add("example#customPointIcon", template);

 

Тогда создание стиля можно будет записать так:

 

styleIcon.iconStyle = new YMaps.IconStyle("example#customPointIcon");

 

Таким образом значок для метки может быть не только изображение, а любое html-содержимое, которое будет задано в текстовом шаблоне.

Например, рассмотрим следующую задачу: для каждой метки в балуне нужно выводить заголовок зеленым цветом, а под описанием объекта – размещать логотип компании.
Можно решить эту задачу, записав необходимый html для каждого объекта в поля name и desctiption. Тогда определение содержимого одной метки будет выглядеть примерно так:

// Создание метки
var placemark = new YMaps.Placemark(map.getCenter());
 
// Определение содержимое балуна метки
placemark.name = '<span style="color: green">Имя объекта</span>';
placemark.description = '<div>Описание объекта</div><img src="http://img.yandex.ru/i/m_logo.png" alt=""/>';
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

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

Рассмотрим подробнее текстовый шаблон балуна по умолчанию.

<b>$[name]</b><div>$[description]</div>

Элементы name и description будут браться из объекта контекста. Если вызвать метод openBalloon() у метки, то объектом-контекстом будет сама метка.

var placemark = new YMaps.Placemark(map.getCenter());
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);
placemark.openBalloon();

 В итоге после построения шаблона балун будет иметь следующее содержимое:

<b>Имя объекта</b><div>Описание объекта</div>

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

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b style="color: green">$[name]</b><div>$[description]</div>\
        <img src="http://img.yandex.ru/i/m_logo.png" alt=""/>')
    }
}

Теперь применим созданный стиль к метке.

var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);

 Посмотреть пример на отдельной странице 

В итоге получен результат такой же, как если html был записан в поля name и description. Текстовые шаблоны позволяют избавляться от дублирования код (в текстовый шаблон можно вынести все повторяющиеся элементы, например, цвет заголовка и логотип компании).

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

Например, стоит задача: разместить на карте местоположения складов, а в балуне указывать количество единиц товара, которые на них в настоящее время присутствует. Если товара нет (количество единиц товара равно нулю), то необходимо вывести сообщение «нет в наличии». Дополнительную информацию необходимо размещать в поле metaDataProperty, чтобы избежать перекрытия стандартных полей и методов.

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b>$[name]</b><div>$[description]</div>\
        <div>Количество товара: $[metaDataProperty.anyMetaData.count|нет в наличии]</div>')
    }
}
 
var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Склад № 1";
placemark.description = "Центральный склад, расположенный в центре карты";
 
// Добавление дополнительной информации
placemark.metaDataProperty = {
    count : 100
}
 
map.addOverlay(placemark);

Если не определить поле placemark.metaDataProperty.count, то будет выведено сообщение по умолчанию «нет в наличии».
Посмотреть пример на отдельной странице

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

Рады видеть вас в блоге команды разработки API Яндекс.Карт. Здесь мы пишем обо всем новом, что происходит на сервисе, публикуем анонсы мероприятий и другую полезную информацию.

В блоге легко ориентироваться: вы сразу найдете интересующие вас темы по меткам.

Например, с меткой «статьи» мы выкладываем тексты наших разработчиков или ссылки на материалы пользователей об API Яндекс.Карт и о его возможностях.

С меткой «примеры» мы публикуем новые примеры использования API, которых пока нет в документации.

Если вас интересуют прошедшие и предстоящие мероприятия, на которых мы рассказываем про API, обратите внимание на метки «конференции» и «вебинар». А материалы докладов ищите по меткам «видео» и «презентации».

Чтобы открыть собственную тему, задать вопрос разработчикам, использующим API Яндекс.Карт, или опубликовать свою статью, воспользуйтесь клубом разработчиков API Яндекс.Карт.

Сайт API Яндекс.Карт
Документация API Яндекс.Карт
Страница API Яндекс.Карт в Facebook
Страница API Яндекс.Карт во ВКонтакте

-----

Эта статья относится к API Яндекс.Карт 1.x. Рекомендуем почитать аналогичную инструкцию для новой версии API — 2.0.

-----

API Яндекс.Карт используется для реализации множества различных сервисов: от простых схем проезда до почти полноценных ГИС. В зависимости от сложности решаемой задачи и «динамичности» данных, отображаемых на карте, используется свой подход и инструменты.

Схемы проезда обычно не меняются, а создаются один раз на продолжительный промежуток времени (например, до переезда офиса). Поэтому для их создания удобно воспользоваться визуальным инструментом «Конструктор схем проездов", который позволяет разметить необходимые объекты на карте и получить готовый код для вставки на страницу.

Недостатком «Конструктора схем проезда» является отсутствие возможности продолжить редактирование созданных карт. Поэтому для изменения объектов или их местоположение приходится создавать либо новую карту в конструкторе, либо редактировать JavaScript вручную. Такой проблемы не возникнет при использовании сервиса «Мои карты".

Сервис «Мои карты» позволяет отмечать на карте метки, изменять их внешний вид и описание, после чего можно поделиться ссылкой на созданную карту с друзьями. Карту, созданную в вышеописанном сервисе, можно разместить и у себя на сайте. Для этого необходимо воспользоваться возможностью экспорта объектов, размеченных на карте, в виде YMapsML. Более подробно про экспорт YMapsML можно прочитать в этом топике.

Чтобы добавить YMapsML-документ на карту, необходимо после ее инициализации вставить следующую строку (необходимо подставить свой URL):

map.addOverlay(new YMaps.YMapsML("http://maps.yandex.ru/export/usermaps/DwSVPt66C9uouT5tN_0YgE-D23KX7rM0/")

Посмотреть пример на отдельной странице

Объекты, размещенные на карте таким образом, можно редактировать через интерфейс «Моих карт». Другими словами все изменения, внесенные в карту на Яндекс.Картах, автоматически отразятся в соответствующем YMapsML.

При добавлении YMapsML-документа из "Моих карт" центр и масштаб карты подбирается таким образом, чтобы все добавленные метки были видны на карте. Такое поведение можно изменить, если при создании YMapsML в конструктор передать параметр viewAutoApply со значением false. 

map.addOverlay(

    new YMaps.YMapsML("http://maps.yandex.ru/export/usermaps/DwSVPt66C9uouT5tN_0YgE-D23KX7rM0/", {

        viewAutoApply : false

    })

Посмотреть пример на отдельной странице 

После окончания загрузки YMapsML-документа можно поменять внешний вид значков. Для этого необходимо создать обработчика события Load и в нем вызвать метод setStyle() для группы, в которой размещены метки:

var ml = new YMaps.YMapsML("http://maps.yandex.ru/export/usermaps/DwSVPt66C9uouT5tN_0YgE-D23KX7rM0/");

map.addOverlay(ml);

 

YMaps.Events.observe(ml, ml.Events.Load, function (ml) {

    ml.get(0).setStyle("default#mushroomIcon");

} 

Посмотреть пример на отдельной странице 

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

В клубе API Яндекс.Карт, при личных встречах вы нас часто просили сделать больше примеров, потому что, лучше один раз увидеть чем сто раз услышать!

Конечно, мы пошли на встречу вашим пожеланиям и сегодня рады представить обновленную страницу примеров использования JavaScript API 1.x Яндекс.Карт.
Теперь примеров аж 72 штуки и они разбиты на 16 групп, чтобы было удобнее найти нужный.

Группы отсортированы по сложности. Поэтому, чтобы увидеть в примерах весь процесс создания сложного проекта, просто начните сверху от "Основ использования карты" и просмотрите всё до блока "Карты, координатные системы".

Мы собрали все примеры о которых вы нас просили.

Нужно что-то ещё? Обязательно пишите!
Эта страница будет пополняться на основе ваших пожеланий.