Inicio rápido: Anclar un icono secundario (HTML)
[ 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
Nota ¿No usas JavaScript? Consulta Inicio rápido: Anclar un icono secundario (XAML).
Este tema te guía a través de los pasos para crear un icono secundario para una aplicación y anclarlo a la pantalla Inicio.
Requisitos previos
Para comprender este tema, necesitarás:
- Conocimientos prácticos sobre los términos y conceptos de iconos secundarios. Si quieres obtener más información, consulta la Introducción a los iconos secundarios.
- Capacidad para crear una aplicación de la Tienda Windows con JavaScript básica mediante las API de Windows en tiempo de ejecución. Para obtener más información, consulta el tema sobre cómo crear tu primera aplicación de la Tienda Windows con JavaScript.
- Conocimientos sobre el uso de Microsoft Visual Basic para crear código para una aplicación de la Tienda Windows basada en HTML.
Importante Para ver el código que se proporciona en este tema usado en una muestra completa, consulta la muestra de iconos secundarios. La muestra se proporciona en las versiones de JavaScript, C#, C++ y Visual Basic.
Instrucciones
1. Agregar una barra de la aplicación con un botón anclar/desanclar
En Windows, generalmente ofreces al usuario la oportunidad de anclaje mediante un botón Anclar a Inicio en la barra de la aplicación. Para obtener información acerca de cómo crear una barra de la aplicación, consulta Inicio rápido: agregar una barra de la aplicación con comandos.
Nota En las aplicaciones de la Tienda de Windows Phone, el anclaje suele llevarse a cabo mediante un menú contextual, en vez de mediante un botón en la barra de la aplicación.
En el siguiente ejemplo, se declara una barra de la aplicación con un botón. Este código se añade a la página .html de tu proyecto a la que se aplica el resto de código de este tema.
<div id="pinUnpinFromAppbar" data-win-control="WinJS.UI.AppBar" data-win-options="">
<button
data-win-control="WinJS.UI.AppBarCommand"
data-win-options="{id:'commandButton',section:'global'}">
</button>
</div>
2. Proporcionar un identificador único al icono secundario
var appbarTileId = "MySecondaryTile";
3. Crear una función para establecer el botón como anclar o desanclar
La acción del botón de anclaje alterna entre el anclaje y el desanclaje del icono secundario. En este ejemplo, creamos una función para establecer correctamente el botón, utilizando iconos proporcionados por el sistema para que el aspecto sea coherente con otras aplicaciones. Se llama a esta función como parte del código de inicialización de tu aplicación, cada vez que se abra la barra de la aplicación e inmediatamente después de una operación de anclaje/desanclaje correcta.
La línea final de esta función establece la propiedad WinJS.UI.sticky de la barra de la aplicación en false, lo que permite que se descarte que la barra.
function setAppbarButton() {
var commandButton = appBar.getCommandById("commandButton").winControl;
if (Windows.UI.StartScreen.SecondaryTile.exists(appbarTileId)) {
commandButton.label = "Unpin from Start";
commandButton.icon = "unpin";
} else {
commandButton.label = "Pin to Start";
commandButton.icon = "pin";
}
document.getElementById("pinUnpinFromAppbar").winControl.sticky = false;
}
4. Mostrar el botón apropiado y asignar un controlador de clic de botón
En este ejemplo, como parte de la inicialización de la aplicación, utilizamos la función setAppbarButton a partir del último paso para comprobar si el icono secundario ya está anclado y establecer el texto del botón en consonancia.
A continuación, asignamos el controlador appbarButtonClicked al evento click de botón de anclaje. Te mostraremos cómo implementar el controlador de eventos en el siguiente paso.
Llama al código que se muestra en este paso, junto con cualquier otra inicialización que debas realizar, como parte de la inicialización de tu aplicación cada vez que esta se inicia.
document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();
id("commandButton").addEventListener("click", appbarButtonClicked, false);
5. Crear y anclar el icono secundario en el controlador de evento de botón
Este ejemplo implementa una sola función que se puede llamar mediante el controlador de eventos de clic del botón de anclaje. Esta función reúne varios pasos que dan origen a la solicitud de anclaje:
- Asigna valores de propiedad necesarios para la creación de iconos secundarios
- Crea el objeto del icono secundario
- Especifica propiedades adicionales del icono secundario
- Obtiene las coordenadas de pantalla usadas para mostrar el control flotante de confirmación (solo en Windows)
Algunas de las propiedades del icono secundario deben establecerse con anterioridad para poder anclarlo. Si intentas anclar un icono secundario sin alguna de estas propiedades, no podrás hacerlo. Estas son las propiedades necesarias:
- Un identificador único para el icono
- Nombre corto (solo en Windows 8.0)
- Nombre para mostrar
- Una cadena de argumentos que se pasa a la aplicación principal cuando se active el icono secundario
- Una imagen de logotipo
- Opciones de icono (solo en Windows 8.0)
Como ejemplo de una cadena de argumentos, esta muestra pasa la hora en que el icono secundario se ancló a la pantalla Inicio.
Nota En Windows Phone 8.1, el nombre para mostrar no aparece nunca en un icono secundario mediano (150 x 150). Además, todos los iconos de teléfono se anclan inicialmente como iconos medianos, por lo que el parámetro newTileDesiredSize se ignora en el teléfono.
Nota Si proporcionas un identificador igual al del icono secundario existente, este último se sobrescribirá.
var currentTime = new Date();
var appbarTileId = "SecondaryTile.AppBar";
var newTileDisplayName = "Secondary tile pinned through app bar";
var TileActivationArguments = appbarTileId + " was pinned at " + currentTime;
var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
var newTileDesiredSize = Windows.UI.StartScreen.TileSize.square150x150;
A continuación, creamos el objeto de icono secundario. Esta versión del constructor crea un icono mediano. Ten en cuenta que si tu icono secundario recibe notificaciones, un procedimiento recomendado es declarar todos los tamaños de iconos. Esto se hace proporcionando imágenes de logotipo mediante la clase SecondaryTileVisualElements.
var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
newTileDesiredSize);
Ahora que ya tienes un objeto de icono secundario, puedes especificar las propiedades del icono secundario que no se establecen mediante el constructor. Este ejemplo especifica el color de texto en primer plano y un logotipo pequeño y especifica que el nombre para mostrar debe aparecer en el icono.
Nota En Windows Phone 8.1, en un icono secundario mediano (150 x 150) no aparecen ni el logotipo pequeño ni el nombre para mostrar y no puede especificarse el color de texto en primer plano, por lo que estas propiedades, tal y como se establecen en este ejemplo, se ignoran en el teléfono.
tile.visualElements.showNameOnSquare150x150Logo = true;
tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
tile.visualElements.square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");
En Windows, el usuario debe confirmar para que se pueda anclar un icono secundario. En el cuadro de diálogo de confirmación, el usuario puede invalidar el nombre para mostrar del icono y seleccionar entre varios tamaños de icono para anclaje. El control flotante de confirmación debe aparecer cerca del botón que invocó la solicitud de anclaje. En este ejemplo, se recupera el rectángulo de límite del botón de anclaje y se especifica que el cuadro de diálogo de confirmación debe aparecer encima del botón.
Nota En Windows Phone 8.1, el usuario no ve un cuadro de diálogo de confirmación; el icono simplemente se ancla a la pantalla Inicio como icono de tamaño medio y sin un nombre. El código que se muestra aquí se ignorará.
var element = document.getElementById("commandButton");
var selectionRect = element.getBoundingClientRect();
var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
var placement = Windows.UI.Popups.Placement.above;
A continuación, la función solicita el anclaje del icono secundario.
- En Windows Phone 8.1, esta llamada ancla el icono, suspende la aplicación y lleva al usuario a la pantalla Inicio.
- En Windows, esta llamada muestra el control flotante de confirmación que pide permiso al usuario para anclar el icono. Con el rectángulo de límite del botón de anclaje, este ejemplo muestra el control flotante de confirmación sobre esas coordinadas. Una vez que el usuario lo aprueba, Windows crea el icono secundario y lo coloca en la pantalla Inicio. El usuario permanece en la aplicación.
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
Nota En Windows Phone 8.1, una llamada a RequestCreateAsync o RequestCreateForSelectionAsync sale de la aplicación y lleva al usuario a la pantalla Inicio. Por este motivo, no se ejecutará el código que siga a la llamada a RequestCreateAsync o RequestCreateForSelectionAsync. Por tanto, en los proyectos en Windows Phone 8.1, debes prestar atención al evento Suspending para poder realizar una tarea que necesariamente haya que llevar a cabo antes de salir de la aplicación, como guardar el estado de la aplicación.
Aquí se muestran las funciones appbarButtonClicked y pinByElementAsync completas de la muestra de iconos secundarios.
function appbarButtonClicked() {
document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;
if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
if (isDeleted) {
WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
setAppbarButton();
}
});
} else {
pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "Appbar pinned secondary tile").done(function (isCreated) {
if (isCreated) {
WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
setAppbarButton();
}
});
}
}
function pinByElementAsync(element, newTileID, newTileDisplayName) {
var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
var square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");
var currentTime = new Date();
var TileActivationArguments = newTileID + " was pinned at=" + currentTime;
var tile = new Windows.UI.StartScreen.SecondaryTile(newTileID,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
Windows.UI.StartScreen.TileSize.square150x150);
tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
tile.visualElements.square30x30Logo = square30x30Logo;
tile.visualElements.showNameOnSquare150x150Logo = true;
var selectionRect = element.getBoundingClientRect();
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync({ x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height }, Windows.UI.Popups.Placement.above).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
}
6. Crear una función de desanclaje
Cuando el icono secundario ya está anclado, el botón de anclaje se convierte en uno de desanclaje y el controlador de eventos de clic del botón desancla el icono. Este ejemplo proporciona la función a la que llama el controlador para desanclar el icono. Como parámetros, la función acepta el objeto del botón de anclaje (nuevamente con el objetivo de colocar el control flotante de confirmación) y el identificador único del icono secundario. Al igual que en la función de anclaje, la llamada de desanclaje devuelve un objeto Promise.
Nota Los iconos secundarios también se pueden desanclar mediante la barra de la aplicación de la pantalla Inicio. Tienes la opción de confiar en ese método para desanclar, en cuyo caso no necesitas implementar funcionalidad de desanclaje ni proporcionar un botón para realizar esta tarea.
Nota En Windows Phone 8.1, no se solicita la confirmación del usuario para desanclar un icono secundario. El proceso para desanclar un icono secundario en el teléfono es idéntico al proceso para desanclar cualquier otro icono. El código que se muestra aquí se ignorará.
function unpinByElementAsync(element, unwantedTileID) {
var selectionRect = element.getBoundingClientRect();
var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
var placement = Windows.UI.Popups.Placement.above;
var tileToDelete = new Windows.UI.StartScreen.SecondaryTile(unwantedTileID);
return new WinJS.Promise(function (complete, error, progress) {
tileToGetDeleted.requestDeleteForSelectionAsync(buttonCoordinates, placement).done(function (isDeleted) {
if (isDeleted) {
complete(true);
} else {
complete(false);
}
});
});
}
7. Implementar el controlador de eventos del botón
Cuando el usuario selecciona el botón en la barra de la aplicación, un control flotante le pide confirmación. Para asegurarte de que no se descarte la barra de la aplicación mientras se muestra el control flotante, debes establecer la propiedad WinJS.UI.sticky de la barra de la aplicación. Asegúrate también de que el elemento primario del control flotante esté asignado correctamente. Este ejemplo llama a las funciones setAppbarButton, pinByElementAsync y unpinByElementAsync definidas en los pasos anteriores.
Ten en cuenta que el controlador llama a setAppbarButton en todas las operaciones de anclaje y desanclaje, tanto en las correctas como en las que producen errores. Si la operación se completó correctamente, el botón alternará entre anclaje y desanclaje. De lo contrario, permanecerá igual. En ambos casos, debe llamarse a la función para revertir la propiedad WinJS.UI.sticky a false para que pueda descartarse la barra de la aplicación.
function appbarButtonClicked() {
document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;
if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
if (isDeleted) {
WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
setAppbarButton();
}
});
} else {
pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "App bar pinned secondary tile", "A secondary tile that was pinned by the user from the app bar").done(function (isCreated) {
if (isCreated) {
WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
setAppbarButton();
}
});
}
}
Resumen y siguientes pasos
En este inicio rápido, definiste un botón en una barra de la aplicación con el que un usuario puede anclar o desanclar un icono secundario. Creaste el icono secundario, definiste muchas de sus propiedades y presentaste el cuadro de diálogo de confirmación al usuario, lo que da como resultado la adición final del icono secundario a la pantalla Inicio.
Después de anclar un icono secundario, el icono de la aplicación primaria crea un Identificador uniforme de recursos (URI) de canal para poder comunicarse con el icono secundario. Para más información, consulta el tema de inicio rápido: enviar una notificación a un icono secundario.
Temas relacionados
Introducción a los iconos secundarios
Inicio rápido: enviar una notificación a un icono secundario