主要磚 API

  • 發行項

主要磚 API 可讓您查看您的應用程式目前是否已釘選至 [開始]，以及要求釘選您應用程式的主要磚。

重要

需要 Creators Update：您必須以 SDK 15063 為目標，並執行組建 15063 或更新版本，才能使用主要磚 API。

重要 API：StartScreenManager 類別、ContainsAppListEntryAsync、RequestAddAppListEntryAsync

使用主要磚 API 的時機

您投入很多心力為應用程式的主要磚設計出絕佳體驗，現在您有機會請使用者將它釘選到 [開始]。 不過，在我們深入探討程式碼之前，在您設計體驗的過程中務必牢記以下事項：

  • 請務必在應用程式中製作不會干擾且容易關閉的 UX，並提供清楚的「釘選動態磚」行動號召。
  • 請先清楚說明應用程式動態磚的價值，再詢問使用者是否要釘選它。
  • 請勿在已釘選應用程式的磚或裝置不支援此功能的情況下，詢問使用者是否要釘選磚 (詳細資訊如下)。
  • 請勿重複詢問使用者是否要釘選您應用程式的磚 (使用者可能會覺得很煩)。
  • 請勿在沒有明確使用者互動，或應用程式已最小化/未開啟的情況下，呼叫釘選 API。

查看 API 是否存在

如果您的應用程式支援舊版 Windows 10，您需查看這些主要磚 API 是否可用。 您可以使用 ApiInformation 執行這項操作。 如果主要磚 API 無法使用，請避免對 API 執行任何呼叫。

if (ApiInformation.IsTypePresent("Windows.UI.StartScreen.StartScreenManager"))
{
    // Primary tile API's supported!
}
else
{
    // Older version of Windows, no primary tile API's
}

查看 [開始] 是否支援您的應用程式

根據目前的 [開始] 功能表和您的應用程式類型而定，可能不支援將您的應用程式釘選到目前的 [開始] 畫面。 只有 Desktop 和 Mobile 支援將主要磚釘選到 [開始]。 因此，在顯示任何釘選 UI 或執行任何釘選程式碼之前，甚至需要先查看目前的 [開始] 畫面是否支援您的應用程式。 如果不支援，請勿提示使用者釘選磚。

// Get your own app list entry
// (which is always the first app list entry assuming you are not a multi-app package)
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// Check if Start supports your app
bool isSupported = StartScreenManager.GetDefault().SupportsAppListEntry(entry);

查看目前是否已釘選

若要確認您的主要磚目前是否已釘選到 [開始]，請使用 ContainsAppListEntryAsync 方法。

// Get your own app list entry
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// Check if your app is currently pinned
bool isPinned = await StartScreenManager.GetDefault().ContainsAppListEntryAsync(entry);

釘選主要磚

如果您的主要磚目前未釘選，且 [開始] 支援您的磚，您可能希望提示使用者可釘選您的主要磚。

注意

您必須在應用程式位於前景時，從U I 執行緒呼叫此 API，而且只能在使用者有意要求釘選主要磚時呼叫此 API (例如，使用者對您的釘選磚提示按一下 [是] 之後)。

如果使用者按下按鈕來釘選主要磚，您就會接著呼叫 RequestAddAppListEntryAsync 方法來要求將磚釘選到 [開始]。 這時會顯示對話方塊，要求使用者確認他們想要將磚釘選到 [開始]。

這時會傳回布林值，代表您的磚現在是否已釘選到 [開始]。 如果您的磚已釘選，這時會立即傳回 true，而不會對使用者顯示對話方塊。 如果使用者在對話方塊上按一下 [否]，或是不支援將磚釘選到 [開始]，這時就會傳回 false。 否則，使用者按一下 [是] 並釘選磚，且 API 會傳回 true。

// Get your own app list entry
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// And pin it to Start
bool isPinned = await StartScreenManager.GetDefault().RequestAddAppListEntryAsync(entry);

資源