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'
}
});
Поддерживаемые параметры
Параметр |
Описание |
Возможные значения |
|
Текст, которым нужно поделиться. |
Строка. |
|
Изображение, которым нужно поделиться. |
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
}
});
Поддерживаемые параметры
Параметр |
Описание |
Возможные значения |
|
Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка. |
|
|
Цветовая схема кнопок соцсетей. |
|
|
Позиция кнопки Скопировать ссылку. Кнопка может отображаться в pop-up по нажатии |
Значение по умолчанию: |
|
Указание на мобильных устройствах вместо pop-up выводить окно, похожее на нативный инструмент Поделиться.
Источники данных для превьюКонтент в превью может не совпадать с контентом для соцсети. Картинка и описание для превью берутся из атрибутов Кнопка Другие для вызова нативного инструмента Поделиться и кнопка Скопировать ссылку присутствуют в окне, если такая возможность предусмотрена браузером. |
|
|
Направление списка кнопок. |
|
|
Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку. |
|
|
Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатии кнопки |
Натуральное число или отсутствие свойства. |
|
Вид кнопки открытия pop-up, если значение |
|
|
Идентификатор директивы Content Security Policy. Используется для подтверждения безопасности скрипта блока «Поделиться». |
Строка, сгенерированная сервером. |
|
Направление открытия pop-up. |
|
|
Расположение pop-up относительно контейнера блока. Значение |
|
|
Список идентификаторов социальных сетей, отображаемых в блоке. |
См. список идентификаторов поддерживаемых соцсетей. Несколько соцсетей указываются через запятую без пробела.
Значение по умолчанию: |
|
Форма кнопок соцсетей. |
|
|
Размер кнопок соцсетей. |
|
|
Указание, что страницу отправки ссылки нужно всегда открывать в новом окне или вкладке. Если атрибут не добавлять, страница может выводиться во всплывающем окне (возможность зависит от соцсети и браузера). |
|
hooks
Внутри этой группы вы можете указать свои функции, срабатывающие при наступлении определенного события блока.
Ya.share2('my-share', {
hooks: {
onready: function () {
alert('блок инициализирован');
},
onshare: function (name) {
alert('нажата кнопка' + 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();
}
}
});