Cтили, шаблоны и макеты

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

Стили

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

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

var style = new YMaps.Style();

// Содержимое балуна
style.balloonContentStyle = new YMaps.BalloonContentStyle();

// Внешний вид балуна
style.balloonStyle = new YMaps.BaloonStyle();

// Флаг, определяющий возможность открытия над объектом балуна              
style.hasBalloon = true;

// Флаг, определяющий наличие у объекта всплывающей подсказки. 
style.hasHint = false;

// Содержимое всплывающей подсказки
style.hintContentStyle = new YMaps.HintContentStyle();

// Внешний вид всплывающей подсказки
style.hintStyle = new YMaps.HintStyle();

// Содержимое значка метки
style.iconContentStyle = new YMaps.IconContentStyle();

// Значок метки
style.iconStyle = new YMaps.IconStyle();    

// Стиль рисования линии
style.lineStyle = new YMaps.LineStyle();

// Родительский стиль
style.parentStyle = YMaps.Styles.DefaultStyleKey;

// Стиль рисования многоугольника           
style.polygonStyle = new YMaps.PolygonStyle();

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

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

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

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

// Создает базовый стиль для значка мяча
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 = "/i/maps/football.png";

// Стиль баскетбольного мяча наследует признаки базового стиля
var styleBasketBall = new YMaps.Style(baseStyle);
styleBasketBall.iconStyle = new YMaps.IconStyle();
styleBasketBall.iconStyle.href = "/i/maps/basketball.png";

// Стиль теннисного мяча наследует признаки базового стиля
var styleTennis = new YMaps.Style(baseStyle);
styleTennis.iconStyle = new YMaps.IconStyle();
styleTennis.iconStyle.href = "/i/maps/tennis.png";

Открыть пример в новом окне

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

// Создает метку со стилем, который будет создан позже
var placemark = new YMaps.Placemark(map.getCenter(), {style: "user#bluePoint"});

// Создает стиль метки
var s = new YMaps.Style();
s.iconStyle.offset = new YMaps.Point(-22, -46);
s.iconStyle.href = "http://info.maps.yandex.net/api/i/steelblue/dot.png";
s.iconStyle.size = new YMaps.Point(26, 46);

// Добавляет стиль в хранилище
YMaps.Styles.add("user#bluePoint", s);

// Добавление метки на карту
map.addOverlay(placemark);

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

Шаблоны

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

Шаблон представляет из себя HTML-строку, которая может содержать один или несколько элементов следующего вида:

$[имя_поля|значение_по_умолчанию]

При разборе шаблона эти элементы заменяются полями, взятыми из объекта-контекста, который передается в метод шаблона build().

Под объектом-контекстом понимается объект, содержащий данные для подстановки. Например, при вызове метода openBalloon() для метки объектом-контекстом для формирования содержимого балуна будет служить сама метка.

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

Для обращения к стилям объекта используйте следующую конструкцию:

$[style.<имя_поля>]

По умолчанию в балун выводятся значения полей name и description:

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

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

// С помощью этого шаблона оверлеи смогут "рассказать" о себе
var template = new YMaps.Template(
    "<b><span style=\"color:red\">Я</span> - $[name|объект]</b>\
    <div>$[description|Информация недоступна]</div>\
    <div>Подробнее <a href=\"http://api.yandex.ru/maps/jsapi/doc/$[metaDataProperty.moreLink]\">здесь</a></div>");

На основе шаблона template в примере создается новый стиль содержимого балуна:

var s = new YMaps.Style();
s.balloonContentStyle = new YMaps.BalloonContentStyle(template);

Стиль применен к двум меткам, при чем у одной метки заданы значения для подстановки в шаблон, а у другой - нет:

// Метка, у которой заданы поля name, description и moreLink
var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.69, 55.71), {style: s});
placemark.name = "метка";
placemark.description = "С помощью меток можно обозначать на карте различные объекты.";
placemark.metaDataProperty.moreLink = "dg/concepts/markers.xml";
map.addOverlay(placemark);

// Метка у которой поля с данными не определены 
// При подстановке значений в шаблон будут использованы значения по умолчанию
var placemark2 = new YMaps.Placemark(new YMaps.GeoPoint(37.58, 55.66), {style: s});
map.addOverlay(placemark2);

Открыть пример в новом окне

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

var template = new YMaps.Template("<div><img style=\"height:$[style.iconStyle.size.y]px;width:$[style.iconStyle.size.x]px;\" src=\"$[style.iconStyle.href]\"\/>\
              <div style=\"position:relative; top: -42px; left: 8px;\">$[name|0]</div></div>");

Открыть пример в новом окне

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

Макеты

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

Чтобы создать макет оверлея необходимо реализовать один из следующих интерфейсов:

Пример ниже демонстрирует как изменить внешний вид балуна. В примере создается класс SampleBalloonLayout, реализующий интерфейс YMaps.IBalloonLayout:

function SampleBalloonLayout() {
    this.element = YMaps.jQuery(
        "<div class=\"b-simple-balloon-layout\"><div class=\"content\"></div><div class=\"close\"></div><div class=\"tail\"></div></div>");
 
    this.close = this.element.find(".close");
    this.content = this.element.find(".content");
 
    // Отключает кнопку закрытия балуна
    this.disableClose = function(){
        this.close.unbind("click").css("display", "none");
    };
                
    // Включает кнопку закрытия балуна
    this.enableClose = function(callback){
        this.close.bind("click", callback).css("display", "");
        return false;
    };
 
    // Добавляет макет на страницу
    this.onAddToParent = function (parentNode) {
        YMaps.jQuery(parentNode).append(this.element);
    };
 
    // Удаляет макет со страницы
    this.onRemoveFromParent = function () {
        this.element.remove();
    };
 
    // Устанавливает содержимое балуна
    this.setContent = function (content) {
        content.onAddToParent(this.content[0]);
    };
                
    // Обновляет балун
    this.update = function() {
        this.element.css("margin-top", "-" + (this.content.height() + 45 ) + "px");
    };
};

Созданный макет обрабатывает событие закрытия балуна. Для того, чтобы установить содержимое балуна используйте метод оверлея setBalloonContent(), либо заполните поля name и description.

В примере ниже созданный макет SampleBalloonLayout используется для создания стиля метки:

var sampleBalloonTemplate = new YMaps.LayoutTemplate(SampleBalloonLayout);

var style = new YMaps.Style();
style.balloonStyle = {template: sampleBalloonTemplate};
var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76), {style: style});
placemark.description = "Описание метки";
map.addOverlay(placemark);

Открыть пример в новом окне