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

Статья
12/12/2015

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

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

Цель: Научиться получать общее содержимое.

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

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

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

Инструкции

1. Поддержка контракта отправки данных

Чтобы ваше приложение могло получать общее содержимое, вам нужно объявить, что оно поддерживает контракт отправки данных. Этот контракт позволяет системе узнать о доступности вашего приложения для получения содержимого. Как обеспечить поддержку контракта отправки данных, если для создания приложения вы используете шаблон Visual Studio:

Откройте файл манифеста. Он должен иметь имя package.appxmanifest.
Откройте вкладку Объявления.
Выберите Share Target (Конечное приложение) из списка Available Declarations (Доступные объявления).

Подробнее см. в разделе Шаблон элемента контракта получателя данных.

2. Определение поддерживаемых типов файлов и форматов данных

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

Откройте файл манифеста.
В разделе Поддерживаемые типы файлов страницы Объявления нажмите кнопку Добавить.
Введите расширение имени файла, которое вы хотите поддерживать. Например, .docx. Не забудьте ввести точку (.).

Если вы хотите поддерживать все типы файлов, установите флажок SupportsAnyFileType.

Чтобы задать поддерживаемые форматы данных:

Откройте файл манифеста.
В разделе Форматы данных щелкните Добавить.
Введите имя формата данных, который вы хотите поддерживать. Например, "Text".

API общего доступа поддерживают несколько стандартных форматов, таких как текст, HTML и растровые изображения. Вы также можете задать пользовательские типы файлов и форматы данных. При этом помните: приложения-источники должны распознавать эти типы и форматы, иначе приложения не смогут обмениваться такими данными.

3. Обработка активации общего доступа

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

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

Данные, которые хочет предоставить пользователь, содержатся в объекте ShareOperation. Вы можете использовать этот объект, чтобы проверить формат содержащихся в нем данных. Вот пример обработчика событий, который принимает общее содержимое в формате обычного текста:

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. Отчет о состоянии расширенного общего доступа (для длительных операций)

Примечание

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

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

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

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

shareOperation.reportStarted();

После вызова метода reportStarted не стоит рассчитывать на продолжение взаимодействия пользователя с вашим приложением. Поэтому вам не следует вызывать этот метод, если пользователь еще не готов закрыть вашу программу.

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

shareOperation.reportDataRetreived();

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

shareOperation.reportError("Could not reach the server! Try again later.");

Если вы используете эти методы, применяйте их в указанном выше порядке и не вызывайте их больше одного раза. Бывают случаи, когда получающее приложение может вызывать reportDataRetrieved до reportStarted. Например, приложение может извлекать данные в рамках задачи обработчика события активации, но не вызывать reportStarted, пока пользователь не нажмет кнопку Общий доступ.

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

5. Отчет о завершении операции общего доступа

Наконец, когда ваша программа обработала общее содержимое, вам нужно вызвать метод reportCompleted.

shareOperation.reportCompleted();

Когда ваше приложение сообщает, что операция общего доступа завершена, оно закрывается.

6. Возвращение объекта QuickLink в случае успешного выполнения общего доступа

Примечание

Объекты QuickLink не поддерживаются в Windows Phone 8.1. Приложения Магазина Windows Phone могут получать объекты QuickLink в рамках операции общего доступа, но они автоматически пропускаются.

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

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

Объект QuickLink должен иметь название, значок и идентификатор. Название (например, "Написать маме") и значок появляются, когда пользователь касается чудо-кнопки "Поделиться". Идентификатор используется приложением для идентификации выбранного объекта QuickLink. Когда ваше приложение создает объект QuickLink, оно возвращает QuickLink системе, вызывая для этого метод reportCompleted объекта ShareOperation. Например, вот так:

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Помните, что ваше приложение отвечает за хранение идентификатора QuickLink и соответствующих пользовательских данных. Когда пользователь касается элемента QuickLink, вы можете получить его идентификатор с помощью свойства ShareOperation.quickLinkId. Если общий доступ к объекту QuickLink установлен успешно, следует возвращать тот же объект QuickLink при вызове reportCompleted.

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

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

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

Примечание Отладка приложения-получателя данных отличается от отладки других видов приложений. Подробнее см. в разделе Руководство по отладке приложений — получателей данных.

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

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

Краткое руководство. Общий доступ к содержимому