Cómo recibir un vínculo (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

Los vínculos son un formato común de datos que los usuarios quieren compartir. A veces, el usuario comparte un vínculo de forma directa (por ejemplo, un artículo de un sitio web). La compatibilidad con vínculos también es útil como opción secundaria cuando los usuarios comparten contenido HTML o contenido que puede estar disponible en línea.

En este tema se muestra cómo recibir un solo vínculo que se va a compartir desde una aplicación de origen.

Lo que debes saber

Tecnologías

Requisitos previos

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

Instrucciones

Paso 1: Admitir el contrato para contenido compartido

Antes de 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 Microsoft 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 (package.manifest) en la vista de diseñador.
Abre la pestaña Declaraciones.
Elige la opción Compartir destino en la lista Declaraciones disponibles.
Haz clic en Agregar para agregar soporte para el Contrato para aceptar contenido compartido en tu aplicación.

Paso 2: Especifica que tu aplicación admite vínculos

Para admitir vínculos, necesitas especificar que tu aplicación admite el formato URI:

Abre el archivo de manifiesto.
En la sección Formatos de datos, haz clic en Agregar nuevo.
Escribe "text" (sin las comillas).

Los pasos anteriores agregan la siguiente sección al manifiesto:

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <DataFormat>uri</DataFormat>
    </ShareTarget>
  </Extension>
</Extensions>

Nota Puedes especificar un punto de entrada de diferente cuando tu aplicación se activa para el Contrato para aceptar contenido compartido. Para ello, modifica la entrada Página de inicio en la sección Configuración de la aplicación de la declaración Compartir contenido, en el manifiesto de la aplicación. Es muy recomendable que uses también un archivo de JavaScript diferente para administrar la activación de esta página. Para ver un ejemplo, consulta Muestra de una aplicación de destino de contenido compartido.

Paso 3: Agrega un controlador de eventos para detectar el momento en que se activa tu aplicación.

Cuando un usuario selecciona tu aplicación para compartir contenido, el sistema la activa. Como esto puede hacerse de muchas maneras, debes agregar el código que detecta el motivo por el que se produjo la activación. Para hacer esto, debes comprobar el valor de la propiedad kind.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        ...
    }
};

Si usas una página de inicio dedicada para el Contrato para aceptar contenido compartido, puedes omitir la comprobación de la propiedad kind

Paso 4: Obtén el objeto ShareOperation.

El objeto ShareOperation incluye todos los datos que tu aplicación necesita para obtener el contenido que un usuario quiere compartir.

shareOperation = args.detail.shareOperation;

Paso 5: Vuelve rápidamente del controlador del evento activado.

El controlador del evento activated debe volver rápidamente. Pon en cola un evento asincrónico del controlador del evento activated para que el procesamiento de los datos compartidos se realice después de que vuelva el evento activado.

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

Los pasos restantes implementan la función shareReady.

Paso 6: Comprueba si DataPackageView contiene un URI.

El objeto ShareOperation contiene un objeto DataPackageView. Este objeto es una versión de solo lectura del objeto DataPackage que la aplicación de origen usó para crear los datos. Usa este objeto para ver si el contenido que se va a compartir contiene un vínculo.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.uri)) {
    // Code to process URI goes here.
}

Es recomendable comprobar si DataPackage contiene el formato de datos que te interesa, aunque tu aplicación admita solo un formato. Esto facilita la compatibilidad posterior con otros tipos de datos y formatos de archivo.

Paso 7: Procesa el vínculo.

Para obtener el URI, llama al método DataPackageView.getUriAsync.

shareOperation.data.getUriAsync().then(function (uri) {
    if (uri != null) {
        // In this sample, we only display the URI. To output the link using this example, 
        // you need a div tag with an id of "output" in your HTML file.
        // In your app, replace this with whatever is appropriate for your scenario.
        document.getElementById("output").innerText = uri.absoluteUri;
    }
});

Paso 8: Llama a reportCompleted.

Una vez que la aplicación termina de compartir el contenido correctamente, llama a reportCompleted. Después de llamar a este método, el sistema descarta tu aplicación.

shareOperation.reportCompleted();

Observaciones

Algunas aplicaciones podrían proporcionar un Identificador uniforme de recursos (URI) que no comience por http:// o https://. Por ejemplo, una aplicación de origen podría proporcionar un protocolo de activación que llevara al usuario directamente al contenido en la propia aplicación. Si tu aplicación ya admite cualquier URI, tendrás esta funcionalidad de manera predeterminada. Si tu aplicación está limitada a ciertos tipos de URI, debes tener en cuenta lo siguiente:

Si admites HTML, usa en su lugar el HTML suministrado en el DataPackage.
Si no admites HTML pero sí texto, usa el texto en el DataPackage.
Si ninguna de las opciones anteriores funciona, considera la posibilidad de mostrar un mensaje que indique al usuario que no admites ese URI concreto.

En todos los casos, intenta incorporar el título y la descripción de los datos a tu experiencia. Esto proporciona al usuario más contexto sobre lo que se va a compartir.

Consulta el código de la Muestra de una aplicación de destino de contenido compartido para ver la experiencia completa de una aplicación que recibe una imagen como parte de un uso compartido.

Ejemplo completo

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.uri)) {
        shareOperation.data.getUriAsync().done(function (uri) {
            // In this sample, we only display the URI. To output the link using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            // In your app, replace this with whatever is appropriate for your scenario.
            document.getElementById("output").innerText = "Uri: " + uri.absoluteUri;
        });
    }
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The app was launced. Initialize as appropriate.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This app was been activated for the Share contract
        args.setPromise(WinJS.UI.processAll());

        // We receive the ShareOperation object as part of the eventArgs
        shareOperation = args.detail.shareOperation;


        // We queue an asychronous event so that working with the ShareOperation 
        // object does not block or delay the return of the activation handler.
        WinJS.Application.addEventListener("shareready", shareReady, false);
        WinJS.Application.queueEvent({ type: "shareready" });
    }
};