Xamarin 中的 watchOS 复杂组件

watchOS 允许开发人员为手表界面编写自定义复杂组件

本页介绍了可用的各种类型的复杂组件，以及如何向 watchOS 3 应用添加复杂组件。

请注意，每个 watchOS 应用程序只能有一个复杂组件。

首先阅读 Apple 的文档，以确定你的应用是否适合复杂组件。 有 5 种 CLKComplicationFamily 显示类型可供选择：

应用可以只实现其中一种样式，也可以实现全部五种，具体取决于要显示的数据。 你还可以支持按时间顺序查看，在用户旋转数字皇冠时提供过去和/或将来时间的值。

添加复杂组件

配置

复杂组件可以在创建过程中添加到手表应用中，也可以手动添加到现有解决方案中。

添加新项目...

“添加新项目...”向导包括一个复选框，用于自动创建一个复杂组件控制器类并配置 Info.plist 文件：

现有项目

若要向现有项目添加复杂组件，请执行以下操作：

1. 创建一个新的 ComplicationController.cs 类文件并实现 CLKComplicationDataSource。
2. 配置应用的 Info.plist 以公开此复杂组件，并确定哪些复杂组件系列受支持。

下面更详细地介绍了这些步骤。

CLKComplicationDataSource 类

下面的 C# 模板包括了实现 CLKComplicationDataSource 所需的最少方法。

[Register ("ComplicationController")]
public class ComplicationController : CLKComplicationDataSource
{
  public ComplicationController ()
  {
  }
  public override void GetPlaceholderTemplate (CLKComplication complication, Action<CLKComplicationTemplate> handler)
  {
  }
  public override void GetCurrentTimelineEntry (CLKComplication complication, Action<CLKComplicationTimelineEntry> handler)
  {
  }
  public override void GetSupportedTimeTravelDirections (CLKComplication complication, Action<CLKComplicationTimeTravelDirections> handler)
  {
  }
}

按照编写复杂组件说明向此类中添加代码。

Info.plist

手表扩展的 Info.plist 文件应指定 CLKComplicationDataSource 的名称以及你要支持的复杂组件系列：

数据源类条目列表将显示包含你的复杂组件逻辑的 CLKComplicationDataSource 子类派生自的类名。

CLKComplicationDataSource

所有复杂组件功能都是在单个类中实现的，并重写来自 CLKComplicationDataSource 抽象类（此类实现 ICLKComplicationDataSource 接口）的方法。

必需的方法

必须实现以下方法才能运行复杂组件：

• GetPlaceholderTemplate - 返回在配置期间或者当应用无法提供值时使用的静态显示。
• GetCurrentTimelineEntry - 计算当复杂组件正在运行时的正确显示。
• GetSupportedTimeTravelDirections - 返回来自 CLKComplicationTimeTravelDirections 的选项，例如 None、Forward、Backward 或 Forward | Backward。

隐私

显示个人数据的复杂组件

• GetPrivacyBehavior - CLKComplicationPrivacyBehavior.ShowOnLockScreen 或 HideOnLockScreen

如果此方法返回 HideOnLockScreen，则当手表被锁定时，复杂组件将显示图标或应用程序名称（而不显示任何数据）。

更新

• GetNextRequestedUpdateDate - 返回操作系统下次查询应用以获取更新的复杂组件显示数据的时间。

还可以从 iOS 应用进行强制更新。

支持按时间顺序查看

支持按时间顺序查看是可选的，由 GetSupportedTimeTravelDirections 方法控制。 如果它返回 Forward、Backward 或 Forward | Backward，则你必须实现以下方法：

• GetTimelineStartDate
• GetTimelineEndDate
• GetTimelineEntriesBeforeDate
• GetTimelineEntriesAfterDate

编写复杂组件

复杂组件的范围包括简单的数据显示、复杂的图像，以及支持按时间顺序查看的数据呈现。 下面的代码展示了如何构建简单的单模板复杂组件。

代码示例

此示例仅支持 UtilitarianLarge 模板，因此只能在支持该复杂组件类型的特定手表界面上选择。 在手表上选择复杂组件时，它将显示“MY COMPLICATION”，在运行时，它将显示文本 MINUTE 小时（时间的一部分）。

