SecondaryTile 類別

定義

命名空間:

Windows.UI.StartScreen

建立、列舉和提供次要磚的相關資訊。

在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件 ，以及 從傳統型應用程式釘選次要磚。

public ref class SecondaryTile sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.StartScreen.ISecondaryTileFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.StartScreen.ISecondaryTileFactory2, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class SecondaryTile final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.StartScreen.ISecondaryTileFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.StartScreen.ISecondaryTileFactory2), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class SecondaryTile

function SecondaryTile(tileId, shortName, displayName, arguments, tileOptions, logoReference, wideLogoReference)

Public NotInheritable Class SecondaryTile

繼承

Object Platform::Object IInspectable SecondaryTile

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

下列範例會建立次要磚，並將其釘選到 [開始] 畫面。

using Windows.UI.StartScreen;

// Prepare package images for all four tile sizes in our tile to be pinned as well as for the square30x30 logo used in the Apps view.  
Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
Uri wide310x150Logo = new Uri("ms-appx:///Assets/wide310x150Tile-sdk.png");
Uri square310x310Logo = new Uri("ms-appx:///Assets/square310x310Tile-sdk.png"); 
Uri square30x30Logo = new Uri("ms-appx:///Assets/square30x30Tile-sdk.png");

// During creation of secondary tile, an application may set additional arguments on the tile that will be passed in during activation.
// These arguments should be meaningful to the application. In this sample, we'll pass in the date and time the secondary tile was pinned.
string tileActivationArguments = MainPage.logoSecondaryTileId + " WasPinnedAt=" + DateTime.Now.ToLocalTime().ToString();

// Create a Secondary tile with all the required arguments.
// Note the last argument specifies what size the Secondary tile should show up as by default in the Pin to start fly out.
// It can be set to TileSize.Square150x150, TileSize.Wide310x150, or TileSize.Default.  
// If set to TileSize.Wide310x150, then the asset for the wide size must be supplied as well.
// TileSize.Default will default to the wide size if a wide size is provided, and to the medium size otherwise. 
SecondaryTile secondaryTile = new SecondaryTile(MainPage.logoSecondaryTileId,
                                                "Title text shown on the tile",
                                                tileActivationArguments,
                                                square150x150Logo,
                                                TileSize.Square150x150);

// Pin the tile
bool isPinned = await tile.RequestCreateAsync();
if (isPinned) {
    // Secondary tile successfully pinned.
} 
else {
    // Secondary tile not pinned.
}

下列範例示範如何使用 RequestDeleteAsync 方法來刪除 (取消釘選) 次要磚。 請注意，此範例假設磚存在。 若要判斷磚是否在呼叫 RequestDeleteAsync之前釘選，請參閱 Exists 方法。

// Check if the secondary tile is pinned
if (SecondaryTile.Exists(tileId)) {
    // Initialize a secondary tile with the same tile ID you want removed
    SecondaryTile toBeDeleted = new SecondaryTile(tileId);

    // And then unpin the tile
    bool isDeleted = await toBeDeleted.RequestDeleteAsync();
    if (isDeleted) {
        // Secondary tile successfully deleted.
    } else {
        // Secondary tile not deleted.
    }
}

下列範例示範如何使用 FindAllForPackageAsync 方法來擷取針對呼叫應用程式所建立之所有次要磚的識別碼清單，以及相同套件中的任何其他應用程式。

// Get all secondary tiles
var tiles = await SecondaryTile.FindAllForPackageAsync();

下列範例示範如何使用 TileUpdateManager.createTileUpdaterForSecondaryTile 方法，將通知傳送至識別碼為 「SecondaryTile.Dynamic」 的次要磚。 請注意，此範例同時提供寬版和方形版的通知，因為使用者可控制顯示何種形式的磚。

using NotificationsExtensions.TileContent;

// Define the notification context.
// Note: This sample contains an additional reference, NotificationsExtensions, which you can use in your apps
ITileWide310x150Text04 tileContent = TileContentFactory.CreateTileWide310x150Text04();
tileContent.TextBodyWrap.Text = "Sent to a secondary tile from NotificationsExtensions!";

// Provide a square version of the notification.
ITileSquare150x150Text04 squareContent = TileContentFactory.CreateTileSquare150x150Text04();
squareContent.TextBodyWrap.Text = "Sent to a secondary tile from NotificationExtensions!";
tileContent.Square150x150Content = squareContent;

// Send the notification to the secondary tile by creating a secondary tile updater
TileUpdateManager.CreateTileUpdaterForSecondaryTile(MainPage.dynamicTileId).Update(tileContent.CreateNotification());

