Fixar blocos secundários na barra de tarefasPin secondary tiles to taskbar

Assim como fixação de blocos secundários para iniciar, você pode fixar blocos secundários na barra de tarefas, dando a seus usuários acesso rápido ao conteúdo em seu aplicativo.Just like pinning secondary tiles to Start, you can pin secondary tiles to the taskbar, giving your users quick access to content within your app.

Taskbar pinning

Importante

API de acesso limitado: essa API é um recurso de acesso limitado.Limited Access API: This API is a limited access feature. Para usar essa API, entre em contato com taskbarsecondarytile@microsoft.com .To use this API, please contact taskbarsecondarytile@microsoft.com.

Requer atualização de outubro de 2018: você deve ter como destino o SDK 17763 e executar o Build 17763 ou superior para fixar na barra de tarefas.Requires October 2018 Update: You must target SDK 17763 and be running build 17763 or higher to pin to taskbar.

OrientaçãoGuidance

Um bloco secundário fornece uma maneira consistente e eficiente para que os usuários acessem diretamente áreas específicas dentro de um aplicativo.A secondary tile provides a consistent, efficient way for users to directly access specific areas within an app. Embora um usuário decida se deseja ou não fixar um bloco secundário na barra de tarefas, as áreas fixas em um aplicativo são determinadas pelo desenvolvedor.Although a user chooses whether or not to "pin" a secondary tile to the taskbar, the pinnable areas in an app are determined by the developer. Para obter mais diretrizes, consulte diretrizes de bloco secundário.For more guidance, see Secondary tile guidance.

1. Determine se a API existe e desbloqueie o acesso limitado1. Determine if API exists and unlock Limited-Access

Dispositivos mais antigos não têm as APIs de fixação da barra de tarefas (se você estiver visando versões mais antigas do Windows 10).Older devices don't have the taskbar pinning APIs (if you're targeting older versions of Windows 10). Portanto, você não deve exibir um botão de PIN nesses dispositivos que não são capazes de fixar.Therefore, you shouldn't display a pin button on these devices that aren't capable of pinning.

Além disso, esse recurso está bloqueado em acesso limitado.Additionally, this feature is locked under Limited-Access. Para obter acesso, entre em contato com a Microsoft.To gain access, contact Microsoft. As chamadas à API para taskbarprovider. RequestPinSecondaryTileAsync, TaskbarManager. IsSecondaryTilePinnedAsync e TaskbarManager. TryUnpinSecondaryTileAsync falharão com uma exceção de acesso negado.API calls to TaskbarManager.RequestPinSecondaryTileAsync, TaskbarManager.IsSecondaryTilePinnedAsync, and TaskbarManager.TryUnpinSecondaryTileAsync will fail with an Access Denied exception. Os aplicativos não têm permissão para usar essa API sem permissão e a definição de API pode ser alterada a qualquer momento.Apps are not allowed to use this API without permission, and the API definition may change at any time.

Use o método ApiInformation. IsMethodPresent para determinar se as APIs estão presentes.Use the ApiInformation.IsMethodPresent method to determine if the APIs are present. E, em seguida, usar a API LimitedAccessFeatures para tentar desbloquear a API.And then use the LimitedAccessFeatures API to try unlocking the 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 da barra de tarefas2. Get the TaskbarManager instance

Os aplicativos do Windows podem ser executados em uma ampla variedade de dispositivos; Nem todos eles dão suporte à barra de tarefas.Windows apps can run on a wide variety of devices; not all of them support the taskbar. No momento, somente dispositivos desktop são compatíveis com a barra de tarefas.Right now, only Desktop devices support the taskbar. Além disso, a presença da barra de tarefas pode vir e ir.Additionally, presence of the taskbar might come and go. Para verificar se a barra de tarefas está presente no momento, chame o método taskbarprovider. GetDefault e verifique se a instância retornada não é nula.To check whether taskbar is currently present, call the TaskbarManager.GetDefault method and check that the instance returned is not null. Não exibir um botão de PIN se a barra de tarefas não estiver presente.Don't display a pin button if the taskbar isn't present.

É recomendável manter a instância do pela duração de uma única operação, como fixação e, em seguida, capturar uma nova instância na próxima vez que você precisar realizar outra operação.We recommend holding onto the instance for the duration of a single operation, like pinning, and then grabbing a new instance the next time you need to do another operation.

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 no momento na barra de tarefas3. Check whether your tile is currently pinned to the taskbar

Se o bloco já estiver fixado, você deverá exibir um botão Desafixar.If your tile is already pinned, you should display an unpin button instead. Você pode usar o método IsSecondaryTilePinnedAsync para verificar se o bloco está fixado no momento (os usuários podem desafixa-lo a qualquer momento).You can use the IsSecondaryTilePinnedAsync method to check whether your tile is currently pinned (users can unpin it at any time). Nesse método, você passa o tileid do bloco que você deseja saber que está fixado.In this method, you pass the TileId of the tile you want to know is pinned.

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 é permitida4. Check whether pinning is allowed

A fixação na barra de tarefas pode ser desabilitada por Política de Grupo.Pinning to the taskbar can be disabled by Group Policy. A propriedade TaskbarManager. IsPinningAllowed permite verificar se a fixação é permitida.The TaskbarManager.IsPinningAllowed property lets you check whether pinning is allowed.

Quando o usuário clica no botão PIN, você deve verificar essa propriedade e, se for false, deverá exibir uma caixa de diálogo de mensagem informando que o usuário que está sendo fixado não é permitido neste computador.When the user clicks your pin button, you should check this property, and if it's false, you should display a message dialog informing the user that pinning is not allowed on this machine.

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. construa e fixe seu bloco5. Construct and pin your tile

