Xamarin 中的 watchOS 复杂组件
watchOS 允许开发人员为手表界面编写自定义复杂组件
本页介绍了可用的各种类型的复杂组件,以及如何向 watchOS 3 应用添加复杂组件。
请注意,每个 watchOS 应用程序只能有一个复杂组件。
首先阅读 Apple 的文档,以确定你的应用是否适合复杂组件。 有 5 种 CLKComplicationFamily
显示类型可供选择:
应用可以只实现其中一种样式,也可以实现全部五种,具体取决于要显示的数据。 你还可以支持按时间顺序查看,在用户旋转数字皇冠时提供过去和/或将来时间的值。
复杂组件可以在创建过程中添加到手表应用中,也可以手动添加到现有解决方案中。
“添加新项目...”向导包括一个复选框,用于自动创建一个复杂组件控制器类并配置 Info.plist 文件:
若要向现有项目添加复杂组件,请执行以下操作:
- 创建一个新的 ComplicationController.cs 类文件并实现
CLKComplicationDataSource
。 - 配置应用的 Info.plist 以公开此复杂组件,并确定哪些复杂组件系列受支持。
下面更详细地介绍了这些步骤。
下面的 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 文件应指定 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
它显示单个图像和一些文本,全部显示在单个行上。