下列範例示範如何使用 BadgeUpdateManager.createBadgeUpdaterForSecondaryTile 方法，將數值徽章通知傳送至識別碼為 「SecondaryTile.Dynamic」 的次要磚。

using NotificationsExtensions.BadgeContent;

// Define the badge content
BadgeNumericNotificationContent badgeContent = new BadgeNumericNotificationContent(6);

// Send the notification to the secondary tile
BadgeUpdateManager.CreateBadgeUpdaterForSecondaryTile(MainPage.dynamicTileId).Update(badgeContent.CreateNotification());

建構函式

SecondaryTile()	建立 SecondaryTile 物件。 呼叫端接著必須透過 物件設定任何必要屬性，再嘗試釘選、更新或刪除圖格。 在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件。
SecondaryTile(String)	建立具有特定識別碼的 SecondaryTile 物件。 這個形式的建構函式應該用來建立次要磚物件，以執行磚更新或刪除。 在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件。
SecondaryTile(String, String, String, String, TileOptions, Uri)	注意 此建構函式可能會在Windows 8.1之後變更或無法使用版本。 請改用 SecondaryTile.SecondaryTile (String、String、String、Uri、TileSize) 。 建立 SecondaryTile 物件做為中型磚。 在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件。
SecondaryTile(String, String, String, String, TileOptions, Uri, Uri)	注意 此建構函式可能會在Windows 8.1之後變更或無法使用版本。 請改用 SecondaryTile.SecondaryTile (String、String、String、Uri、TileSize) ，並透過 SecondaryTile.VisualElements 方法提供其他磚大小和選項。 建立 SecondaryTile 物件作為寬圖格。 在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件。 在 Windows Phone 8.1 上，所有磚包括次要磚，都會釘選為中型磚，之後使用者就可以調整大小。 這個建構函式提供調整為寬圖格大小的選項。
SecondaryTile(String, String, String, Uri, TileSize)	建立 SecondaryTile 物件，其中包含建立中型磚所需的所有必要屬性。 在傳統型應用程式中，在以顯示 UI 的方式使用這個類別的實例之前，您必須將物件與其擁有者的視窗控制碼產生關聯。 如需詳細資訊和程式碼範例，請參閱 顯示相依于 CoreWindow 的 WinRT UI 物件。

屬性

