为 Apple Watch 创建复杂功能

为 Apple Watch 创建复杂功能

当您在 Watch app 中添加复杂功能时，人们可以直接从其表盘访问全部最新信息。我们将向您展示如何从头开始创建和构建复杂功能，并向您介绍多种复杂功能。了解如何构建时间表，使用族和模板，以及探索最佳实践，以打造透彻的复杂功能体验。

资源
相关视频

WWDC20
下载

（你好 WWDC2020）
你好欢迎来到 WWDC
（为 Apple Watch 创建复杂功能）大家好我是 Michael Kent 我是一名 ClockKit 工程师在本视频中我们将了解 Apple Watch 的复杂功能以及如何将它们添加至你的 app 复杂功能是把你的内容展现在用户眼前的绝佳方式只需快速一瞥钟面用户就能看见它们在 watchOS 7 上我们让创造优秀的复杂功能体验变得比以往更容易这就是为什么复杂功能在 Watch 上与 app 体验一样重要的原因它们是将你的内容展现在用户眼前的最容易之法要如何将它们添加至你的 app？我们会来讨论时间线即复杂功能的支撑结构你需要进行的所有琐碎工作你要如何将数据置入复杂功能你要如何利用新的 watchOS 7 性能让你的 app 提供多于一种的复杂功能然后我们还会查看一个示例我们先从时间线开始说起吧时间线在复杂功能里扮演着主要角色它们代表随时间推移的复杂功能数据因为时间线提供了所有复杂功能的数据 ClockKit 可以向你的 app 请求一次所有的必要信息来将你的复杂功能驱动至你所指定的一个日期
当然如果你的 app 获得了新数据而你需要给我们更多条目你可以请求 ClockKit 延长你的时间线或彻底使之失效我和一些团队成员正在努力开发一款 app 来追踪夏威夷周围的鲸鱼出没在这个 app 里你可以看到毛伊岛周围在几个观察站看到的鲸鱼出没来看看可能来自这个 app 的时间线示例吧在这里我有一个观鲸之旅的日程表这是一天之内不同地点的三项观鲸活动现在这个则是该日程表以时间线的形式可能显示在 ClockKit 里的样子你会注意到几处不同首先每个活动都只和一个时间点而非一个时间范围相关联这是因为你的复杂功能在到达下一个活动的日期前只会显示一个条目第二点你会看到每个活动的关联时间都比实际开始时间还要早这是为了事先通知用户以便如果他们感兴趣的话能来得及搭乘观光船不是所有数据都会这样运作比方说气温预测就应该要在其真正的预测时间记录条目最上方的是我想在当前时间要这个复杂功能显示的数据随着一天的推进你可以看到信息跟着时间而更新直到今天再没有任何观光活动为止
现在就来了解一下你究竟要如何指定你的复杂功能显示些什么
复杂功能家族即是将它们归类进不同视觉分组的方法图形家族早在 watchOS 5 就被推出了不过当时没有 Graphic Extra Large 这是 watchOS 7 的新功能这些家族允许更多以视觉为主的数据呈现不同的表盘使用不同的复杂功能家族以下是一些示例
图文表盘使用 Graphic Corner 和 Graphic Bezel 以及 Graphic Circular 它也和 Graphic Rectangular 一起出现在图文模块表盘上
这就是 Graphic Extra Large 现在超大表盘支持它模块表盘上有 Modular Small 和 Modular Large 动态表盘上则有 Utilitarian Small Flat 实用表盘上有 Utilitarian Small 和 Large 最后如果你的复杂功能不支持 Graphic Extra Large 家族的话超大表盘则会使用 Extra Large 这个家族会一直用在 Series 3 手表的超大表盘上在理想情况下你应该让自己的复杂功能尽可能地支持更多复杂功能家族这样的话你的所有用户都能够在任何自己喜爱的表盘上使用你的复杂功能复杂功能模板代表家族内的不同视觉布局这是一个示例上面只显示了某些不同家族的一些复杂功能模板虽然它们和特定家族相关联但是每个模板实则继承自一个通用基类即 CLKComplicationTemplate
你可以从这么多选择里进行挑选以便最好地显示你的数据你可以在开发者网站上的说明文档里找到更多可用模板现在我们来看一下这个提供时间线的代码示例我要说明的第一个类型是 CLKComplicationTimelineEntry 你通过给我们一个这些的列表来填充你复杂功能的时间线每一个都代表了你的复杂功能在特定时间点里应该是什么样子它只有两个属性第一是日期这是该条目应该变得可见的日子第二是 complicationTemplate 这是包含你要为此条目显示的数据的模板回到我们之前的时间线示例在早上 6 时我们会有一个填充了日期的时间线条目即早上 6 时以及一个代表着马亚拉伊港观光活动的 complicationTemplate 在上午 9 时日期和模板就会改变这在余下的一天里都会如此你与 ClockKit 的主要互动是通过一个你创建的对象进行的该对象符合 CLKComplicationDataSource 在这个协议里唯一需要的方法是 getCurrentTimelineEntry for complication withHandler
要实施这个方法你只需为给定的复杂功能调用当前时间线条目的处理程序我们稍后再讲这个复杂功能是什么
对于某些复杂功能来说一个当前条目就已足够比如说棒球比赛的当前分数或者是 Apple 的当前股价但是如果你的复杂功能可以提供包括未来条目的时间线你还将需要实施这两种方法 getTimelineEndDate for complication withHandler 它可以指定你想为多远的未来提供条目以及 complication after date limit withHandler 的 getTimelineEntries 这有点拗口但你只需要做一件事那就是尽可能地为你既定日期后的时间提供条目在限制内越多适合数据的条目越好 “日期” 代表着我们已经拥有的最后一个时间线条目 “限制” 则确保我们一次只能获取我们所需的条目数量如果你提供更多的话我们将删除所有超过限制的条目那么如果你的 app 获得了新数据而你需要重新加载时间线呢？对此我们有两种选择第一种如果你的数据完全改变而你提供过的所有条目都无效了你可以在 CLKComplicationServer 的共享实例上为复杂功能调用 reloadTimeline
比方说一场始料未及的暴风雨席卷了毛伊岛我们所有的赏鲸活动将会被取消我们需要使我们的整个时间线都失效来反映这点
但是如果你之前所提供的条目依然有效而你只是想让我们知道你可以提供更多条目那你就可以为复杂功能调用 extendTimeline
ClockKit 只会为用户表盘上的当前的复杂功能跟踪时间线我们通过 activeComplications 属性让你知道这点
你永远都不会直接创建 CLKComplication 对象你总是从这里得到它们或者传入你所实施的数据源方法现在就来聊聊创建这些复杂功能模板需要什么吧
复杂功能有一些限制手表屏幕已经够小了复杂功能比它还小你也许想要在不同的模板或者复杂功能家族里显示相同的字符串而它们全都有着大不相同的布局限制为交付最好的体验我们有个叫做数据提供者的概念它们允许你在许多不同的地点和情境里表达同一信息信息由 ClockKit 为你进行格式化因为我们会替你处理复杂功能的具体布局详情而我们需要足够的信息才能灵活行动我来向你展示我说的情况吧我们会先从一些文本开始手表的核心是时间所以显示日期是你经常要做的一件事这个写长日期的方法不错但是在绝大多数的复杂功能情境里你最终会写出这样的东西这样的文本不是很清楚我们要怎样让它变得更好呢？你可以使用一个叫做 CLKDateTextProvider 的数据提供器你声明你想要的内容在这个场景里是 “9 月 23 日星期三” 然后我们会尽己所能来显示它如果空间不足的话我们会采用较短的版本
最终可能就会删去比较无用的信息比如星期几如有必要可能会一直删到只剩下该月的天数
以下是它在代码里的样子你给它提供一个日期创建一个 CLKDateTextProvider 以及你偏好的最长日历单位如果你需要回答问题比如说 “这个日期距离我当前时间还有多久？” 或者“这个日期距离某个日期还有多久？” 你可以使用 CLKRelativeDateTextProvider 在第一道问题的场景里一个相对日期文本提供器会自动更新文本反映出当前的时间这甚至可以精确到秒而你无需做任何事你可以将它用于不同的格式显示像这样的字符串从现在到日落的时间或者你的面团还要多久才能发酵完成
在后一个例子中你可以提供一个结束日期你可以指定“计时器”风格并提供你想要显示的单位这些是其他的文本提供器比如时间文本提供器它和日期文本提供器的作用非常相似但是它显示的是时间而非天数时间间隔文本提供器则是用来显示一个范围内的时间比如上午 7 时 30 分至上午 9 时最后的简单文本提供器则会显示你想要的任何字符串你也可以给它提供较短的版本好让该字符串在受限的空间里自行选用图像提供器和文本提供器很相似它们所含的数据都能用在几种不同的情境里
最大的分别是这些情境比较专注于表盘的颜色许多表盘允许用户自定义这个属性而复杂功能必须与它一致匹配
某些表盘将单一颜色应用到整个复杂功能的图像上而其他表盘可能允许由背景和前景所组成的多色图像你可以在底部这里看到一些例子比如计时器、日出和秒表
CLKImageProvider 是实现这一切的对象图形复杂功能家族允许显示全彩图像因此它们的模板要求的是 CLKFullColorImageProviders 可是在某些情境里这些图形复杂功能是被着色的如果你只提供一个全彩图像我们会帮你降低饱和度以应用这种着色如果你想否决这种行为 CLKFullColorImageProvider 会允许你设置一个 CLKImageProvider 以作为后备你可以在这里看到为相同的图像提供 CLKImageProvider 之后这个复杂功能变亮了它现在拥有了和左上角其他复杂功能一样的白色欲了解更多关于适应复杂功能着色的信息请查看这个 2019 年的精彩讲座（探索图形复杂功能的着色）量表提供器是用来概括必要数据以显示图形型量表或进度的方法它们能适应不同的复杂功能布局就像这里所看到的角落和中心一样
你可以自定义量表的颜色或渐变度以及填充系数你只需要花很少的功夫即可
如果你想要一个能够实时更新其填充系数的量表你可以使用 CLKTimeIntervalGaugeProvider 它能让你指定开始和结束日期然后它会自动更新以显示当前时间的进度
你现在可以在复杂功能里使用 SwiftUI 了这是 watchOS 7 的新功能所有使用 CLKFullColor ImageProviders 的复杂功能模板都拥有 SwiftUI 视图选项
这样你就可以轻易地重用 app 里其他部分的部件并且你的复杂功能更容易脱颖而出你也可以更容易地创建独特的复杂功能以吸引你的用户（在 SwiftUI 里构建复杂功能 WWDC20）若想进一步了解在复杂功能里使用 SwiftUI 的详情我们有一个很好的视频详细地说明了这些
如果说你的 app 充满了对用户有用且相关的信息而你想让他们快速方便地访问它们？这也是 watchOS 7 的新性能你现在可以从单一 app 里提供多种复杂功能了这是将你的数据呈现在用户面前的好方法用户只需在手腕上快速一览即可看到你甚至可以将你的复杂功能放到表盘上并共享它
多种复杂功能的支持会在你所实施的 CLKComplicationDataSource 中被声明这里有两个相关的方法第一 getComplicationDescriptors withHandler 它会说明你的 app 所支持的复杂功能当前列表
第二个是 handleSharedComplicationDescriptors 当某个包含了你部分复杂功能的表盘与这个手表共享时这个方法就会被调用以提醒你 ClockKit 会开始帮它们请求时间线条目 CLKComplicationDescriptor 是你定义复杂功能的方法它包含了一个你的 app 里独特的标识符
一个在编辑表盘时显示的 displayName 一个被这个复杂功能所支持的复杂功能家族列表以及两个可选的互斥属性它们允许你包含以后会用到的自定义数据即 userInfo dictionary 或者 userActivity
我们的观鲸 app 支持着几种不同的复杂功能有些是显示每个地点看到鲸鱼的次数一个是快速记录新看到的鲸鱼的复杂功能还有一个是显示全季数据的复杂功能来看看它们是怎样运作的吧
在 getComplicationDescriptors withHandler 方法里你会创建一个 ComplicationDescriptors 的数组并用它来调用处理程序在这里我们会在数据模型里遍历每一个观察站为它们每一个创建 ComplicationDescriptor
这些将会用来显示每个地点的观鲸信息
接下来我们要给复杂功能添加一个描述符以便记录一次看到鲸鱼的事件最后再加一个描述符以便浏览全季数据你会注意到这最后一个复杂功能只支持 graphicRectangular 家族而其他复杂功能则支持全部家族由于季节数据复杂功能需要显示很多信息 graphicRectangular 的巨大画布是唯一适用于这个复杂功能的选择如果你需要使这个列表失效你可以在 CLKComplicationServer 上调用 reloadComplicationDescriptors 然后我们还会再调用这个方法在我们的观鲸示例中也许我们只显示了用户所喜爱观鲸站的复杂功能如果他们更新那些列表那我们也应该要更新复杂功能
如果你更新了列表并移除了对某个用户在当前表盘上有的复杂功能的支持我们会继续请求你提供该复杂功能的时间线条目在这种情况下请尽你所能确保自己可以继续提供有用的信息
注意一下这个方法与 CLKComplicationServer 的 reload TimelineForComplication 方法不同前者会重新加载你的 app 所提供的复杂功能列表后者则会重新加载特定的复杂功能时间线
和往常一样当用户轻点你的复杂功能我们就会启动你的 app 如果被轻点的复杂功能的标识符是用 userActivity 创建的那么它就会在启动时被用上无论是哪种情况我们都会把一些条目传进 userInfo dictionary 比如说该复杂功能当前可见的时间线条目日期以及复杂功能的标识符
当然这个 dictionary 也会包含被 complicationDescriptor 所定义的开发者指定条目
我们讨论过如何描述你所支持的复杂功能但是你又要如何知道 Clockit 在为哪个复杂功能请求时间线条目？
这里是我们先前看过的几个方法 getCurrentTimelineEntry 以及 getTimelineEndDate 每一个都需要 CLKComplication 类型的复杂功能参数
这看起来很像 complicationDescriptor 但是当 complicationDescriptor 负责定义复杂功能支持什么这个对象则代表一个复杂功能在用户表盘上的具体实际实例所以它不会有一个所支持家族的列表反而它会拥有一个属性该属性包含现实复杂功能实例的家族当然你使用 userInfo dictionary 或 userActivity 给描述符提供的信息也会被包含在这里我们有一个叫做默认复杂功能标识符的东西你应不应该用这个东西来识别你的一个复杂功能呢？当然可以但这不是它的主要用途如果你拥有一个 watchOS 7 之前的复杂功能而用户在他们的表盘上有它又或者用户与你的复杂功能共享了表盘但是选择移除关联数据那么你就会被问起有以下标识符的复杂功能 CLKDefaultComplicationIdentifier 即便你并没有在你的复杂功能描述符列表上明确支持它这点很重要你应该要支持这个复杂功能否则你的用户肯定会好奇为什么他们会在表盘上看到一个来自你的 app 并且已经有故障的复杂功能那么你该怎么办呢？
你可以显示与你的复杂功能在 watchOS 7 之前所显示的同样的信息又或者你可以选择显示来自你 app 最受欢迎或最相关的信息又或者你可以只显示 app 的图标这样的话至少用户会知道那个复杂功能是什么并大致了解如果轻点它的话会发生什么现在来看看我们观鲸 app 的更多细节吧我们之前就看过这个方法它会为既定的复杂功能创建当前条目
以下是我们还未看过的另一个方法 getLocalizableSampleTemplate for complication withHandler 也是 CLKComplicationDataSource 协议的一部分
它正在请求的模板会用在表盘编辑里的复杂功能选择过程上以及用在已配对 iPhone 的 Apple Watch app 上这个模板应该包含示例数据因为我们只会为每个复杂功能发出一次请求并缓存结果
我们已经看到 createTimelineEntry 方法被用过几次了它挺简单的它会先创建一个模板再创建该模板的一个时间线条目和传入该条目的日期
让我们来更深入了解 createTemplate 方法吧我们先来抓取一些我们需要在创建模板时重用的数据我们从这个复杂功能里提取观察站信息记住我们用它创建了描述符然后我们再创建可以用在不同情况下的 FullColorImageProvider 接着我们创建用来记录观鲸的 SimpleTextProvider
最后我们再创建一个可以为给定家族返回默认模板的闭包这是面对突发情况时我们可以备用的闭包比如说当我们收到默认复杂功能标识符模板的请求时
要确定创建哪个模板我们先来打开家族和标识符针对 Graphic Rectangular 中的 SeasonData 复杂功能我们会创建一个 GraphicRectangularFullView 模板它有一个 SwiftUI 视图能够漂亮地显示一张数据直观图表
至于 graphicCircular 中的 “记录看到鲸鱼”的复杂功能我们则会使用之前创建的 ImageProvider 和 TextProvider 来创建一个 GraphicCircularStackImage 模板至于其他任何种类的 graphicCircular 复杂功能的话我们会展示另一个 SwiftUI 视图它会显示某个地点的鲸鱼出没信息 GraphicExtraLarge 和 GraphicCorner 也很相似它们各自都会返回一个复杂功能模板该模板会包含来自站点数据的相应 text 和 imageProviders 其实还有很多为每个所支持的复杂功能正确提供模板的其他例子但是它们或多或少都很相似所以我就不一一说明了当然如果我们被问到一个复杂功能而我们认为我们做不了什么比如说默认复杂功能标识符那我们就返回一个默认模板即可以下是某些那种复杂功能运行时的样子我们有两种不同的 Graphic Rectangular 复杂功能两种 Graphic Circular 复杂功能我们使用 SwiftUI 来绘制这些美丽图表而这些复杂功能在全彩和着色情境下好看极了在 watchOS 7 里你拥有很多将数据带到用户面前的表盘上的机会所以制作复杂功能吧让数据以时间线的形式显示让你的复杂功能切合最新情况使用 SwiftUI 创建优秀且自定义的复杂功能内容最后被问到的时候你要确保可以支持默认复杂功能标识符如果你还想要了解更多关于构建优秀复杂功能的信息你可以查看这些视频谢谢你的收看

