Fixar blocos secundários na barra de tarefas

Artigo
06/02/2023

Assim como fixar blocos secundários em Iniciar, você pode fixar blocos secundários na barra de tarefas, dando aos usuários acesso rápido ao conteúdo em seu aplicativo.

Importante

API de Acesso Limitado: essa API é um recurso de acesso limitado. Para usar essa API, entre em contato com taskbarsecondarytile@microsoft.com.

Requer atualização de outubro de 2018: você deve direcionar o SDK 17763 e executar o build 17763 ou posterior para fixar na barra de tarefas.

Diretrizes

Um bloco secundário fornece uma maneira consistente e eficiente de os usuários acessarem diretamente áreas específicas em um aplicativo. Embora um usuário escolha se deseja ou não "fixar" um bloco secundário na barra de tarefas, as áreas fixáveis em um aplicativo são determinadas pelo desenvolvedor. Para obter mais diretrizes, confira Diretrizes de bloco secundário.

1. Determinar se a API existe e desbloquear Limited-Access

Os dispositivos mais antigos não têm as APIs de fixação da barra de tarefas (se você estiver direcionando versões mais antigas do Windows 10). Portanto, você não deve exibir um botão fixar nesses dispositivos que não são capazes de fixar.

Além disso, esse recurso está bloqueado em Acesso Limitado. Para obter acesso, entre em contato com a Microsoft. As chamadas à API para TaskbarManager.RequestPinSecondaryTileAsync, TaskbarManager.IsSecondaryTilePinnedAsync e TaskbarManager.TryUnpinSecondaryTileAsync falharão com uma exceção acesso negado. Os aplicativos não têm permissão para usar essa API sem permissão e a definição da API pode ser alterada a qualquer momento.

Use o método ApiInformation.IsMethodPresent para determinar se as APIs estão presentes. Em seguida, use a API LimitedAccessFeatures para tentar desbloquear a API.

if (ApiInformation.IsMethodPresent("Windows.UI.Shell.TaskbarManager", "RequestPinSecondaryTileAsync"))
{
    // API present!
    // Unlock the pin to taskbar feature
    var result = LimitedAccessFeatures.TryUnlockFeature(
        "com.microsoft.windows.secondarytilemanagement",
        "<tokenFromMicrosoft>",
        "<publisher> has registered their use of com.microsoft.windows.secondarytilemanagement with Microsoft and agrees to the terms of use.");

    // If unlock succeeded
    if ((result.Status == LimitedAccessFeatureStatus.Available) ||
        (result.Status == LimitedAccessFeatureStatus.AvailableWithoutToken))
    {
        // Continue
    }
    else
    {
        // Don't show pin to taskbar button or call any of the below APIs
    }
}

else
{
    // Don't show pin to taskbar button or call any of the below APIs
}

2. Obter a instância TaskbarManager

Os aplicativos do Windows podem ser executados em uma ampla variedade de dispositivos; nem todos dão suporte à barra de tarefas. No momento, somente dispositivos desktop são compatíveis com a barra de tarefas. Além disso, a presença da barra de tarefas pode ir e vir. Para marcar se a barra de tarefas está presente no momento, chame o método TaskbarManager.GetDefault e marcar que a instância retornada não seja nula. Não exiba um botão fixar se a barra de tarefas não estiver presente.

É recomendável manter a instância durante uma única operação, como fixar e, em seguida, pegar uma nova instância na próxima vez que precisar fazer outra operação.

TaskbarManager taskbarManager = TaskbarManager.GetDefault();

if (taskbarManager != null)
{
    // Continue
}
else
{
    // Taskbar not present, don't display a pin button
}

3. Verifique se o bloco está fixado na barra de tarefas no momento

Se o bloco já estiver fixado, você deverá exibir um botão de desafixar. Você pode usar o método IsSecondaryTilePinnedAsync para marcar se o bloco está fixado no momento (os usuários podem desafixá-lo a qualquer momento). Nesse método, você passa a TileId do bloco que deseja saber que está fixada.

if (await taskbarManager.IsSecondaryTilePinnedAsync("myTileId"))
{
	// The tile is already pinned. Display the unpin button.
}

else 
{
	// The tile is not pinned. Display the pin button.
}

4. Verifique se a fixação é permitida

A fixação na barra de tarefas pode ser desabilitada por Política de Grupo. A propriedade TaskbarManager.IsPinningAllowed permite que você marcar se a fixação é permitida.

Quando o usuário clica no botão fixar, você deve marcar essa propriedade e, se ela for falsa, você deverá exibir uma caixa de diálogo de mensagem informando ao usuário que a fixação não é permitida neste computador.

TaskbarManager taskbarManager = TaskbarManager.GetDefault();
if (taskbarManager == null)
{
    // Display message dialog informing user that taskbar is no longer present, and then hide the button
}

else if (taskbarManager.IsPinningAllowed == false)
{
    // Display message dialog informing user pinning is not allowed on this machine
}

else
{
    // Continue pinning
}

5. Construir e fixar o bloco

O usuário clicou no botão fixar e você determinou que as APIs estão presentes, a barra de tarefas está presente e a fixação é permitida... hora de fixar!

