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 方法检索为调用应用和同一包中的任何其他应用创建的所有辅助磁贴的 ID 列表。

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

以下示例演示如何使用 TileUpdateManager.createTileUpdaterForSecondaryTile 方法向 ID 为“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 方法将数字锁屏提醒通知发送到 ID 为“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)	创建具有特定 ID 的 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后，BackgroundColor 可能会更改或不可用。 请改用 SecondaryTileVisualElements.BackgroundColor。 获取或设置磁贴的背景色。
DisplayName	获取或设置与磁贴关联并显示在磁贴上的名称。 此名称显示在“开始”磁贴中的“开始”磁贴上、磁贴的工具提示中、“应用”列表中的小磁贴表示形式旁边，以及某些控制面板应用程序中。 创建磁贴时需要此属性。 它等效于应用main磁贴的清单中声明的显示名称。 在 Windows Phone 8.1 上，显示名称仅显示在宽辅助磁贴上。
ForegroundText	注意 Windows 8.1后，ForegroundText 可能会更改或不可用。 请改用 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	注意 在Windows 8.1后，TileOptions 可能会更改或不可用于发布。 请改用 SecondaryTile.VisualElements。 获取或设置辅助磁贴可用的选项。
VisualElements	获取一个 对象，通过该对象可以获取或设置辅助磁贴的背景色、前景文本、磁贴图像和应用名称显示选项。 截至Windows 8.1，此对象的属性将替换以下 SecondaryTile 属性： SecondaryTile.BackgroundColor SecondaryTile.ForegroundText SecondaryTile.Logo SecondaryTile.SmallLogo SecondaryTile.WideLogo SecondaryTile.TileOptions (CopyOnDeployment)
WideLogo	注意 Windows 8.1后，WideLogo 可能会更改或不可用。 请改用 SecondaryTileVisualElements.Wide310x150Logo。 获取或设置加宽辅助磁贴中使用的徽标图像。 创建加宽辅助磁贴时，需要此属性，并在用户调整磁贴大小时为用户提供加宽磁贴的选项。

方法

