Документация

API блока «Поделиться»

Если ваш сайт реализован в виде одностраничного приложения, вы можете встроить блок на любом DOM-элементе сайта с помощью API блока «Поделиться».

  1. Подключите скрипт блока. Если требуется поддержка старых браузеров (например, 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>
    Примечание. Внутри скрипта share2 не следует указывать атрибут async — с этим атрибутом API будет работать некорректно.
  2. Вызовите метод 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: 'It's all about Yandex',
        image: 'https://yastatic.net/morda-logo/i/logo.svg'   
    }
});
Поддерживаемые параметры
ПараметрОписаниеВозможные значения
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'
        }
    }
});

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

Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com',
        title: 'Yandex'
    },

    contentByService: {
        facebook: {
            url: 'https://ya.ru',
            title: 'Яндекс',
            accessToken: 'fb-token'
        }
    }
});

theme

Внутри группы theme можно указать параметры, относящиеся к внешнему виду блока:

Ya.share2('my-share', {
    theme: {
        services: 'gplus,facebook,lj,viber,twitter',
        counter: true,
        lang: 'uk',
        limit: 3,
        size: 's',
        bare: false
    }
});
Поддерживаемые параметры
ПараметрОписаниеВозможные значения
bare Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка.
  • true — стили не подгружаются;
  • false — стили подгружаются.

Значение по умолчанию: false

copy Позиция кнопки Скопировать ссылку. Кнопка Скопировать ссылку может отображаться, если используется параметр limit.
  • last — кнопка вверху списка;
  • first — кнопка внизу списка;
  • hidden — кнопка не отображается.

Значение по умолчанию: last

counter Признак того, что на кнопке соцсети отображается счетчик публикаций.
Внимание! На кнопке Твиттера счетчик публикаций отображаться не будет — Твиттер больше не поддерживает API с количеством публикаций.
  • true — счетчик включен;
  • false — счетчик выключен.

Значение по умолчанию: false

direction Направление списка кнопок.
  • horizontal — горизонтальное;
  • vertical — вертикальное.

Значение по умолчанию: horizontal.

lang Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку.
  • az — азербайджанский;
  • be — белорусский;
  • en — английский;
  • hy — армянский;
  • ka — грузинский;
  • kk — казахский;
  • ro — румынский;
  • ru — русский;
  • tr — турецкий;
  • tt — татарский;
  • uk — украинский.

Значение по умолчанию: ru.

limit Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатию кнопки . Натуральное число или отсутствие свойства.
popupDirection Направление открытия pop-up.
  • bottom — вниз;
  • top — вверх.

Значение по умолчанию: bottom.

popupPosition Расположение pop-up относительно контейнера блока. Значение outer может понадобиться в том случае, если из-за специфики верстки вашего сайта pop-up обрезается соседними элементами страницы.
  • inner — внутри контейнера;
  • outer — снаружи контейнера.

Значение по умолчанию: inner.

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

Значение по умолчанию: vkontakte,facebook,twitter

size Размер кнопок соцсетей.
  • m — большой ;
  • s — маленький .

Значение по умолчанию: m.

hooks

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

Ya.share2('my-share', {
    hooks: {
        onready: function () {
            alert('блок инициализирован');
        },

        onshare: function (name) {
            alert('нажата кнопка' + 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();
        }
    }
});