Как обеспечить поддержку операций отложенного общего доступа (HTML)

Статья
12/12/2015

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

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

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

Что необходимо знать

Технологии

Windows.ApplicationModel.DataTransfer

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

Вам должна быть знакома среда Visual Studio и связанные с ней шаблоны.
Вам необходимо знать JavaScript.
Вы должны знать, как получать файлы и другие данные, например с помощью FileOpenPicker. Подробнее см. в разделе Доступ к файлам с помощью средств выбора файлов.

Инструкции

Этап 1: Создание функции обработчика кнопки, чтобы пользователь мог выбрать файл изображения

Следующий код обработчика кнопки позволяет пользователю выбрать файл изображения. Этот файл используется на остальных шагах этого краткого руководства.

Примечание

В следующем коде используется pickSingleFileAsync. В Windows Phone 8.1 вместо этого нужно использовать pickSingleFileAndContinue.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

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

Точные характеристики функции делегирования зависят от вашего приложения. Рассмотрим один пример.

function onDeferredImageRequested(request) {
    if (imageFile) {
        var imageStreamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);
        request.setData(imageStreamRef);
    }
}

Обратите внимание, что функция делегирования использует setData при добавлении содержимого вместо функций определенного формата, таких как setBitmap или setStorageItems. При выборе функции делегирования вам нужно использовать setData для отправки содержимого.

Этап 3: Настройка приложения в качестве источника данных

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

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", sharePullHandler);

Остальные шаги выполняются для реализации функции sharePullHandler.

Этап 4: Получение объекта DataRequest

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

var request = e.request;

Этап 5: Настройка свойств заголовка и описания

request.data.properties.title = "Share Pull Example";
request.data.properties.description = "Demonstrates how to pull operations in share.";

Этап 6: При необходимости задайте типы файлов.

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

request.data.properties.fileTypes.replaceAll([".jpg", ".bmp", ".gif", ".png"]);

Этап 7: Добавление функции делегирования в объект DataPackage

Метод setDataProvider определяет созданную вами функцию делегирования, которая отправляет фактическое содержимое.

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

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

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

Замечания

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

Полный пример

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

function onDeferredImageRequested(request) {
    if (imageFile) {
        var imageStreamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);
        request.setData(imageStreamRef);
    }
}

function sharePullHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Pull Example";
    request.data.properties.description = "Demonstrates how to support pull operations in share.";
    request.data.properties.fileTypes.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register it as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", sharePullHandler);
            // Set up the button handler to pick an image file.
            document.getElementById("chooseImageButton").addEventListener("click", pickImageFile, false);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};