Arguments	取得或設定從次要磚傳遞至應用程式啟用時的應用程式定義資訊集。 當您建立磚時，需要這個屬性。
BackgroundColor	注意 背景色彩可能會在Windows 8.1之後變更或無法使用版本。 請改用 SecondaryTileVisualElements.BackgroundColor。 取得或設定磚的背景色彩。
DisplayName	取得或設定與並顯示在圖格上相關聯的名稱。 此名稱會顯示在 [開始] 的磚、磚的工具提示、應用程式清單中的小型磚標記法，以及某些主控台應用程式中。 當您建立磚時，需要這個屬性。 它相當於應用程式主要磚的資訊清單中所宣告的顯示名稱。 在 Windows Phone 8.1 上，顯示名稱只會顯示在寬次要磚上。
ForegroundText	注意 foregroundText 可能會在Windows 8.1之後變更或無法使用版本。 請改用 SecondaryTileVisualElements.ForegroundText。 取得或設定磚是否應該使用深色或淺色文字。
LockScreenBadgeLogo	取得或設定徽章標誌影像的位置，以代表鎖定畫面上的次要磚。 藉由提供此影像，您會宣告次要磚有資格在鎖定畫面上顯示徽章。 如果您也想要次要磚符合鎖定畫面詳細磚位置的資格，您也必須將 LockScreenDisplayBadgeAndTileText 屬性設定為 True。 注意 指出您的次要磚符合鎖定畫面顯示狀態的資格，並不保證其會有鎖定畫面。 只有使用者可以將應用程式新增至七個鎖定畫面位置的其中一個。 如需詳細資訊，請參閱 鎖定畫面概觀。
LockScreenDisplayBadgeAndTileText	取得或設定次要磚是否符合在鎖定畫面上顯示徽章和詳細磚的資格。 如果您將此屬性設定為 True，您也必須透過 LockScreenBadgeLogo 屬性提供徽章影像。 如果您不想使用詳細的磚功能，請透過 LockScreenBadgeLogo 屬性提供徽章影像，並將 LockScreenDisplayBadgeAndTileText 設定為 False。 注意 指出您的次要磚符合鎖定畫面顯示狀態的資格，並不保證其會有鎖定畫面。 只有使用者可以將應用程式新增至七個鎖定畫面位置的其中一個，以及選擇其中一個可以顯示詳細磚資訊。 如需詳細資訊，請參閱 鎖定畫面概觀。
Logo	注意 標誌可能會在Windows 8.1之後變更或無法使用。 請改用 SecondaryTileVisualElements.Square150x150Logo。 取得或設定中型磚中使用的標誌影像。 當您建立方形或寬圖格時，需要此屬性。
PhoneticName	取得或設定次要磚名稱的注音版本。 與字元型語言搭配使用，以進行 UI 排序。
RoamingEnabled	取得或設定值，這個值會決定當使用者在另一部電腦上使用其 Microsoft 帳戶安裝父應用程式時，是否要透過雲端重新取得次要磚。 請注意，從Windows 8.1開始，漫遊是預設行為。 這與預設 Windows 8 行為相反，其中漫遊是加入宣告。 此屬性在 Windows Phone 8.1 上一律會傳回 false。
ShortName	注意 Windows 8.1之後的版本可能會變更或無法使用 ShortName。 請改用 SecondaryTile.DisplayName。 取得或設定直接顯示在磚上的簡短名稱。 注意 自 Windows 8.1 起，會忽略此屬性，並在資訊清單中宣告的顯示名稱用於其位置。
SmallLogo	注意 smallLogo 可能會在Windows 8.1之後變更或無法使用。 請改用 SecondaryTileVisualElements.Square30x30Logo。 取得或設定小型標誌影像，用於搜尋結果、[所有程式] 清單，以及 UI 中的其他位置。 小型標誌不會與Windows Phone 8.1 次要磚搭配使用。
TileId	取得或設定唯一字串，以識別封裝內的圖格。 當您建立或刪除磚時，需要這個屬性。
TileOptions	注意 TileOptions 可能會在Windows 8.1之後變更或無法使用版本。 請改用 SecondaryTile.VisualElements。 取得或設定次要磚可用的選項。
VisualElements	取得 物件，您可以透過該物件取得或設定次要磚的背景色彩、前景文字、磚影像和應用程式名稱顯示選項。 自Windows 8.1起，此物件的屬性會取代下列 SecondaryTile 屬性： SecondaryTile.BackgroundColor SecondaryTile.ForegroundText SecondaryTile.Logo SecondaryTile.SmallLogo SecondaryTile.WideLogo SecondaryTile.TileOptions (CopyOnDeployment)
WideLogo	注意 WideLogo 可能會在Windows 8.1之後變更或無法使用。 請改用 SecondaryTileVisualElements.Wide310x150Logo。 取得或設定寬次要磚中使用的標誌影像。 當您建立寬的次要磚時，需要這個屬性，並在使用者調整磚大小時提供寬圖格的選項。

方法