O usuário clicou no botão PIN e você determinou que as APIs estão presentes, a barra de tarefas está presente e a fixação é permitida... tempo para fixar!The user has clicked your pin button, and you've determined that the APIs are present, taskbar is present, and pinning is allowed... time to pin!

Primeiro, construa seu bloco secundário assim como faria ao fixar no início.First, construct your secondary tile just like you would when pinning to Start. Você pode saber mais sobre as propriedades de bloco secundários lendo fixar blocos secundários para iniciar.You can learn more about the secondary tile properties by reading Pin secondary tiles to Start. 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.However, when pinning to taskbar, in addition to the previously required properties, Square44x44Logo (this is the logo used by taskbar) is also required. Caso contrário, uma exceção será gerada.Otherwise, an exception will be thrown.

Em seguida, passe o bloco para o método RequestPinSecondaryTileAsync .Then, pass the tile to the RequestPinSecondaryTileAsync method. 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.Since this is under limited-access, this will not display a confirmation dialog and does not require a UI thread. Mas 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 precisarão usar o thread da interface do usuário.But in the future when this is opened up beyond limited-access, callers not utilizing limited-access will receive a dialog and be required to use the UI thread.

// 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.This method returns a boolean value that indicates whether your tile is now pinned to the taskbar. Se o bloco já foi fixado, o método atualiza o bloco existente e retorna true.If your tile was already pinned, the method updates the existing tile and returns true. Se a fixação não tiver sido permitida ou a barra de tarefas não tiver suporte, o método retornará false.If pinning wasn't allowed or taskbar isn't supported, the method returns false.

Enumerar blocosEnumerate tiles

Para ver todos os blocos que você criou e que ainda estão fixados em algum lugar (Iniciar, barra de tarefas ou ambos), use FindAllAsync.To see all the tiles that you created and are still pinned somewhere (Start, taskbar, or both), use FindAllAsync. Em seguida, você pode verificar se esses blocos estão fixados na barra de tarefas e/ou iniciar.You can subsequently check whether these tiles are pinned to the taskbar and/or Start. Se a superfície não tiver suporte, esses métodos retornarão false.If the surface isn't supported, these methods return 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 blocoUpdate a tile

Para atualizar um bloco já fixado, você pode usar o método SecondaryTile. UpdateAsync conforme descrito em atualizando um bloco secundário.To update an already pinned tile, you can use the SecondaryTile.UpdateAsync method as described in Updating a secondary tile.

Desafixar um blocoUnpin a tile

Seu aplicativo deverá fornecer um botão Desafixar se o bloco estiver fixado no momento.Your app should provide an unpin button if the tile is currently pinned. Para desafixar o bloco, basta chamar TryUnpinSecondaryTileAsync, passando o tileid do bloco secundário que você gostaria de desafixado.To unpin the tile, simply call TryUnpinSecondaryTileAsync, passing in the TileId of the secondary tile you would like unpinned.

Esse método retorna um valor booliano que indica se o bloco não está mais fixado na barra de tarefas.This method returns a boolean value that indicates whether your tile is no longer pinned to the taskbar. Se o bloco não foi fixado em primeiro lugar, isso também retorna verdadeiro.If your tile wasn't pinned in the first place, this also returns true. Se a desanexação não for permitida, isso retornará false.If unpinning wasn't allowed, this returns false.

Se seu bloco foi fixado apenas na barra de tarefas, isso excluirá o bloco, pois ele não está mais fixado em nenhum lugar.If your tile was only pinned to taskbar, this will delete the tile since it is no longer pinned anywhere.

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

Excluir um blocoDelete a tile

Se você quiser Desafixar um bloco de qualquer lugar (Iniciar, barra de tarefas), use o método RequestDeleteAsync .If you want to unpin a tile from everywhere (Start, taskbar), use the RequestDeleteAsync method.

Isso é apropriado para casos em que o conteúdo fixado pelo usuário não é mais aplicável.This is appropriate for cases where the content the user pinned is no longer applicable. Por exemplo, se seu aplicativo permitir que você fixe um bloco de anotações para iniciar e barra de tarefas e, em seguida, o usuário excluir o bloco de anotações, você deverá simplesmente excluir o bloco associado ao bloco de anotações.For example, if your app lets you pin a notebook to Start and taskbar, and then the user deletes the notebook, you should simply delete the tile associated with the notebook.

// 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 apenas do inícioUnpin only from Start

Se você quiser Desafixar um bloco secundário do início ao deixá-lo na barra de tarefas, poderá chamar o método StartScreenManager. TryRemoveSecondaryTileAsync .If you only want to unpin a secondary tile from Start while leaving it on Taskbar, you can call the StartScreenManager.TryRemoveSecondaryTileAsync method. Assim, isso excluirá o bloco se ele não estiver mais fixado em nenhuma outra superfície.This will similarly delete the tile if it is no longer pinned to any other surfaces.

Esse método retorna um valor booliano que indica se o bloco não está mais fixado para iniciar.This method returns a boolean value that indicates whether your tile is no longer pinned to Start. Se o bloco não foi fixado em primeiro lugar, isso também retorna verdadeiro.If your tile wasn't pinned in the first place, this also returns true. Se a desanexação não for permitida ou iniciar não tiver suporte, isso retornará false.If unpinning wasn't allowed or Start isn't supported, this returns false.

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

RecursosResources