Поделиться через

Краткое руководство: общий доступ к содержимому (HTML)

  • Статья

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

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

Ниже описано, как работать с этими API. Если вас больше интересует, как ваше приложение может получать общее содержимое, см. раздел Краткое руководство: получение общего содержимого.

Цель: Ознакомившись с данным руководством, вы узнаете, как совместно использовать содержимое.

Необходимые условия

  • Вам должна быть знакома среда Visual Studio и ее шаблоны.
  • Вы должны быть знакомы с разработкой на HTML и JavaScript.

Инструкции

Выбор форматов данных

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

  • Обычный текст
  • Универсальные коды ресурсов (URI)
  • HTML
  • Форматированный текст
  • Растровые изображения
  • Файлы
  • Данные, определенные разработчиком

Объект DataPackage может содержать один или несколько указанных форматов в любом сочетании. Кроме того, DataPackage может содержать делегат — функцию, которая вызывается, когда принимающее приложение запрашивает данные. Мы рекомендуем использовать делегат, когда пользователь хочет предоставить общий доступ к ресурсоемким данным, так как это позволит вашему приложению обеспечивать общий доступ более эффективно.

Выбор свойств

При подготовке данных пакета к совместному использованию у вас есть возможность установить ряд свойств, дающих дополнительную информацию о содержимом, предназначенном для общего доступа. Благодаря этим свойствам конечное приложение может улучшить взаимодействие с пользователем. Например, предоставление названия и описания для совместно используемых данных может быть полезным, если пользователь предоставляет общий доступ более чем одному приложению. Добавление эскиза при совместном использовании рисунка или ссылки на веб-страницу поможет установить визуальную связь с пользователем. Подробнее о доступных свойствах: DataPackage.DataPackagePropertySet.

Настройка источника данных

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

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

Этот класс поддерживает событие DataRequested, которое запускается, когда пользователь вызывает общий доступ. В приложении Магазина Windows это выполняется автоматически, когда пользователь нажимает чудо-кнопку "Поделиться". Для Windows Phone чудо-кнопка "Поделиться" не предусмотрена, поэтому вам придется самостоятельно добавить элемент управления, которого должен будет коснуться пользователь для запуска этого обработчика.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

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

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

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

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Text Example";
    request.data.properties.description = "Demonstrates how to share text.";
    request.data.setText("Hello World!");
}

Общий доступ и делегаты

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

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

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

Программный вызов панели общего доступа

После определения содержимого для общего доступа оно готово к отправке. Все, что нужно сделать пользователю, — это выбрать приложение для получения содержимого. Если использование чудо-кнопки не оптимально (например, чтобы поделиться рекордом в игре), можно также программно задать срабатывание чудо-кнопки "Поделиться".

Примечание  

Charms bar отсутствует в Windows Phone 8.1, поэтому вы должны добавить параметр Коснуться и отправить программным способом. Возможность поделиться содержимым может быть всегда доступна на панели приложения либо связываться с определенным элементом управления на конкретной странице.

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

Обработка ошибок и решение проблем

В большинстве случаев предоставление содержимого — простой процесс. Однако бывают случаи, когда приложение не может обеспечить общий доступ. Чтобы вы могли справиться с подобными ситуациями в Windows 8.1, объект DataRequest поддерживает метод FailWithDisplayText. Используйте этот способ для отображения текстового сообщения пользователю, если последний не может получить общий доступ к содержимому из определенного представления или ему необходимо выполнить дополнительные действия для получения общего доступа. Например, приложение требует, чтобы пользователь выбрал содержимое для общего доступа, а пользователь ничего не выбрал.

Краткая сводка и дальнейшие действия

Теперь вы знаете, как работает общий доступ.

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

Связанные разделы

Выбор форматов данных для общего доступа

Рекомендации и контрольный список для общего доступа к содержимому

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