Exists(String)	檢查呼叫端應用程式是否有特定的次要磚存在。
FindAllAsync()	擷取為呼叫端應用程式建立的次要磚清單。
FindAllAsync(String)	擷取與呼叫應用程式相同套件中為另一個應用程式建立的次要磚清單。
FindAllForPackageAsync()	擷取針對呼叫應用程式套件中所有應用程式建立的次要磚清單。 當應用程式啟動時，它應該一律透過這個方法列舉其次要磚，以防有未察覺的任何新增或刪除專案。 當透過 \[開始\] 畫面應用程式列刪除次要磚時，Windows 只會移除該次要磚。 應用程式本身負責發行由次要磚使用的任何資源。 透過雲端複製次要磚時，次要磚上的目前磚或徽章通知、排程通知、推播通知通道和統一資源識別項 (URI) 不會隨次要磚一起複製，而且必須重設。
RequestCreateAsync()	顯示 [釘選到開始] 飛出視窗，使用者可以透過該飛出視窗確認他們想要建立次要磚，進而建立磚。 此方法的多載可讓您指定飛出視窗的螢幕位置。 注意 最佳做法是在叫用建立磚要求的按鈕附近顯示 [釘選到開始] 飛出視窗。 因此，我們建議您使用 RequestCreateAsync (Point) 形式的此方法多載。 在 Windows Phone 8.1 上，次要磚會透過此呼叫建立，而不會向使用者顯示飛出視窗、提示他們進行確認，或讓他們選擇磚大小或標題文字。 請注意，使用 RequestCreateAsync 方法在 Windows Phone 8.x 應用程式中釘選次要磚時，應用程式會暫停，並將使用者帶至 [開始] 畫面。 電腦上的這個相同 API 呼叫不會暫停程式。 因此，請注意，在 App 暫停之前，不保證會在 RequestCreateAsync 之後呼叫的任何程式碼執行。 若要避免此潛在問題，您應該使用應用程式的 OnSuspended 事件來執行任何程式碼，例如更新釘選的磚，該磚應該在應用程式暫停之前執行。 若要查看此模式的範例，請下載並執行 暫止範例上的磚更新。
RequestCreateAsync(Point)	顯示指定位置上方的 [釘選到開始] 飛出視窗，使用者可以透過該位置確認他們想要建立次要磚，進而建立磚。 在 Windows Phone 8.1 上，次要磚會透過此呼叫建立，而不會向使用者顯示飛出視窗、提示他們進行確認，或讓他們選擇磚大小或標題文字。 請注意，使用RequestCreateAsync方法在 Windows Phone 8.x 應用程式中釘選次要磚時，應用程式會暫停，並將使用者帶至 [開始] 畫面。 電腦上的這個相同 API 呼叫不會暫停程式。 因此，請注意，在 App 暫停之前，不保證會在 RequestCreateAsync 之後呼叫的任何程式碼執行。 若要避免此潛在問題，您應該使用應用程式的 OnSuspended 事件來執行任何程式碼，例如更新釘選的磚，該磚應該在應用程式暫停之前執行。 若要查看此模式的範例，請下載並執行 暫止範例上的磚更新。
RequestCreateForSelectionAsync(Rect)	顯示指定區域上方的 [釘選到開始] 飛出視窗。 此飛出視窗由使用者用來確認他們想要建立次要磚，進而建立磚。 在 Windows Phone 8.1 上，次要磚會透過此呼叫建立，而不會向使用者顯示飛出視窗、提示他們確認，或讓他們選擇磚大小或標題文字。 請注意，使用RequestCreateAsync方法在 Windows Phone 8.x 應用程式中釘選次要磚時，應用程式會暫停，並將使用者帶到 [開始] 畫面。 電腦上的這個相同 API 呼叫不會暫停程式。 因此請注意，在 App 暫停之前，不保證在 RequestCreateAsync 之後呼叫的任何程式碼都會執行。 若要避免此潛在問題，您應該使用應用程式的 OnSuspended 事件來執行任何程式碼，例如更新釘選的磚，應該在應用程式暫停之前執行。 若要查看此模式的範例，請下載並執行 暫止範例上的磚更新。
RequestCreateForSelectionAsync(Rect, Placement)	顯示指定區域指定側邊的 [釘選到開始] 飛出視窗。 使用者會使用此飛出視窗來確認他們想要建立次要磚，進而建立磚。 在 Windows Phone 8.1 上，次要磚會透過此呼叫建立，而不會向使用者顯示飛出視窗、提示他們確認，或讓他們選擇磚大小或標題文字。 請注意，使用RequestCreateAsync方法在 Windows Phone 8.x 應用程式中釘選次要磚時，應用程式會暫停，並將使用者帶到 [開始] 畫面。 電腦上的這個相同 API 呼叫不會暫停程式。 因此請注意，在 App 暫停之前，不保證在 RequestCreateAsync 之後呼叫的任何程式碼都會執行。 若要避免此潛在問題，您應該使用應用程式的 OnSuspended 事件來執行任何程式碼，例如更新釘選的磚，應該在應用程式暫停之前執行。 若要查看此模式的範例，請下載並執行 暫止範例上的磚更新。
RequestDeleteAsync()	顯示 [開始] 飛出視窗的 [取消釘選 ]。 此飛出視窗可讓使用者確認移除次要磚。
RequestDeleteAsync(Point)	顯示在指定點 的 [從開始] 飛出視窗取消釘選 。 此飛出視窗可讓使用者確認移除次要磚。
RequestDeleteForSelectionAsync(Rect)	顯示在指定區域上方 的 [從開始] 飛出視窗取消釘選。 此飛出視窗可讓使用者確認移除次要磚。
RequestDeleteForSelectionAsync(Rect, Placement)	在指定區域的指定端顯示 [從開始] 飛出視窗取消釘選。 此飛出視窗可讓使用者確認移除次要磚。
UpdateAsync()	更新該磚釘選到 [開始] 畫面之後的次要磚。 在 Windows Phone 8.1 上，您的應用程式會暫停，並在釘選次要磚時，將使用者移至 \[開始\] 畫面。 因此請注意，在 App 暫停之前，不保證在 RequestCreateAsync 之後呼叫的任何程式碼都會執行。 若要避免此潛在問題，您應該使用應用程式的 OnSuspended 事件來執行任何程式碼，例如更新釘選的磚，應該在應用程式暫停之前執行。 若要查看此模式的範例，請下載並執行 暫止範例上的磚更新。

事件

VisualElementsRequested

呼叫 RequestCreateAsync時引發。 Windows Phone 8.1 上不會引發此事件。

另請參閱

• 次要磚指導方針
• 次要磚範例 (Windows 10)
• Mixed Reality模型範例