将辅助磁贴固定到任务栏

项目
08/09/2024

注意

生活磁贴是 Windows 10 功能，在更高版本的 Windows 上不受支持。对于新应用，建议遵循应用图标的当前指南。

就像将辅助磁贴固定到“开始”一样，可以将辅助磁贴固定到任务栏，让用户快速访问应用中的内容。

重要

有限的访问权限 API：此 API 是一项有限的访问功能。若要使用此 API，请联系 taskbarsecondarytile@microsoft.com。

需要 2018 年 10 月更新：必须以 SDK 17763 为目标，并运行内部版本 17763 或更高版本以固定到任务栏。

指南

利用辅助磁贴，用户可以一致并高效地直接访问应用中的特定区域。虽然用户可以选择是否将辅助磁贴“固定”到任务栏，但应用中的可固定区域由开发人员决定。有关更多指导，请参阅辅助磁贴指南。

1. 确定 API 是否存在并解锁有限的访问权限

较旧的设备没有任务栏固定 API（如果面向较旧版本的 Windows 10）。因此，不应在这些无法固定的设备上显示固定按钮。

此外，此功能在“有限的访问权限”下锁定。若要获取访问权限，请联系 Microsoft。对 TaskbarManager.RequestPinSecondaryTileAsync、TaskbarManager.IsSecondaryTilePinnedAsync 和 TaskbarManager.TryUnpinSecondaryTileAsync 的 API 调用将失败，出现“拒绝访问”异常。不允许应用在没有权限的情况下使用此 API，API 定义随时可能更改。

使用 ApiInformation.IsMethodPresent 方法确定 API 是否存在。然后使用 LimitedAccessFeatures API 尝试解锁 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. 获取 TaskbarManager 实例

Windows 应用可以在各种设备上运行；并非所有设备都支持任务栏。目前，只有桌面设备支持任务栏。此外，任务栏可能会时断时续。若要检查任务栏当前是否存在，请调用 TaskbarManager.GetDefault 方法，并检查返回的实例是否不为 null。如果任务栏不存在，则不显示固定按钮。

建议在单个操作（如固定）期间保留实例，然后在下次需要执行其他操作时抓取新实例。

TaskbarManager taskbarManager = TaskbarManager.GetDefault();

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

3. 检查磁贴当前是否已固定到任务栏

如果磁贴已固定，应改为显示取消固定按钮。可以使用 IsSecondaryTilePinnedAsync 方法检查磁贴当前是否已固定（用户可以随时取消固定）。在此方法中 TileId ，传递要知道的磁贴已固定。

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. 检查是否允许固定

固定到任务栏可以通过组策略禁用。 TaskbarManager.IsPinningAllowed 属性可用于检查是否允许固定。

当用户单击固定按钮时，应检查此属性，如果此属性为 false，应显示一个消息对话框，告知用户此计算机上不允许固定。

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. 构造并固定磁贴

用户已单击固定按钮，你已确定 API 存在、任务栏存在且允许固定...可以固定了！

首先，像固定到“开始”时一样构造辅助磁贴。若要详细了解辅助磁贴属性，可阅读将辅助磁贴固定到“开始”。但是，固定到任务栏时，除了以前所需的属性之外，还需要 Square44x44Logo（这也是任务栏使用的徽标）。否则，将引发异常。

然后，将磁贴传递给 RequestPinSecondaryTileAsync 方法。由于访问受限，因此这不会显示确认对话框，并且不需要 UI 线程。但在将来，当这超出了访问受限的范畴时，不使用有限的访问权限的调用方将收到一个对话框，要求其使用 UI 线程。

// 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);

此方法会返回一个布尔值，指明你的磁贴现在是否已固定到任务栏。如果磁贴已固定，该方法将更新现有磁贴并返回 true。如果不允许固定或不支持任务栏，该方法将 false返回。

枚举磁贴

若要查看创建的所有磁贴，并且仍固定在某个位置（开始、任务栏或两者），请使用 FindAllAsync。随后可以检查这些磁贴是否已固定到任务栏和/或“开始”。如果不支持此图面，这些方法将返回 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
    }
}

更新磁贴

若要更新已固定的磁贴，可以使用 SecondaryTile.UpdateAsync 方法，如更新辅助磁贴中所述。

取消固定磁贴

如果磁贴当前已固定，应用应提供取消固定按钮。若要取消固定磁贴，只需调用 TryUnpinSecondaryTileAsync，传入 TileId 要取消固定的辅助磁贴。

此方法会返回一个布尔值，指明你的磁贴不再固定到任务栏。如果磁贴未固定到第一位，则这也返回 true。如果不允许取消固定，则返回 false。

如果磁贴仅固定到任务栏，则会删除磁贴，因为它不再固定到任何位置。

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

删除磁贴

如果要从任意位置取消固定磁贴（Start、taskbar），请使用 RequestDeleteAsync 方法。

这适用于用户固定的内容不再适用的情况。例如，如果应用允许将笔记本固定到“开始”和任务栏，然后用户删除笔记本，则只需删除与笔记本关联的磁贴。

// 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();

仅从“开始”取消固定

如果只想在任务栏上离开时从 Start 中取消固定辅助磁贴，则可以调用 StartScreenManager.TryRemoveSecondaryTileAsync 方法。如果磁贴不再固定到任何其他图面，则同样会删除该磁贴。

此方法会返回一个布尔值，指明你的磁贴现在是否已固定到“开始”。如果磁贴未固定到第一位，则这也返回 true。如果不允许取消固定或不支持启动，则返回 false。

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

通过