[Register ("ComplicationController")]
public class ComplicationController : CLKComplicationDataSource
{
    public ComplicationController ()
    {
    }
    public ComplicationController (IntPtr p) : base (p)
    {
    }
    public override void GetCurrentTimelineEntry (CLKComplication complication, Action<CLKComplicationTimelineEntry> handler)
    {
        CLKComplicationTimelineEntry entry = null;
    var complicationDisplay = "MINUTE " + DateTime.Now.Minute.ToString(); // text to display on watch face
        if (complication.Family == CLKComplicationFamily.UtilitarianLarge)
        {
            var textTemplate = new CLKComplicationTemplateUtilitarianLargeFlat();
            textTemplate.TextProvider = CLKSimpleTextProvider.FromText(complicationDisplay); // dynamic display
            entry = CLKComplicationTimelineEntry.Create(NSDate.Now, textTemplate);
        } else {
            Console.WriteLine("Complication family timeline not supported (" + complication.Family + ")");
        }
        handler (entry);
    }
    public override void GetPlaceholderTemplate (CLKComplication complication, Action<CLKComplicationTemplate> handler)
    {
        CLKComplicationTemplate template = null;
        if (complication.Family == CLKComplicationFamily.UtilitarianLarge) {
            var textTemplate = new CLKComplicationTemplateUtilitarianLargeFlat ();
            textTemplate.TextProvider = CLKSimpleTextProvider.FromText ("MY COMPLICATION"); // static display
            template = textTemplate;
        } else {
            Console.WriteLine ("Complication family placeholder not not supported (" + complication.Family + ")");
        }
        handler (template);
    }
    public override void GetSupportedTimeTravelDirections (CLKComplication complication, Action<CLKComplicationTimeTravelDirections> handler)
    {
        handler (CLKComplicationTimeTravelDirections.None);
    }
}

复杂组件模板

每种复杂组件样式都有许多不同的模板可用。 “环”模板允许围绕复杂组件显示进度样式的环，这可用于以图形方式显示进度或一些其他值。

Apple 的 CLKComplicationTemplate 文档

小圆形

这些模板类名都以 CLKComplicationTemplateCircularSmall 作为前缀：

• RingImage - 显示单个图像，并且周围环绕着一个进度环。
• RingText - 显示单行文本，并且周围环绕着一个进度环。
• SimpleImage - 仅显示单个小图像。
• SimpleText - 仅显示一小段文本。
• StackImage - 显示一个图像和一行文本，一个高于另一个
• StackText - 显示两行文本。

小型模块

这些模板类名都以 CLKComplicationTemplateModularSmall 作为前缀：

• ColumnsText - 显示一个包含文本值的小型网格（2 行 2 列）。
• RingImage - 显示单个图像，并且周围环绕着一个进度环。
• RingText - 显示单行文本，并且周围环绕着一个进度环。
• SimpleImage - 仅显示单个小图像。
• SimpleText - 仅显示一小段文本。
• StackImage - 显示一个图像和一行文本，一个高于另一个
• StackText - 显示两行文本。

大型模块

这些模板类名都以 CLKComplicationTemplateModularLarge 作为前缀：

• Columns - 显示一个包含 3 行 2 列的网格，还可以选择在每行的左侧包括一个图像。
• StandardBody - 显示一个粗体标题字符串，以及两行纯文本。 标题还可以选择在左侧显示一个图像。
• Table - 显示一个粗体标题字符串，其下方有一个 2x2 文本网格。 标题还可以选择在左侧显示一个图像。
• TallBody - 显示一个粗体标题字符串，其下方有较大字号的单行文本。

小型实用

这些模板类名都以 CLKComplicationTemplateUtilitarianSmall 作为前缀：

• Flat - 在单个行上显示一个图像和一些文本（文本应当很短）。
• RingImage - 显示单个图像，并且周围环绕着一个进度环。
• RingText - 显示单行文本，并且周围环绕着一个进度环。
• Square - 显示一个正方形图像（38mm 和 42mm Apple Watch 分别为 40px 和 44px 的正方形）。

大型实用

此复杂组件样式只有一个模板：CLKComplicationTemplateUtilitarianLargeFlat 它显示单个图像和一些文本，全部显示在单个行上。

相关链接

• Apple 的文档
• WWDC 视频