Exists(String)	检查调用应用是否存在特定的辅助磁贴。
FindAllAsync()	检索为调用应用创建的辅助磁贴列表。
FindAllAsync(String)	检索在调用应用所在的同一包中为另一个应用创建的辅助磁贴列表。
FindAllForPackageAsync()	检索为调用应用的包中的所有应用创建的辅助磁贴列表。 当应用启动时，它应始终通过此方法枚举其辅助磁贴，以防存在它不知道的任何添加或删除操作。 当通过“开始”屏幕应用栏删除辅助磁贴时，Windows 只是删除该磁贴。 应用本身负责释放由辅助磁贴使用的任何资源。 通过云复制辅助磁贴时，辅助磁贴上的当前磁贴或锁屏提醒通知、计划通知、推送通知通道和用于定期通知的统一资源标识符 () URI 不会与辅助磁贴一起复制，必须重置。
RequestCreateAsync()	显示 “固定到开始” 浮出控件，用户可以通过该浮出控件确认要创建辅助磁贴，从而创建磁贴。 此方法的重载使你可以指定浮出控件的屏幕位置。 注意 最佳做法是在调用创建磁贴的请求的按钮附近显示 “固定到开始” 浮出控件。 因此，建议使用此方法重载的 RequestCreateAsync (点) 形式。 在 Windows Phone 8.1 上，通过此调用创建辅助磁贴，不向用户显示浮出控件、提示用户进行确认或允许用户选择磁贴大小或标题文本。 请注意，使用 RequestCreateAsync 方法将辅助磁贴固定到 Windows Phone 8.x 应用中时，应用会暂停，用户将被带到“开始”屏幕。 电脑上的同一 API 调用不会暂停程序。 因此，请注意，在 RequestCreateAsync 之后调用的任何代码都不能保证在应用暂停之前运行。 若要避免此潜在问题，应使用应用的 OnSuspended 事件来运行应在应用挂起之前运行的任何代码，例如更新固定磁贴。 若要查看此模式的示例，请下载并运行 暂停时磁贴更新示例。
RequestCreateAsync(Point)	在指定位置上方显示 “固定到开始” 浮出控件，用户可以通过该浮出控件确认要创建辅助磁贴，从而创建磁贴。 在 Windows Phone 8.1 上，通过此调用创建辅助磁贴，不向用户显示浮出控件、提示用户进行确认或允许用户选择磁贴大小或标题文本。 请注意，使用 RequestCreateAsync 方法将辅助磁贴固定到 Windows Phone 8.x 应用中时，应用将暂停，用户将被带到“开始”屏幕。 电脑上的同一 API 调用不会暂停程序。 因此，请注意， 在 RequestCreateAsync 之后调用的任何代码都不能保证在应用暂停之前运行。 若要避免此潜在问题，应使用应用的 OnSuspended 事件来运行应在应用挂起之前运行的任何代码，例如更新固定磁贴。 若要查看此模式的示例，请下载并运行 暂停时磁贴更新示例。
RequestCreateForSelectionAsync(Rect)	在指定区域上方显示 “固定到开始” 浮出控件。 用户使用此浮出控件来确认他们想要创建辅助磁贴，而辅助磁贴又会创建磁贴。 在 Windows Phone 8.1 上，辅助磁贴是通过此调用创建的，而不会向用户显示浮出控件、提示用户进行确认或允许他们选择磁贴大小或标题文本。 请注意，使用 RequestCreateAsync 方法在 Windows Phone 8.x 应用中固定辅助磁贴时，应用将暂停，用户将转到“开始”屏幕。 电脑上的同一 API 调用不会暂停程序。 因此，请注意，在 RequestCreateAsync 之后调用的任何代码都不能保证在应用暂停之前运行。 若要避免此潜在问题，应使用应用的 OnSuspended 事件来运行应在应用暂停之前运行的任何代码，例如更新固定磁贴。 若要查看此模式的示例，请下载并运行 暂停时磁贴更新示例。
RequestCreateForSelectionAsync(Rect, Placement)	在指定区域的指定侧显示 “固定到开始”菜单 浮出控件。 用户使用此浮出控件来确认他们想要创建辅助磁贴，而辅助磁贴又会创建该磁贴。 在 Windows Phone 8.1 上，辅助磁贴是通过此调用创建的，而不会向用户显示浮出控件、提示用户进行确认或允许他们选择磁贴大小或标题文本。 请注意，使用 RequestCreateAsync 方法在 Windows Phone 8.x 应用中固定辅助磁贴时，应用将暂停，用户将转到“开始”屏幕。 电脑上的同一 API 调用不会暂停程序。 因此，请注意，在 RequestCreateAsync 之后调用的任何代码都不能保证在应用暂停之前运行。 若要避免此潜在问题，应使用应用的 OnSuspended 事件来运行应在应用暂停之前运行的任何代码，例如更新固定磁贴。 若要查看此模式的示例，请下载并运行 暂停时磁贴更新示例。
RequestDeleteAsync()	显示“ 从”开始“屏幕取消固定 浮出控件。 此浮出控件允许用户确认删除辅助磁贴。
RequestDeleteAsync(Point)	在指定点显示 取消固定“从”开始“ 浮出控件。 此浮出控件允许用户确认删除辅助磁贴。
RequestDeleteForSelectionAsync(Rect)	显示指定区域上方 的“从开始”屏幕取消固定 浮出控件。 此浮出控件允许用户确认删除辅助磁贴。
RequestDeleteForSelectionAsync(Rect, Placement)	在指定区域的指定侧显示 “从”开始“屏幕取消固定 浮出控件。 此浮出控件允许用户确认删除辅助磁贴。
UpdateAsync()	在将辅助磁贴固定到“开始”屏幕后，汇报辅助磁贴。 在 Windows Phone 8.1 上，你的应用将暂停，并且当用户固定辅助磁贴时，用户将转到“开始”屏幕。 因此，请注意，在 RequestCreateAsync 之后调用的任何代码都不能保证在应用暂停之前运行。 若要避免此潜在问题，应使用应用的 OnSuspended 事件来运行应在应用暂停之前运行的任何代码，例如更新固定磁贴。 若要查看此模式的示例，请下载并运行 暂停时磁贴更新示例。

事件

VisualElementsRequested

调用 RequestCreateAsync 时触发。 Windows Phone 8.1 上不会引发此事件。

另请参阅

• 辅助磁贴指南
• 辅助磁贴示例 (Windows 10)
• 混合现实模型示例