4:54 - CLKComplicationDataSource - Required Methods

// CLKComplicationDataSource - Required
class ComplicationController: NSObject, CLKComplicationDataSource {

    func getCurrentTimelineEntry(
        for complication: CLKComplication, 
        withHandler handler: @escaping (CLKComplicationTimelineEntry?) -> Void)     
    {
        // Call the handler with the current timeline entry
        handler(createTimelineEntry(forComplication: complication, date: Date()))
    }
}

5:16 - CLKComplicationDataSource - Timeline Support

// CLKComplicationDataSource - Timeline Support
extension ComplicationController {

    func getTimelineEndDate(
        for complication: CLKComplication, 
        withHandler handler: @escaping (Date?) -> Void) 
    {
        handler(timeline(for: complication)?.endDate)
    }

    func getTimelineEntries(
        for complication: CLKComplication, 
        after date: Date, 
        limit: Int, 
        withHandler handler: @escaping ([CLKComplicationTimelineEntry]?) -> Void) 
    {
       handler(timeline(for: complication)?.entries(after: date, limit: limit))
    }
}

8:11 - CLKDateTextProvider initialization

let longDate: Date = DateComponents(year: 2020, month: 9, day: 23).date ?? Date()
let units: NSCalendar.Unit = [.weekday, .month, .day]
let textProvider = CLKDateTextProvider(date: longDate, units: units)

