Idioma: HTML | XAML

Início rápido: fixando um bloco secundário (XAML)

Applies to Windows and Windows Phone

Observação  Não está usando C#/VB/C++? Consulte Início rápido: fixando um bloco secundário (HTML).

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 compreender 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 C# ou C++ usando as APIs do Tempo de Execução do Windows. Para saber mais, consulte Criar seu primeiro aplicativo da Windows Store em C# ou Visual Basic.
  • Uma compreensão de como usar o Microsoft Visual Basic para criar um código por trás do aplicativo da Windows Store baseado em Extensible Application Markup Language (XAML).

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. Opcional: adicionar namespaces

Para simplificar seu código, adicione as seguintes linhas ao arquivo .cs no seu projeto que contenha código (ou a versão dele) encontrado no resto deste Início rápido. Todo o código neste tópico presume que você adicionou tais linhas e não irá compilá-los de outra forma. O Windows.UI.StartScreen contém os objetos do bloco secundário e Windows.UI.Xaml.Controls é usado com barras de aplicativos e botões.



using Windows.UI.StartScreen;
using Windows.UI.Xaml.Controls;

2. 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 saber sobre como criar uma barra de aplicativos, veja Guia de início rápido: adicionando barras de aplicativos.

  • Applies to Windows Phone

No Windows Phone, a fixação é normalmente feita por meio do menu de contexto em vez de um botão na barra de aplicativos.

No Windows, quando o usuário seleciona o botão de fixar/desafixar, um submenu aparece para solicitar ao usuário a confirmação. Para manter a barra de aplicativo de ser descartada enquanto o submenu é exibido, defina a propriedade IsSticky como True.

Este código é adicionado à página .xaml no seu projeto para o qual o resto do código neste tópico é o code-behind.



<Page.BottomAppBar>
    <CommandBar x:Name="SecondaryTileCommandBar" Padding="10,0,10,0" IsSticky="True" IsOpen="True">
        <AppBarButton x:Name="PinUnPinCommandButton" Icon="Pin" Label="Pin" />
    </CommandBar>
</Page.BottomAppBar>

3. Dar uma ID exclusiva ao bloco secundário



public const string appbarTileId = "MySecondaryTile";

4. 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.



private void ToggleAppBarButton(bool showPinButton)
{
    if (showPinButton)
    {
        this.PinUnPinCommandButton.Label = "Pin to Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.Pin);
    }
    else
    {
        this.PinUnPinCommandButton.Label = "Unpin from Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.UnPin);
    }

    this.PinUnPinCommandButton.UpdateLayout();
}

5. 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 ToggleAppBarButton 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 pinToAppBar_Click 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.



void Init()
{
    ToggleAppBarButton(!SecondaryTile.Exists(MainPage.appbarTileId));
    this.PinUnPinCommandButton.Click += this.pinToAppBar_Click;
}

6. 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.

  • Applies to Windows Phone

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.



string displayName = "Secondary tile pinned through app bar";
string tileActivationArguments = MainPage.appbarTileId + " was pinned at=" + DateTime.Now.ToLocalTime().ToString();
Uri square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
TileSize newTileDesiredSize = 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 logotipo através da classe SecondaryTileVisualElements.



SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId, 
                                                displayName, 
                                                tileActivationArguments,
                                                square150x150Logo, 
                                                TileSize.Square150x150);

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.

  • Applies to Windows Phone

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.



secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;                       
secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;                        
secondaryTile.VisualElements.Square30x30Logo = new 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 recupera o retângulo delimitador do botão de fixação (“remetente”) e especifica que a caixa de diálogo de confirmação deve exibir acima do botão.

  • Applies to Windows Phone

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.



Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
Windows.UI.Popups.Placement 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.


bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

  • Applies to Windows Phone

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.

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 o código que o manipulador chama de forma assíncrona para desafixar o bloco. Novamente, essa chamada produz uma caixa de diálogo de confirmação em vez de realmente desafixar o bloco da tela Inicial. Após a aprovação, o Windows remove o bloco secundário da tela inicial.

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.



SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);

Por fim, nós revertemos a propriedade IsSticky da barra de aplicativos para false para que o submenu possa ser ignorado.



rootPage.BottomAppBar.IsSticky = false;

O manipulador de eventos pinToAppBar_Click completo é mostrado aqui. Observe que o manipulador chama ToggleAppBarButton após as duas operações de fixar e desafixar. Se a operação falhar, o botão não alterna.



async void pinToAppBar_Click(object sender, RoutedEventArgs e)
{
#if WINDOWS_APP
    this.SecondaryTileCommandBar.IsSticky = true;
#endif
    
    if (SecondaryTile.Exists(MainPage.appbarTileId))
    {
        // Unpin
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;
        
        bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);
    
        ToggleAppBarButton(isUnpinned);
    }
    else
    {
        // Pin
        Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
        string tileActivationArguments = MainPage.appbarTileId + " was pinned at = " + DateTime.Now.ToLocalTime().ToString();
        string displayName = "Secondary tile pinned through app bar";
    
        TileSize newTileDesiredSize = TileSize.Square150x150;
    
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId,
                                                        displayName, 
                                                        tileActivationArguments,
                                                        square150x150Logo,
                                                        newTileDesiredSize);
    
        Uri square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.Square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;
        secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;

#if WINDOWS_APP
        bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

        ToggleAppBarButton(!isPinned);
#endif

#if WINDOWS_PHONE_APP
       await secondaryTile.RequestCreateAsync();
#endif
    }

#if WINDOWS_APP
    this.BottomAppBar.IsSticky = false;
#endif
}

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

Exemplo de blocos secundários
Visão geral dos blocos secundários
Guia de início rápido: enviando uma notificação para um bloco secundário
Diretrizes e lista de verificação para blocos secundários
SecondaryTile class

 

 

Mostrar:
© 2014 Microsoft