API блока «Поделиться»
Если ваш сайт реализован в виде одностраничного приложения, вы можете встроить блок на любом DOM-элементе сайта с помощью API блока «Поделиться».
Подключите скрипт блока. Если требуется поддержка старых браузеров (например, Internet Explorer 8), дополнительно подключите скрипт
es5-shims
. Этот скрипт должен быть подключен перед скриптом блока:<script src="https://yastatic.net/es5-shims/0.0.2/es5-shims.min.js"></script> <script src="https://yastatic.net/share2/share.js"></script>
Вызовите метод
Ya.share2
. Передайте методу идентификатор элемента и объект параметров.Метод
Ya.share2
возвращает экземпляр блока «Поделиться». Если вы сохраните экземпляр блока в переменную, то сможете использовать методы экземпляра блока.var share = Ya.share2('my-share', { content: { url: 'https://yandex.com' } // здесь вы можете указать и другие параметры });
Также вместо идентификатора вы можете передать сам элемент:
var myShare = document.getElementById('my-share'); var share = Ya.share2(myShare, { content: { url: 'https://yandex.com' } // здесь вы можете указать и другие параметры });
Внутри объекта параметры объединяются в группы:
- content — параметры контента, которым нужно поделиться;
- contentByService — параметры контента для каждого сервиса отдельно;
- theme — параметры внешнего вида блока;
- hooks — функции, которые нужно вызвать при наступлении одного из событий блока.
content
Внутри группы content можно указать параметры контента, которым нужно поделиться: адрес и заголовок страницы, ссылку на изображение, текст описания.
Ya.share2('my-share', {
content: {
url: 'https://yandex.com',
title: 'Yandex',
description: 'All about Yandex',
image: 'https://yastatic.net/morda-logo/i/logo.svg'
}
});
- Поддерживаемые параметры
-
Параметр Описание Возможные значения description Текст, которым нужно поделиться. Строка. image Изображение, которым нужно поделиться. URL изображения. title Заголовок, которым нужно поделиться. Строка. По умолчанию указывается заголовок страницы, на которой размещен блок.
url Ссылка, которой нужно поделиться. Любой URL. По умолчанию указывается URL страницы, на которой размещен блок.
Параметр Описание Возможные значения description Текст, которым нужно поделиться. Строка. image Изображение, которым нужно поделиться. URL изображения. title Заголовок, которым нужно поделиться. Строка. По умолчанию указывается заголовок страницы, на которой размещен блок.
url Ссылка, которой нужно поделиться. Любой URL. По умолчанию указывается URL страницы, на которой размещен блок.
Некоторые соцсети могут обрабатывать большие строки некорректно. Вы можете сразу указывать значения параметров контента с учетом этого или указать значения для таких соцсетей отдельно.
title
и description
и берут значения из семантической разметки страницы. О том, как использовать семантическую разметку, читайте в статьях Open Graph, Schema.org и Микроформаты.contentByService
Внутри группы contentByService
можно указать параметры контента для каждой соцсети отдельно. Например, это может понадобиться для Твиттера, где установлено ограничение на длину сообщения.
Также для Твиттера можно указать хэштеги. Несколько хэштегов указываются через запятую, без пробела и знака #
.
Ya.share2('my-share', {
content: {
url: 'https://yandex.com',
title: 'Yandex'
},
contentByService: {
twitter: {
url: 'https://ya.ru',
title: 'Яндекс',
hashtags: 'yandex,share'
}
}
});
theme
Внутри группы theme
можно указать параметры, относящиеся к внешнему виду блока:
Ya.share2('my-share', {
theme: {
services: 'messenger,lj,viber,twitter',
lang: 'uk',
limit: 3,
size: 's',
bare: false
}
});
- Поддерживаемые параметры
-
Параметр Описание Возможные значения bare Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка. true
— стили не подгружаются;false
— стили подгружаются.
Значение по умолчанию:
false
colorScheme Цветовая схема кнопок соцсетей. blackwhite
— белые иконки на черном фонеwhiteblack
— черные иконки на белом фонеnormal
— белые иконки на индивидуальном фоне
Значение по умолчанию:
normal
.copy Позиция кнопки Скопировать ссылку. Кнопка может отображаться в pop-up по нажатию , если используется атрибут limit
, или в основном списке соцсетей.first
— кнопка вверху списка в pop-up;last
— кнопка внизу списка в pop-up;hidden
— кнопка не отображается в pop-up;extraItem
— кнопка в основном списке.
Значение по умолчанию:
last
.curtain Указание на мобильных устройствах вместо pop-up выводить окно, похожее на нативный инструмент Поделиться.
В шапке окна отображается превью сайта.
Источники данных для превьюКонтент в превью может не совпадать с контентом для соцсети. Картинка и описание для превью берутся из атрибутов image и description. Если атрибуты image и description не указаны, данные подтягиваются из разметки Open Graph. Если описание не найдено в разметке Open Graph, оно подставляется из мета-тега description страницы. Если описания нет и там, берется текущий URL страницы.Кнопка Другие для вызова нативного инструмента Поделиться и кнопка Скопировать ссылку присутствуют в окне, если такая возможность предусмотрена браузером.
true
— заменять стандартный pop-up;false
— не заменять стандартный pop-up.
Значение по умолчанию:
false
direction Направление списка кнопок. horizontal
— горизонтальное;vertical
— вертикальное.
Значение по умолчанию:
horizontal
.lang Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку. - az — азербайджанский;
- be — белорусский;
- en — английский;
- hy — армянский;
- ka — грузинский;
- kk — казахский;
- ro — румынский;
- ru — русский;
- tr — турецкий;
- tt — татарский;
- uk — украинский;
- uz — узбекский.
Значение по умолчанию:
ru
.limit Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатию кнопки . Натуральное число или отсутствие свойства. moreButtonType Вид кнопки открытия pop-up, если значение limit равно 0
.long
— с надписьюshort
— без надписи- значение не задано — стандартный вид
nonce Идентификатор директивы Content Security Policy. Используется для подтверждения безопасности скрипта блока «Поделиться». Строка, сгенерированная сервером. popupDirection Направление открытия pop-up. bottom
— вниз;top
— вверх;auto
— по умолчанию вниз; если не вмещается вниз, то вверх; если не вмещается ни вниз, ни вверх, то вниз.
Значение по умолчанию:
bottom
.popupPosition Расположение pop-up относительно контейнера блока. Значение outer
может понадобиться в том случае, если из-за специфики верстки вашего сайта pop-up обрезается соседними элементами страницы.inner
— внутри контейнера;outer
— снаружи контейнера.
Значение по умолчанию: inner.
services Список идентификаторов социальных сетей, отображаемых в блоке. См. список идентификаторов поддерживаемых соцсетей. Несколько соцсетей указываются через запятую без пробела. Значение по умолчанию:
vkontakte,twitter
shape Форма кнопок соцсетей. round
— круглаяnormal
— прямоугольная со скругленными углами
Значение по умолчанию:
normal
.size Размер кнопок соцсетей. l
— большойm
— среднийs
— маленький
Значение по умолчанию:
m
.useLinks Указание, что страницу отправки ссылки нужно всегда открывать в новом окне или вкладке. Если атрибут не добавлять, страница может выводиться во всплывающем окне (возможность зависит от соцсети и браузера). true
— открывать новую вкладку или окно;false
— открывать всплывающее окно.
Значение по умолчанию:
false
Параметр Описание Возможные значения bare Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка. true
— стили не подгружаются;false
— стили подгружаются.
Значение по умолчанию:
false
colorScheme Цветовая схема кнопок соцсетей. blackwhite
— белые иконки на черном фонеwhiteblack
— черные иконки на белом фонеnormal
— белые иконки на индивидуальном фоне
Значение по умолчанию:
normal
.copy Позиция кнопки Скопировать ссылку. Кнопка может отображаться в pop-up по нажатию , если используется атрибут limit
, или в основном списке соцсетей.first
— кнопка вверху списка в pop-up;last
— кнопка внизу списка в pop-up;hidden
— кнопка не отображается в pop-up;extraItem
— кнопка в основном списке.
Значение по умолчанию:
last
.curtain Указание на мобильных устройствах вместо pop-up выводить окно, похожее на нативный инструмент Поделиться.
В шапке окна отображается превью сайта.
Источники данных для превьюКонтент в превью может не совпадать с контентом для соцсети. Картинка и описание для превью берутся из атрибутов image и description. Если атрибуты image и description не указаны, данные подтягиваются из разметки Open Graph. Если описание не найдено в разметке Open Graph, оно подставляется из мета-тега description страницы. Если описания нет и там, берется текущий URL страницы.Кнопка Другие для вызова нативного инструмента Поделиться и кнопка Скопировать ссылку присутствуют в окне, если такая возможность предусмотрена браузером.
true
— заменять стандартный pop-up;false
— не заменять стандартный pop-up.
Значение по умолчанию:
false
direction Направление списка кнопок. horizontal
— горизонтальное;vertical
— вертикальное.
Значение по умолчанию:
horizontal
.lang Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку. - az — азербайджанский;
- be — белорусский;
- en — английский;
- hy — армянский;
- ka — грузинский;
- kk — казахский;
- ro — румынский;
- ru — русский;
- tr — турецкий;
- tt — татарский;
- uk — украинский;
- uz — узбекский.
Значение по умолчанию:
ru
.limit Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатию кнопки . Натуральное число или отсутствие свойства. moreButtonType Вид кнопки открытия pop-up, если значение limit равно 0
.long
— с надписьюshort
— без надписи- значение не задано — стандартный вид
nonce Идентификатор директивы Content Security Policy. Используется для подтверждения безопасности скрипта блока «Поделиться». Строка, сгенерированная сервером. popupDirection Направление открытия pop-up. bottom
— вниз;top
— вверх;auto
— по умолчанию вниз; если не вмещается вниз, то вверх; если не вмещается ни вниз, ни вверх, то вниз.
Значение по умолчанию:
bottom
.popupPosition Расположение pop-up относительно контейнера блока. Значение outer
может понадобиться в том случае, если из-за специфики верстки вашего сайта pop-up обрезается соседними элементами страницы.inner
— внутри контейнера;outer
— снаружи контейнера.
Значение по умолчанию: inner.
services Список идентификаторов социальных сетей, отображаемых в блоке. См. список идентификаторов поддерживаемых соцсетей. Несколько соцсетей указываются через запятую без пробела. Значение по умолчанию:
vkontakte,twitter
shape Форма кнопок соцсетей. round
— круглаяnormal
— прямоугольная со скругленными углами
Значение по умолчанию:
normal
.size Размер кнопок соцсетей. l
— большойm
— среднийs
— маленький
Значение по умолчанию:
m
.useLinks Указание, что страницу отправки ссылки нужно всегда открывать в новом окне или вкладке. Если атрибут не добавлять, страница может выводиться во всплывающем окне (возможность зависит от соцсети и браузера). true
— открывать новую вкладку или окно;false
— открывать всплывающее окно.
Значение по умолчанию:
false
hooks
Внутри этой группы вы можете указать свои функции, срабатывающие при наступлении определенного события блока.
Ya.share2('my-share', {
hooks: {
onready: function () {
alert('блок инициализирован');
},
onshare: function (name) {
alert('нажата кнопка' + name);
}
}
});
- Поддерживаемые события
-
Событие Описание Аргументы onready Срабатывает при инициализации блока. — onshare Срабатывает при нажатии на кнопку соцсети. name
— название соцсети.Событие Описание Аргументы onready Срабатывает при инициализации блока. — onshare Срабатывает при нажатии на кнопку соцсети. name
— название соцсети.
Методы
Метод Ya.share2
возвращает экземпляр блока «Поделиться». Для каждого экземпляра блока доступны методы:
updateContent
— обновляет контент для всех сервисов;updateContentByService
— обновляет контент для отдельного сервиса;destroy
— очищает контейнер блока и удаляет все обработчики событий.
Вы можете вызвать эти методы, сохранив экземпляр блока в переменную. Если вы не сохранили экземпляр блока в переменную, вы можете вызвать методы внутри группы параметров hooks.
- updateContent
-
Метод позволяет переопределить параметры контента после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы content.
Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.
var share = Ya.share2('my-share', { content: { url: 'https://yandex.com' } // здесь вы можете указать и другие параметры }); share.updateContent({ title: 'Shiny share button', description: 'To rule them all', url: 'https://tech.yandex.ru/share/' });
- updateContentByService
-
Метод позволяет переопределить параметры контента для отдельного сервиса после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы contentByService.
Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.
var share = Ya.share2('my-share', { content: { url: 'https://yandex.com' } // здесь вы можете указать и другие параметры }); share.updateContentByService({ twitter: { title: 'Easy to share', url: 'https://tech.yandex.ru/share/' } });
- destroy
-
Метод позволяет очистить контейнер блока и удалить все обработчики событий.
Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.
var share = Ya.share2('my-share', { content: { url: 'https://yandex.com' } // здесь вы можете указать и другие параметры }); share.destroy();
- updateContent
-
Метод позволяет переопределить параметры контента после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы content.
Если вы не сохранили экземпляр блока в переменную, вы можете вызвать метод внутри группы параметров hooks.
Ya.share2('myshare', { hooks: { onready: function () { this.updateContent({ title: 'Shiny share button', description: 'To rule them all', url: 'https://tech.yandex.ru/share/' }); } } });
- updateContentByService
-
Метод позволяет переопределить параметры контента для отдельного сервиса после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы contentByService.
Если вы не сохранили экземпляр блока в переменную, вы можете вызвать метод внутри группы параметров hooks.
Ya.share2('myshare', { hooks: { onready: function () { this.updateContentByService({ twitter: { title: 'Easy to share', url: 'https://tech.yandex.ru/share/' }); } } } });
- destroy
-
Метод позволяет очистить контейнер блока и удалить все обработчики событий.
Если вы не сохранили экземпляр блока в переменную, вы можете вызвать метод внутри группы параметров hooks.
Ya.share2('myshare', { hooks: { onready: function () { this.destroy(); } } });