8:49 - CLKRelativeDateTextProvider initialization

let timerStart: Date = …
let units: NSCalendar.Unit = [.hour, .minute, .second]
let textProvider = CLKRelativeDateTextProvider(date: timerStart, style: .timer, units: units)

13:16 - CLKComplicationDataSource - Multiple Complication Support

// CLKComplicationDataSource - Multiple Complication Support
extension ComplicationController {
    var descriptors : [CLKComplicationDescriptor] = []
    var dataDict = Dictionary<AnyHashable, Any>()
        
    for station in data.stations {
        dataDict = [“name": station.name, “shortName": station.shortName]
        descriptors.append(
            CLKComplicationDescriptor(
                identifier: station.name,
                displayName: station.name,
                supportedFamilies: CLKComplicationFamily.allCases,
                userInfo: dataDict))
    }
    
    descriptors.append(
        CLKComplicationDescriptor(
            identifier: "LogSighting",
            displayName: "Log Sighting",
            supportedFamilies: CLKComplicationFamily.allCases))

    descriptors.append(
        CLKComplicationDescriptor(
            identifier: "SeasonData",
            displayName: "Season Data",
            supportedFamilies: [.graphicRectangular]))
        
    // Call the handler with the currently supported complication descriptors
    handler(descriptors)
}

