將次要磚釘選到工作列

發行項
08/09/2024

注意

生活磚是較新版本 Windows 不支援的 Windows 10 功能。針對新的應用程式，建議您遵循應用程式圖示的目前指引。

就如同將次要磚釘選至 [開始] 一樣，您可以將次要磚釘選至工作列，讓您的使用者快速存取應用程式中的內容。

重要

有限存取 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");
}

刪除圖標

如果您要從任何地方取消釘選磚 ([開始]、工作列)，請使用 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();

僅從 [開始] 取消釘選

如果您只想要從 [開始] 取消釘選次要磚，同時將它留在工作列上，您可以呼叫 StartScreenManager.TryRemoveSecondaryTileAsync 方法。如果磚不再釘選至任何其他介面，則此方法同樣會刪除磚。

此方法會傳回布林值，指出您的磚已不再釘選至 [開始]。如果您的磚未在第一個位置釘選，這也會傳 true回。如果不允許取消釘選或不支援 Start，則會傳 false回。

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

共用方式為