Create engaging content for Swift Playgrounds
Swift & UI 进阶 20m

为 Swift Playgrounds 创建引人入胜的内容

Create engaging content for Swift Playgrounds

2022年6月6日

在 Apple 官方观看视频

一句话判断

Swift Playgrounds 4 的全新教学系统——通过 guide module、walkthrough 和 experiment 三种任务类型，你可以在代码编辑器旁直接构建交互式教学体验。

这场 Session 讲了什么

Swift Playgrounds Content 团队的 Stephanie 和 Marcus 介绍了如何在 Swift Playgrounds 4 中创建教学内容。以一个”Emoji App”的舞蹈视图增强为例，演示了如何使用新的指令式教学系统引导学习者完成代码修改。

Session 覆盖了教学系统的三个核心组件：项目引导模块（guide module）、引导文件（guide file）的 markdown 指令语法、以及 walkthrough 和 experiment 两种任务类型。

值得深挖的点

Guide Module 的文件结构。一个支持教学系统的 Swift Playgrounds 项目需要特定的目录结构：根目录放 Package.swift，然后创建 App module（存放所有源代码和资源）和 Guide module（存放教学内容）。Guide module 中需要一个 guide 文件，用 markdown + 自定义指令描述整个教学流程。

指令（Directive）体系。Guide 文件使用 Apple 扩展的 markdown 语法，通过 directive 定义 UI 元素和内容结构。核心指令包括：guidebook（顶层容器）、welcome message（欢迎信息）、guide + step（学习中心和任务的容器）、ContentAndMedia（学习中心的图文内容）、TaskGroup + Task（具体任务）。

Walkthrough 任务。用于逐步讲解代码概念，适合解释复杂逻辑。以卡片形式展示在源文件顶部，可以包含多页内容，每页有文本、图片和代码片段。学习者阅读后可以直接在下方编写代码。

Experiment 任务。提供代码修改目标和预期结果对比，鼓励学习者动手实验。系统会显示”前/后”代码对比，让学习者直观看到需要修改什么。

代码片段

<!-- Guide 文件的指令结构示例 -->
@Guidebook(title: "舞蹈派对", icon: "music.note", background: "disco.jpg") {
    @WelcomeMessage {
        欢迎来到舞蹈派对！我们将用 SwiftUI 的颜色、形状和动画让派对嗨起来。
    }
    
    @Guide {
        @Step {
            @ContentAndMedia {
                ## 学习目标
                在这个项目中，你将学习如何使用自定义 View Modifier
                为动物添加舞蹈动画效果。
                ![舞蹈效果图](dance-preview.png)
            }
            @TaskGroup(title: "任务列表") {
                @Walkthrough(title: "创建舞蹈地板", file: DanceFloor.swift) {
                    @Page {
                        ## 舞蹈地板
                        我们用 10x10 的网格作为背景...
                        ```swift
                        // 自定义视图修饰符
                        struct DanceFloorModifier: ViewModifier {
                            func body(content: Content) -> some View {
                                content.background(
                                    Grid(rows: 10, columns: 10)
                                )
                            }
                        }
                        ```
                    }
                }
            }
        }
    }
}

最佳实践

  • 教学内容的难度曲线要平滑——从简单的 walkthrough 开始，逐步引入 experiment 任务
  • 欢迎信息要简短有力，让学习者快速了解项目目标
  • ContentAndMedia 区域适合放置较长的说明文字和复杂图表，利用可滚动视图展示
  • 代码片段要精简，聚焦于要讲解的核心概念
  • 任务分组（TaskGroup）有助于将同一主题的多个任务组织在一起

还有什么值得关注

  • Swift Playgrounds 4 支持在 iPad 和 Mac 上运行，教学内容会自动适配不同屏幕尺寸
  • 教学系统完全基于 markdown，版本控制和协作都很方便
  • 可以参考 Apple 官方发布的教程产品（如 “Keep Going with Apps”）作为内容设计的范本
WWDC 2022