Início rápido: afixando um bloco secundário (HTML)
[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]
Observação Não está usando JavaScript? Consulte Início rápido: afixando um bloco secundário (XAML).
Este tópico o orienta pelas etapas de criação de um bloco secundário para um aplicativo e de sua fixação na tela inicial.
Pré-requisitos
Para entender este tópico, você precisa de:
- Um conhecimento prático dos termos e conceitos de blocos secundários. Para mais informações, consulte Visão geral de blocos secundários.
- A capacidade de criar um aplicativo da Windows Store básico com JavaScript usando as APIs do Tempo de Execução do Windows. Para saber mais, veja Criar o seu primeiro aplicativo da Windows Store em JavaScript.
- Uma compreensão de como usar o Microsoft Visual Basic para criar código para um aplicativo da Windows Store com base em HTML.
Importante Para ver o código apresentado neste tópico usado em um exemplo completo, consulte o Exemplo de blocos secundários. O exemplo é mostrado nas versões em JavaScript, C#, C++ e Visual Basic.
Instruções
1. Adicionar uma barra de aplicativo com um botão de fixar/desafixar
No Windows, você normalmente apresenta uma oportunidade de fixação ao usuário através do botão Fixar na Tela Inicial na barra de aplicativos. Para informações sobre como criar uma barra de aplicativos, veja Início rápido: adicionando uma barra de aplicativo com comandos.
Observação Para os aplicativos da Loja do Windows Phone, a fixação é normalmente feita por meio de um menu de contexto, em vez de um botão na barra de aplicativos.
O seguinte exemplo declara uma barra de aplicativo com um botão. Este código é adicionado à página .html no seu projeto para o qual o resto do código neste tópico se aplica.
<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. Atribua uma ID exclusiva ao bloco secundário
var appbarTileId = "MySecondaryTile";
3. Criar uma função para definir o botão como fixar ou desafixar
A ação do botão Fixar se alterna entre fixar e desafixar o bloco secundário. Neste exemplo, criamos uma função para definir o botão adequadamente, usando ícones fornecidos pelo sistema para uma aparência consistente com outros aplicativos. Essa função é chamada de parte do código de inicialização do seu aplicativo, sempre que a barra de aplicativos é aberta e imediatamente após uma operação de fixar/desafixar com sucesso.
A linha final desta função define a propriedade WinJS.UI.sticky da barra de aplicativos como false, permitindo que a barra de aplicativos seja ignorada.
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. Exibir o botão adequado e atribuir um manipulador de clique do botão
Neste exemplo, como parte da inicialização do aplicativo, usamos a função setAppbarButton da última etapa para verificar se o bloco secundário já está fixado e tem o texto do botão definido de acordo.
Então, atribuímos o manipulador appbarButtonClicked ao evento click do botão de fixar. Mostraremos como implementar o manipulador de evento na próxima etapa.
Chame o código mostrado nesta etapa, junto com qualquer outra inicialização necessária para efetuar, como parte da inicialização do aplicativo, toda vez que o aplicativo for inicializado.
document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();
id("commandButton").addEventListener("click", appbarButtonClicked, false);
5. Criar e fixar o bloco secundário no manipulador de evento do botão
Este exemplo implementa uma única função que é chamada pelo manipulador de eventos de clique do botão de fixação. Essa função reúne várias etapas que levam à solicitação de fixação:
- Atribui valores de propriedade necessários à criação do bloco secundário
- Cria o objeto do bloco secundário
- Especifica as propriedades adicionais do bloco secundário
- Obtenha as coordenadas de tela usadas para exibir o submenu de confirmação (somente Windows)
Algumas propriedades do bloco secundário têm que ser definidas antes que ele seja fixado. Se você tentar fixar um bloco secundário sem uma ou mais dessas propriedades, a tentativa vai falhar. Estas são as propriedades necessárias:
- Uma ID exclusiva para o bloco
- Nome curto (somente Windows 8.0)
- Nome de exibição
- Uma sequência de argumento que é passada para o aplicativo pai quando o bloco secundário for ativado
- Uma imagem de logotipo.
- Opções de bloco (somente Windows 8.0)
Como uma amostra de cadeia de caracteres de argumento, este exemplo passa pelo momento em que o bloco secundário foi fixado na tela inicial.
Observação No Windows Phone 8.1, o nome de exibição nunca é exibido em um bloco secundário médio (150x150). Além disso, todos os blocos de telefone fixam inicialmente como blocos médios, então o parâmetro newTileDesiredSize é ignorado no telefone.
Observação Se você fornecer a mesma ID de um bloco secundário existente, o bloco secundário existente será substituído.
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;
Em seguida, nós criamos o objeto do bloco secundário. Esta versão do construtor cria um bloco médio. Observe que, se o seu bloco secundário recebe notificações, a prática recomendada é declarar todos os tamanhos de bloco. Isso é feito ao fornecer imagens de logo através da classe SecondaryTileVisualElements.
var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
newTileDesiredSize);
Agora que você tem um objeto de bloco secundário, especifique as propriedades do bloco secundário que não foram definidas pelo construtor. Este exemplo especifica a cor do texto em primeiro plano e do logotipo pequeno e especifica que o nome de exibição é mostrado no bloco.
Observação No Windows Phone 8.1, o logotipo pequeno e o nome de exibição não são exibidos no bloco secundário médio (150x150) e a cor de texto em primeiro plano não pode ser especificada, por isso, essas propriedades como definidas neste exemplo são ignoradas no telefone.
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");
No Windows, o usuário deve confirmar antes de fixar um bloco secundário. Na caixa de diálogo de confirmação, o usuário pode substituir o nome de exibição do bloco e selecionar de vários tamanhos de bloco a fixar. O submenu de confirmação deve ser exibido perto do botão que chamou a solicitação para fixar. Este exemplo traz o retângulo de vínculo do botão de fixar e especifica que a caixa de diálogo de confirmação deve exibir acima do botão.
Observação No Windows Phone 8.1, não é apresentada ao usuário nenhuma caixa de diálogo de confirmação; o bloco é simplesmente fixado à tela Inicial como bloco médio e sem nome de exibição. O código exibido aqui será ignorado.
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;
Em seguida, a função solicita a fixação do bloco secundário.
- No Windows Phone 8.1, esta chamada fixa o bloco, suspende o aplicativo e leva o usuário à tela Inicial.
- No Windows, essa chamada exibe o submenu de confirmação que solicita ao usuário a permissão para fixar o bloco. Com o uso do retângulo delimitador do botão de fixação, este exemplo exibe o submenu de confirmação acima das coordenadas. Com a aprovação do usuário, o Windows cria o bloco secundário e coloca-o na tela Inicial. O usuário permanece no aplicativo.
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
Observação No Windows Phone 8.1, uma chamada para RequestCreateAsync ou RequestCreateForSelectionAsync sai do aplicativo e leva o usuário à tela Inicial. Por isso, qualquer código que siga as chamadas RequestCreateAsync ou RequestCreateForSelectionAsync não serão executados. Portanto, nos projetos para Windows Phone 8.1, você deve ouvir eventos Suspending para que possa efetuar qualquer coisa, como salvar o estado do aplicativo, que precisa ser feito antes do aplicativo ser encerrado.
As funções appbarButtonClicked e pinByElementAsync completas das Amostras de bloco secundário são exibidas aqui.
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. Criar uma função de desafixação
Quando o bloco secundário já está fixado, o botão de fixação é transformado em botão de desafixação e o manipulador de eventos de clique do botão desafixa o bloco. Este exemplo apresenta a função que o manipulador chama para desafixar o bloco. Como parâmetros, a função aceita o objeto de botão de fixação, novamente com o propósito de inserir o submenu de confirmação e a ID exclusiva do bloco secundário. Como na função de fixação, a chamada para desafixar retorna um objeto Promise.
Observação Qualquer bloco secundário também pode ser desafixado através da barra de aplicativos da tela inicial. Você tem a opção de usar esse método para desafixar e, nesse caso, não precisa implementar a funcionalidade Desafixar nem inserir um botão Desafixar.
Observação No Windows Phone 8.1, o usuário não é solicitado por confirmação para desafixar um bloco secundário. Desafixar um bloco secundário no telefone é idêntico a desafixar qualquer outro bloco. O código exibido aqui será ignorado.
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 o manipulador de eventos para o seu botão
Quando o usuário seleciona o seu botão na barra de aplicativos, um submenu solicita que o usuário confirme. Para que a barra de aplicativos não seja ignorada quando o submenu é exibido, defina a propriedade WinJS.UI.sticky da barra de aplicativos. Além disso, verifique se o pai do submenu foi atribuído corretamente. Este exemplo chama as funções setAppbarButton, pinByElementAsync e unpinByElementAsync definidas nas etapas anteriores.
Observe que o manipulador chama setAppbarButton tanto para situações de sucesso e falha, nas duas operações de fixar e desafixar. Quando a operação é bem-sucedida, o botão se alterna entre fixar e desafixar. Quando há falha na operação, o botão permanece como está. Nos dois casos, a função tem de ser chamada para reverter a propriedade WinJS.UI.sticky para false, assim a barra de aplicativos pode ser ignorada.
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();
}
});
}
}
Resumo e próximas etapas
Neste Guia de início rápido, você definiu um botão na barra de aplicativos para o usuário fixar ou desafixar um bloco secundário. Você criou o bloco secundário, definiu diversas propriedades e apresentou a caixa de diálogo de confirmação para o usuário, resultando na adição final do bloco secundário à tela inicial.
Após a fixação de um bloco secundário, o aplicativo pai cria um URI (Uniform Resource Identifier) de canal para se comunicar com o bloco secundário. Para saber mais, veja Guia de início rápido: enviando uma notificação para um bloco secundário.
Tópicos relacionados
Visão geral dos blocos secundários
Guia de início rápido: enviando uma notificação para um bloco secundário