Primeiro, construa seu bloco secundário da mesma forma que faria ao fixar em Iniciar. Você pode saber mais sobre as propriedades de bloco secundário lendo Fixar blocos secundários para Iniciar. No entanto, ao fixar na barra de tarefas, além das propriedades necessárias anteriormente, Square44x44Logo (esse é o logotipo usado pela barra de tarefas) também é necessário. Caso contrário, uma exceção será gerada.

Em seguida, passe o bloco para o método RequestPinSecondaryTileAsync . Como isso está sob acesso limitado, isso não exibirá uma caixa de diálogo de confirmação e não exigirá um thread de interface do usuário. No entanto, no futuro, quando isso for aberto além do acesso limitado, os chamadores que não utilizam acesso limitado receberão uma caixa de diálogo e serão obrigados a usar o thread da interface do usuário.

// Initialize the tile (all properties below are required)
SecondaryTile tile = new SecondaryTile("myTileId");
tile.DisplayName = "PowerPoint 2016 (Remote)";
tile.Arguments = "app=powerpoint";
tile.VisualElements.Square44x44Logo = new Uri("ms-appdata:///AppIcons/PowerPoint_Square44x44Logo.png");
tile.VisualElements.Square150x150Logo = new Uri("ms-appdata:///AppIcons/PowerPoint_Square150x150Logo.png");

// Pin it to the taskbar
bool isPinned = await taskbarManager.RequestPinSecondaryTileAsync(tile);

Esse método retorna um valor booliano que indica se o bloco agora está fixado na barra de tarefas. Se o bloco já estiver fixado, o método atualizará o bloco existente e retornará true. Se a fixação não for permitida ou não houver suporte para a barra de tarefas, o método retornará false.

Enumerar blocos

Para ver todos os blocos que você criou e ainda estão fixados em algum lugar (Iniciar, barra de tarefas ou ambos), use FindAllAsync. Posteriormente, você pode marcar se esses blocos estão fixados na barra de tarefas e/ou Iniciar. Se não houver suporte para a superfície, esses métodos retornarão false.

var taskbarManager = TaskbarManager.GetDefault();
var startScreenManager = StartScreenManager.GetDefault();

// Look through all tiles
foreach (SecondaryTile tile in await SecondaryTile.FindAllAsync())
{
    if (taskbarManager != null && await taskbarManager.IsSecondaryTilePinnedAsync(tile.TileId))
    {
        // Tile is pinned to the taskbar
    }

    if (startScreenManager != null && await startScreenManager.ContainsSecondaryTileAsync(tile.TileId))
    {
        // Tile is pinned to Start
    }
}

Atualizar um bloco

Para atualizar um bloco já fixado, você pode usar o método SecondaryTile.UpdateAsync , conforme descrito em Atualizando um bloco secundário.

Desafixar um bloco

Seu aplicativo deverá fornecer um botão de desafixar se o bloco estiver fixado no momento. Para desafixar o bloco, basta chamar TryUnpinSecondaryTileAsync, passando a TileId do bloco secundário que você gostaria de desafixar.

Esse método retorna um valor booliano que indica se o bloco não está mais fixado na barra de tarefas. Se o bloco não tiver sido fixado em primeiro lugar, isso também retornará true. Se não for permitido desafixar, isso retornará false.

Se o bloco tiver sido fixado apenas na barra de tarefas, isso excluirá o bloco, pois ele não está mais fixado em lugar nenhum.

var taskbarManager = TaskbarManager.GetDefault();
if (taskbarManager != null)
{
    bool isUnpinned = await taskbarManager.TryUnpinSecondaryTileAsync("myTileId");
}

Excluir um bloco

Se você quiser desafixar um bloco de todos os lugares (Iniciar, barra de tarefas), use o método RequestDeleteAsync .

Isso é apropriado para casos em que o conteúdo fixado pelo usuário não é mais aplicável. Por exemplo, se o aplicativo permitir que você fixe um bloco de anotações em Iniciar e na barra de tarefas e, em seguida, o usuário exclui o bloco de anotações, você deve simplesmente excluir o bloco associado ao bloco de anotações.

// Initialize a secondary tile with the same tile ID you want removed.
// Or, locate it with FindAllAsync()
SecondaryTile toBeDeleted = new SecondaryTile(tileId);

// And then delete the tile
await toBeDeleted.RequestDeleteAsync();

Desafixar somente de Iniciar

Se você quiser apenas desafixar um bloco secundário de Iniciar ao deixá-lo na Barra de Tarefas, poderá chamar o método StartScreenManager.TryRemoveSecondaryTileAsync . Isso excluirá o bloco da mesma forma se ele não estiver mais fixado em nenhuma outra superfície.

Esse método retorna um valor booliano que indica se o bloco não está mais fixado em Iniciar. Se o bloco não tiver sido fixado em primeiro lugar, isso também retornará true. Se não for permitido desafixar ou não houver suporte para Iniciar, isso retornará false.

await StartScreenManager.GetDefault().TryRemoveSecondaryTileAsync("myTileId");

Compartilhar via