WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Create Swift Playgrounds content for iPad and Mac

Create Swift Playgrounds content for iPad and Mac

WWDC 2020SwiftSwift PlaygroundsMac Catalyst
观看原视频

Highlight

Swift Playgrounds 的 Mac 版本让同一本 Playground Book 覆盖 iPad 和 Mac，作者可以用 supportedDevices、requiredCapabilities、quick help、target environment 检查和系统颜色为两类设备裁剪体验。

核心内容

Swift Playgrounds 先在 iPad 上让很多人接触 Swift。到 2020 年，借助 Mac Catalyst，同一个 app 也来到 Mac。问题随之变具体：一本原本为触摸屏写的 Playground Book，放到带键盘、鼠标、窗口工具栏和不同系统设置的 Mac 上，文字、按钮、代码补全和 live view 布局都可能露出不合适的地方。

Apple 在这场 session 里把问题拆成几类。第一类是学习体验本身：Mac 上的代码补全有新的可展开区域，可以显示 token 的 quick help；iPad 上这些描述也会出现在 quick help popover 和原来的代码补全栏里。作者只要给声明和参数补上三斜线文档注释，学习者就能在敲代码时看到更明确的说明。

第二类是分发和运行条件。Playground Book 文档格式增加了 supportedDevices 和 requiredCapabilities 两个可选键。前者决定一本书支持 iPad、Mac，还是两者都支持；后者用 ARKit、microphone、Wi-Fi 这类能力过滤设备。这样，作者可以让内容尽量覆盖更多设备，只把确实依赖某项硬件能力的章节限制住。

第三类是跨平台细节。演讲中的 turtle demo 在 Mac 上展示颜色弹窗和 quick help，在 iPad 上检查深色模式和 AR 按钮。一个白色背景在深色模式下立刻显得刺眼，原因是使用了固定的 UIColor.white；改用系统背景后，界面会跟随主题变化。这个例子说明，Playground Book 不是把同一份页面塞进两个设备就结束，作者需要检查文案、系统颜色、安全区和辅助功能。

详细内容

让代码补全承担教学说明

（01:03）Mac 版 Swift Playgrounds 的代码补全区域可以展开，并显示每个 token 的 quick help。quick help 文本可以本地化，参数也可以写说明。演讲者明确给出写法：把三条 forward slash 放在声明正上方，再给参数补描述。

关键点：

  • 三斜线文档注释会进入 Mac 的展开式代码补全区域。
  • 同一段说明也会在 iPad 的 quick help popover 和原代码补全栏里出现。
  • 这适合教学内容，因为学习者不用离开编辑器就能理解 changeTurtleEyes 这类自定义方法。
  • 如果 Playground Book 面向多语言用户，quick help 描述也应该进入本地化流程。

用 manifest 控制支持的设备

（01:46）Playground Book 文档格式增加了两个可选键：supportedDevices 和 requiredCapabilities。如果一本书只适合某个平台，可以在 book level manifest 和 feed JSON 里写 supportedDevices。有效值是 iPad 和 Mac。

关键点：

  • book level manifest 和 feed JSON 都需要写同样的支持设备信息。
  • 同时声明 iPad 和 Mac 时，这本书会在两个平台上可见。
  • 如果从 supportedDevices 中移除 Mac，这本书不会出现在 Mac 的 feed 中。
  • 这个机制适合处理整本书的平台边界，例如只依赖 iPad 交互的内容。

用能力限制替代设备限制

（02:44）Apple 建议尽量支持更多配置。比起直接排除一个平台，很多内容只需要检查某项能力。requiredCapabilities 可以使用 UIRequiredDeviceCapabilities 中的值，例如 ARKit、microphone 和 Wi-Fi。

关键点：

  • requiredCapabilities 也要同时放进 book level manifest 和 feed JSON。
  • 示例中的 book 需要 microphone 和 ARKit，设备不满足这些能力时就不会显示。
  • 这种做法比只写 supportedDevices 更细，因为 Mac、iPad 之间的差异常常来自具体硬件能力。
  • 如果某一页只是 AR 功能不可用，可以保留其他页面，并把 AR 入口按能力或平台隐藏。

按平台裁剪同一本书

（03:17）演讲者强调，最好支持尽可能多的配置，即使不同平台上的功能有差异。Playground 内容可以通过 target environment 判断当前是为 Mac 还是 iPad 编译。文案也要检查，避免把 Mac 用户带进触摸屏语境。

关键点：

  • 使用 target environment 检查时，同一本书可以在 iPad 和 Mac 上走不同体验。
  • 文案建议使用 tap 或 select 这类通用词，少用只适合某个平台的 click 或 touch。
  • demo 里的 AR 按钮只在非 macOS 环境出现，因为 Mac 没有需要的 ARKit 能力。
  • 这种裁剪保持了同一本书的分发路径，也减少了为每个平台维护独立内容的成本。

尊重系统颜色和 live view 安全区

（03:45）跨平台内容还要响应设备设置。系统提供的颜色，例如 label 和 system background，会自动适配深色模式和系统 accent color。作者也可以把自定义 adaptive colors 放进 book 的 asset catalog。

关键点：

  • 固定颜色容易出问题，demo 中的 UIColor.white 在 iPad 深色模式下造成突兀的白底。
  • 改用系统背景后，页面会跟随浅色和深色模式切换。
  • live view safe area 需要特别检查；Mac 的 live view 右上方有 toolbar buttons，安全区和 iPad 不同。
  • 如果旧代码使用 playground live view safe area container 的 liveViewSafeAreaGuide，现在可以改用标准的 UI layout guide 访问安全区。

核心启发

  • 做一个跨平台编程课本：把一组 Swift 入门练习做成 Playground Book，在 manifest 和 feed JSON 中同时支持 iPad 与 Mac。值得做的原因是学习者可以在触摸屏或桌面环境继续同一套课程。开始时先检查每页文案，把 click、touch 这类平台词改成 tap 或 select。

  • 做一个带能力过滤的 AR 练习页：让普通页面在 iPad 和 Mac 上都可用，只在支持 ARKit 的 iPad 上显示 AR 入口。值得做的原因是 session 明确推荐用 requiredCapabilities 覆盖具体硬件需求。开始时把 ARKit 加入 book level manifest 和 feed JSON，再用 target environment 检查隐藏 Mac 上的 AR 按钮。

  • 做一套本地化代码补全教学卡片：给自定义 turtle 方法、参数和练习 API 写三斜线 quick help，并为不同语言准备描述。值得做的原因是 Mac 的展开式补全区域和 iPad 的 quick help popover 都会显示这些说明。开始时先挑 5 个学习者最容易卡住的 token，给它们补上短句说明。

  • 做一个深色模式验收页：把每个 live view 放到浅色和深色主题里跑一遍，找出固定白底、错误 accent color 和被工具栏遮住的控件。值得做的原因是演示里的白色背景问题只有切到 iPad 深色模式后才暴露。开始时把固定颜色替换成 label、system background 或 asset catalog 中的 adaptive colors。

  • 做一份发布前平台清单：发布 Playground Book 前逐项检查 quick help、supported devices、required capabilities、target environment 分支、safe area 和辅助功能。值得做的原因是 session 收尾把这些内容列成了跨平台 Playground 内容的核心检查项。开始时先用 Mac 和 iPad 各跑一遍同一页，记录两边不一致的交互和布局。

关联 Session

评论

GitHub Issues · utterances