Cómo admitir operaciones de extracción (HTML)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

La mayoría de las veces, la aplicación suministra los datos de forma inmediata desde su controlador de eventos datarequested. Sin embargo, algunas veces tu aplicación puede necesitar tiempo para preparar los datos para compartir. En esos momentos, puedes proporcionar una lista de los formatos admitidos y dejar la preparación y entrega de contenido hasta que la aplicación de destino lo solicite. Aplazar la entrega de contenido hasta que la aplicación de destino lo solicite se denomina operación de extracción (o uso compartido retrasado).

Para admitir operaciones de extracción, primero debes crear una función que empaquete los datos que quiere compartir el usuario. Entonces, en lugar de proporcionar los datos reales a la aplicación de destino, proporcionas una función delegada. Cuando la aplicación de destino intenta obtener los datos, el sistema llama a la función delegada. La ventaja en esto es que tu aplicación puede compartir los datos en segundo plano, lo que permite al usuario continuar usando tu aplicación para otras actividades.

Lo que debes saber

Tecnologías

Windows.ApplicationModel.DataTransfer

Requisitos previos

Debes estar familiarizado con Visual Studio y sus plantillas asociadas.
Debes estar familiarizado con JavaScript.
Debes saber cómo obtener archivos y otros datos, por ejemplo, mediante el FileOpenPicker. Puedes obtener más información en el tema sobre el acceso a archivos mediante selectores de archivos.

Instrucciones

Paso 1: Crear una función de controlador de botón para que el usuario pueda elegir un archivo de imagen

El siguiente código de controlador de botón permite que el usuario seleccione un archivo de imagen. Este archivo se usa en los siguientes pasos de este inicio rápido.

Nota

El siguiente código usa pickSingleFileAsync. En Windows Phone 8.1, se debe usar pickSingleFileAndContinue en su lugar.

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;
    });
}

Paso 2: Crea una función delegada para proporcionar el contenido que el usuario quiere compartir.

La naturaleza exacta de la función delegada depende de tu aplicación. Aquí tienes un ejemplo.

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

Observa que la función delegada usa setData para agregar el contenido, en lugar de una función específica para el formato, como setBitmap o setStorageItems. Cada vez que usas una función delegada, debes usar setData para proporcionar el contenido.

Paso 3: Configurar tu aplicación como origen de contenido compartido

El objeto DataTransferManager es el punto de partida principal para la operación de uso compartido de contenido. Agrega un controlador de eventos DataRequested para activarlo cuando el usuario quiera invocar el uso compartido. En una aplicación de la Tienda Windows, esto se produce automáticamente cuando el usuario invoca el acceso a Compartir. Si estás desarrollando para Windows Phone, no hay un acceso a Compartir integrado, por lo que tendrás que agregar un control para que el usuario pulse y active el controlador.

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

Los pasos restantes implementan la función sharePullHandler.

Paso 4: Obtener un objeto DataRequest

Cuando se produce un evento datarequested, tu aplicación recibe un objeto DataRequest. Este objeto contiene un DataPackage que podrías usar normalmente para proporcionar el contenido que el usuario quiere compartir. Sin embargo, en las operaciones de extracción deberás especificar una función delegada en lugar de datos reales.

var request = e.request;

Paso 5: Establecer las propiedades de título y descripción

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

Paso 6: Si es necesario, configura los tipos de archivo.

Si estás usando una función delegada para compartir archivos, necesitas especificar los tipos de archivo que admite tu aplicación.

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

Paso 7: Agregar la función delegada al objeto DataPackage

El método setDataProvider especifica a la función delegada que creaste para proporcionar el contenido real.

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

En este momento, cuando el usuario pulsa el acceso a Compartir, la aplicación puede responder de manera instantánea con un objeto DataPackage que incluye la función delegada. Ahora, la operación de uso compartido de contenido puede seguir ejecutándose en segundo plano, lo que libera al usuario para continuar con cualquier otra actividad que quiera.

Ten en cuenta que si usas el método setStorageItems para compartir archivos, este método crea objetos StorageFile de solo lectura para compartirlos y conserva los objetos originales. Esto significa que si agregas propiedades al archivo original después de llamar a setStorageItems, no se incluirán esas nuevas propiedades expandidas en los objetos StorageFile que se comparten. Por eso te recomendamos que no agregues los archivos hasta que estés totalmente listo.

Observaciones

Una aplicación que comparta datos que usen representación retrasada debe tener una sola página para evitar la navegación entre páginas. Además, si tu aplicación admite navegación dentro de los fotogramas, también debe usar contexto de script de nivel superior para registrar funciones delegadas en lugar de registrar delegados a nivel fotograma. La navegación hace que se pierda el contexto de script, lo cual invalida las funciones delegadas y genera errores en la representación retrasada.

Ejemplo completo

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());
    }
};