17:09 - CLKComplicationDataSource - Sample Templates

func getLocalizableSampleTemplate(
    for complication: CLKComplication, 
    withHandler handler: @escaping (CLKComplicationTemplate?) -> Void) 
{
    let template = createSampleTemplate(forComplication: complication)
    handler(template)
}

17:33 - Whale Watch - Entries

func createTimelineEntry(
    forComplication complication: CLKComplication, 
    date: Date) -> CLKComplicationTimelineEntry? 
{
    guard let template = createTemplate(forComplication: complication, date: date) else {
        return nil
    }
    return CLKComplicationTimelineEntry(date: date, complicationTemplate: template)
}

17:44 - Whale Watch - Templates

func createTemplate(
    forComplication complication: CLKComplication, 
    date: Date) -> CLKComplicationTemplate? 
{
    var station: Station? = nil
    if let stationName = complication.userInfo?["name"] as? String {
        station = data.stations.first(where: { $0.name == stationName })
    }
    
    let image = UIImage(named: "Spout-small")!
    let spoutFullColorImageProvider = CLKFullColorImageProvider(fullColorImage: image)
    let logSightingTextProvider = CLKSimpleTextProvider(
        text: "Log Sighting", 
        shortText: "Log")

    let defaultTemplate: (CLKComplicationFamily) -> CLKComplicationTemplate = { family -> CLKComplicationTemplate in
      // Return a default complication template for the given family
    }
  
    switch (complication.family, complication.identifier) {

    case (.graphicRectangular, "SeasonData"):
        return CLKComplicationTemplateGraphicRectangularFullView(
            ChartView(
                seriesData: data.last7DaysSightings, 
                seriesColor: .turquoise)

    case (.graphicCircular, "LogSighting"):
        return CLKComplicationTemplateGraphicCircularStackImage(
            line1ImageProvider: spoutFullColorImageProvider, 
            line2TextProvider: logSightingTextProvider)

    case (.graphicCircular, _):
        guard let station = station else { return defaultTemplate(.graphicCircular) }
        return CLKComplicationTemplateGraphicCircularView(
            SightingTypeView(station: station))
          
    case (.graphicCorner, _):
        guard let station = station else { return defaultTemplate(.graphicCorner) }
        return CLKComplicationTemplateGraphicCornerTextImage(
            textProvider: station.timeAndShortLocTextProvider, 
            imageProvider: station.whaleActivityFullColorProvider)
                
    case (.graphicExtraLarge, _):
        guard let station = station else { return defaultTemplate(.graphicExtraLarge) }
        return CLKComplicationTemplateGraphicExtraLargeCircularStackText(
            line1TextProvider: station.timeAndLocationTextProvider, 
            line2TextProvider: station.shortLocationTextProvider)

    default:
        return defaultTemplate(complication.family)
    }
}

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

资源

相关视频

WWDC20