Inicio rápido: recepción de contenido compartido (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

Este inicio rápido te guiará por los pasos necesarios para recibir contenido compartido desde otra aplicación.

Objetivo: Para obtener información sobre cómo recibir contenido compartido.

Requisitos previos

Para usar el código que se describe en esta sección:

Debes estar familiarizado con Visual Studio y sus plantillas asociadas.
Debes estar familiarizado con JavaScript.

Instrucciones

1. Debes admitir el contrato para contenido compartido.

Para que tu aplicación pueda recibir contenido compartido, debes declarar que admite el contrato para contenido compartido. Este contrato permite que el sistema sepa que tu aplicación está disponible para recibir contenido. Si estás utilizando una plantilla de Visual Studio para crear tu aplicación, a continuación te mostramos la forma de admitir el contrato para contenido compartido:

Abre el archivo de manifiesto. Su nombre debe package.appxmanifest.
Abre la pestaña Declaraciones.
Elige la opción Compartir destino en la lista Declaraciones disponibles.

Para obtener más información, consulta el tema sobre la plantilla de elemento Contrato para aceptar contenido compartido.

2. Especificación de los tipos de archivo y formatos de datos admitidos

Como desarrollador de una aplicación de destino, deberás decidir qué tipos de archivo y formatos de datos quieres admitir. Para especificar los tipos de archivo admitidos:

Abre el archivo de manifiesto.
En la sección Tipos de archivo admitidos de la página Declaraciones, haz clic en Agregar nuevo.
Escribe la extensión del nombre de archivo que quieres admitir. Por ejemplo, .docx. Debes incluir el punto (.).

Si quieres admitir todos los tipos de archivo, activa la casilla Admite cualquier tipo de archivo.

Para especificar los formatos de datos admitidos:

Abre el archivo de manifiesto.
En la sección Formatos de datos, haz clic en Agregar nuevo.
Escribe el nombre del formato de datos que admites. Por ejemplo, "Texto".

Las API de recursos compartidos admiten varios formatos estándar, como texto, contenido HTML y mapas de bits. También puedes especificar tipos de archivo y formatos de datos personalizados. Si lo haces, recuerda que las aplicaciones de origen tienen que saber cuáles son esos tipos de formatos y archivos; de lo contrario, esas aplicaciones no compartirán datos de ese tipo.

3. Administración de la activación de recursos compartidos

Cuando un usuario selecciona tu aplicación, se desencadena un evento activated de aplicación. Tu aplicación debe controlar este evento para procesar los datos que el usuario quiere compartir. Debido a que hay muchos motivos por los que se puede activar un evento activated, lo primero que debes hacer es comprobar si el motivo del evento es compartir datos.

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

Los datos que el usuario quiere compartir están contenidos en un objeto ShareOperation. Puedes usar este objeto para comprobar el formato de los datos que contiene. A continuación, mostramos un ejemplo de un controlador de eventos que controla el contenido compartido como texto sin formato:

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. Informe de estado de uso compartido extendido (para operaciones prolongadas)

Nota

El siguiente paso afecta solo a las aplicaciones de la Tienda Windows. Puedes llamar a los siguientes métodos de generación de informes desde Windows Phone 8.1, pero no se devolverá ningún dato.

En algunos casos, es posible que tu aplicación tarde en procesar los datos que el usuario quiere compartir. Llamamos a estos casos de uso compartido uso compartido extendido. Entre los ejemplos de uso compartido extendido, se incluyen los usuarios que comparten colecciones de archivos o imágenes. Estos elementos son más grandes que una simple cadena de texto. Por lo tanto, necesitan más tiempo para procesarse.

Nota Si tu aplicación solo puede recibir cosas sencillas como texto o un hipervínculo, puedes omitir esta sección.

Como aplicación de destino, tu aplicación no debe obligar al usuario a permanecer en la interfaz de usuario de la aplicación tan solo porque tu aplicación necesita más tiempo para administrar los datos. En lugar de ello, debes usar el objeto ShareOperation para informar al sistema que tu aplicación aún está trabajando. De este modo, el usuario puede descartar la interfaz de usuario de la aplicación y continuar con sus actividades. Mientras tanto, tu aplicación sigue procesando los datos en segundo plano.

shareOperation.reportStarted();

Después de llamar a reportStarted, no habrá más interacción del usuario con tu aplicación. En consecuencia, no debes llamar a este método a menos que tu aplicación se encuentre en una etapa en la que el usuario puede descartarla.

Con un uso compartido extendido, es posible que el usuario quiera descartar la aplicación de origen antes de que tu aplicación tenga todos los datos del objeto DataPackage. Por lo tanto, te recomendamos que, cuando tu aplicación haya adquirido los datos que necesita, informes al sistema. De este modo, el sistema puede suspender o terminar la aplicación de origen según sea necesario.

shareOperation.reportDataRetreived();

En caso de que algo falle, también puedes llamar a reportError para enviar un mensaje de error al sistema. El usuario verá el mensaje al comprobar el estado del recurso compartido. En cuanto llames a reportError, se cerrará la aplicación y finalizará la operación de compartir. El usuario tendrá que iniciar de nuevo para compartir el mismo contenido de la aplicación. Según el escenario, es posible que decidas que un error en particular no es lo suficientemente grave como para terminar la operación de compartir. En ese caso, puedes optar por no llamar a reportError y continuar con la acción de compartir.

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

Cuando usas estos métodos, normalmente los llamas en el orden indicado anteriormente y no puedes llamarlos más de una vez. Sin embargo, hay veces en que una aplicación de destino puede llamar a reportDataRetrieved antes de reportStarted. Por ejemplo, la aplicación podría recuperar los datos como parte de una tarea en el controlador de activación, pero no llama a reportStarted hasta que el usuario hace clic en el botón Compartir.

Para ver cómo funciona este tipo de uso compartido de contenido, consulta nuestra muestra de una aplicación de destino de contenido compartido.

5. Informe de finalización de una operación de uso compartido

Por último, una vez que tu aplicación haya procesado correctamente el contenido compartido, debes llamar a reportCompleted.

shareOperation.reportCompleted();

Después de que tu aplicación informa que ha finalizado la operación de uso compartido, se descarta tu aplicación.

6. Devolución de un objeto Quicklink en operaciones de uso compartido correctas

Nota

Los QuickLinks no son compatibles con Windows Phone 8.1. Las aplicaciones de la Tienda de Windows Phone pueden recibir QuickLinks como parte de una operación de compartir, pero se omitirán automáticamente.

Cuando un usuario seleccione tu aplicación para recibir contenido compartido, te recomendamos que crees un QuickLink. Un QuickLink es como un acceso directo que hace que para los usuarios sea más fácil compartir información con tu aplicación. Por ejemplo, tu aplicación puede crear un QuickLink que abra un nuevo mensaje de correo configurado previamente con la dirección de correo electrónico de un amigo.

Cuando un usuario seleccione tu aplicación para recibir contenido compartido, te recomendamos que crees un QuickLink. Un QuickLink es un acceso directo que hace que para los usuarios sea más fácil compartir información con tu aplicación. Por ejemplo, tu aplicación puede crear un QuickLink que abra un nuevo mensaje de correo configurado previamente con la dirección de correo electrónico de un amigo.

Un QuickLink debe tener un título, un icono y un identificador. El título (por ejemplo, "Enviar correo electrónico a mamá") y el icono aparecen cuando el usuario pulsa el acceso a Compartir. El identificador es lo que la aplicación utiliza para identificar qué QuickLink se eligió. Cuando tu aplicación crea un QuickLink, la aplicación devuelve el QuickLink al sistema llamando al método reportCompleted del objeto ShareOperation. Este es un ejemplo:

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

Recuerda que tu aplicación es responsable de almacenar el identificador del QuickLink y los datos de usuario correspondientes. Cuando el usuario pulsa el QuickLink, puedes obtener su identificador mediante la propiedad ShareOperation.quickLinkId. Cuando una operación de compartir con un QuickLink es correcta, debes devolver el mismo QuickLink al llamar a reportCompleted.

Resumen y siguientes pasos

Seguro que ahora tienes una buena noción acerca de cómo recibir contenido compartido y cómo crear un QuickLink para ayudar a los usuarios a compartir contenido con tu aplicación.

Para obtener más información, u obtener más ejemplos específicos de cómo agregar recursos compartidos a tu aplicación, puedes leer lo siguiente:

Nota Depurar una aplicación de destino de contenido compartido es diferente de depurar otros tipos de aplicaciones. Para obtener más información, consulta las directrices para depurar aplicaciones de destino.