使用 Swift-DocC 创建丰富的文档

使用 Swift-DocC 创建丰富的文档

了解如何利用 Swift-DocC 的最新功能为你的 App 或框架创建丰富而详实的文档。我们将向你展示如何使用 Xcode 15 文档预览编辑器高效迭代现有项目的文档，并探索扩展的各创作功能，例如基于网格的布局、视频支持和自定义主题。为了充分利用本次讲座，你最好对 Swift-DocC 文档的基础知识有一定的了解。

章节
- 0:00 - Introduction and overview of Swift-DocC
- 3:33 - Building and browsing documentation in Xcode
- 6:21 - Documenting Swift extensions
- 8:05 - Activating the Documentation Preview editor
- 9:44 - Adding an image to your documentation
- 12:06 - Organizing documentation pages into Topic Groups
- 13:53 - Using Swift-DocC directives to create rich documentation pages
- 25:12 - Theming the online version of your documentation
- 28:29 - Publishing and browsing documentation on the web
- 31:02 - Quick navigation
资源
- DocC
- - 高清视频
  - 标清视频
相关视频

WWDC23
- Xcode 15 的新功能
WWDC22
- 提高 Swift-DocC 内容的可发现性
- Swift-DocC 的新功能
WWDC21
下载

♪ ♪
Ethan：大家好！欢迎来到 “使用 Swift-DocC 创建丰富的文档” 我是 Ethan Swift-DocC 团队的一名工程师 Xcode 15 竭力为 Swift-DocC 文档提供了丰富的新功能这些功能不仅能让你的文档别具一格还为你提供了向读者介绍 App 或框架时更有效的工具通过 Xcode 15 全新的文档预览编辑器无需离开源编辑器你也可以迭代文档我迫不及待地想向你展示了让我们先快速了解一下 Swift-DocC Swift-DocC 是直接集成到 Xcode 中的文档编译器有了它你就可以在对照源代码的情况下同时为项目编写和发布精美的文档你可以混合使用直接在源代码中编写的文档注释和独立的 Markdown 文件来编写高级概念内容和详细的技术文档该文档与静态网络托管解决方案开箱即兼容并允许直接发布到 GitHub Pages 和 Netlify 等服务当然你的文档也会出现在 Xcode 的内置文档窗口中并通过快速帮助集成到 Xcode 的源编辑器中这意味着你编写的文档将可自动供任何有权访问源代码的人使用而无需你做任何额外的工作自 Swift-DocC 在 Xcode 13 中发布以来 Swift-DocC 项目已开源并且现已公开开发我们与 Swift 社区合作为你的所有项目增加文档支持包括支持 Swift、Objective-C 或两者混合编写的 App 和框架 Xcode 15 将编写 Swift-DocC 文档的体验提升到了一个全新的水平文档预览编辑器为你提供了输入内容时文档渲染版本的实时视图并在每次按键时提供反馈通过全新的创作功能如基于网格的布局、视频支持、自定义页面图标甚至完全自定义的主题你可以为你的项目制作提供支持的定制文档本次讲座将重点介绍 Swift-DocC 的一些更高级的功能因此如果这是你第一次学习 Swift-DocC 我建议你先看看 “认识 Xcode 中的 DocC 文档” 和“在 Xcode 提升 DocC 文档” 这两个讲座将介绍我们改进今天文档的计划框架并指导你完成为一个全新的项目添加第一批文档的过程
今天我们首先介绍一个使用 Xcode 15 文档预览编辑器编写文档的新工作流我们将使用新的编辑器因为我们将通过一些新的 Swift-DocC 功能来增强框架的现有文档为了让 web 版本与现有网站相一致接下来我们将为文档创建一个自定义主题最后在网络上发布文档之后我们将介绍 Xcode 15 为所有 Swift-DocC 网站带来的全新导航功能让我们开始吧
在过去的几年里我和我的团队一直在开发一个名为 SlothCreator 的 Swift 包 SlothCreator 是一个可以导入到 iOS App 中的框架用于编目、定制和显示小树懒我们希望 SlothCreator 能够在更多 iOS App 中使用所以我们一直在寻找提高其文档质量的方法我在 Xcode 15 中打开了 SlothCreator 的 Swift 包让我们先来评估其文档的当前状态将鼠标移至 Product 菜单并选择 Build Documentation
Xcode 会将我的项目及其文档一同构建出来然后打开文档窗口这是你可以在自己的项目中尝试的即使你没有专门为 Swift-DocC 编写任何文档 Swift-DocC 自动为你项目中的相关 API 创建页面包括你可能为其编写的任意文档注释因此你可能会惊讶于这些文档开箱即用的便捷程度更棒的是当你选择 Build Documentation 时 Xcode 还将为你的项目的所有依赖项生成文档所以如果你依赖任何第三方库比如 SlothCreator 这些内容也会出现这是 SlothCreator 的文档首页其以一个总结性句子为开始随后概述该框架的全部内容我把页面往下拉一点来到 Topics 部分 Topic 的作用是将文档的不同页面组织成合理的组别首先我们有 Essentials 其中包含为框架新读者提供的介绍性文档然后是一个包含符号的组帮助创建树懒以及照顾和喂养树懒等等组织良好的主题分组是创建可发现且可访问的项目文档的关键我建议你观看 “提高 Swift-DocC 内容的可发现性” 学习一些高级技术让读者能够轻松浏览你的文档让我们打开 Sloth 结构的文档点按文档链接
Sloth 的文档真的很不错概述到位包含了相关页面的内联链接一个帮助我入门的代码示例以及因组织良好而有助于发现相关符号的 Topic 组点按后退按钮导航回 SlothCreator 的首页现在继续向下滚动页面我对这里的组织方式非常满意但在页面的最底部我看到了一个以前从未见过的符号即 SwiftUI 模块好吧事实证明这个符号的出现是因为 Xcode 15 中的一个新 Swift-DocC 功能即拓展支持通过 Xcode 15 现在可以记录你对属于其他框架的类型所做的扩展扩展是一个强大的 Swift 语言功能它允许你为原始源代码无法访问的类型添加功能例如你可以扩展 SwiftUI 的 View 协议为你的 App 添加一些额外的功能现在你可以将这些扩展符号与你的 App 或框架的其他部分一起录入文档这项新功能完全由社区贡献驱动涉及 Swift-DocC 和 Swift 编译器之间的协调更改让我们看看如何当场使用它完善 SlothCreator 的文档单击 SwiftUI 扩展模块
SlothCreator 扩展了 SwiftUI 的 Image 结构所以 Image 作为一个扩展出现在了这里打开 Image 页面可以看到添加了一个初始化程序这个初始化程序的文档涵盖了正确的基本内容但似乎还没有达到我之前看的 Sloth 结构的质量让我来改进一下将鼠标移至项目导航栏上选择 ImageExtensions 文件打开包含我的扩展的 Swift 文件
关闭项目导航栏
这是基于 Sloth 的 Image 初始化程序的声明
声明的正上方是该符号的文档注释由其前面的三个正斜杠定义我想为这个初始化程序添加一些额外的文档用 Xcode 15 编写文档的最佳方法是使用新的文档预览编辑器要激活文档预览辅助编辑器可以先打开 Editor Options 菜单
然后选择 Assistant 项点按辅助编辑器的跳转栏即可开启辅助模式最后选择 Documentation Preview 大功告成现在当你在 Swift 源文件、 Objective-C 头文件和文档 Markdown 文件之间移动时文档预览将始终保持活跃让我们在 SlothCreator 中尝试一下
很好我会先创建 Discussion 部分 Swift-DocC 将文档注释的第一行作为页面的摘要或概括句接下来的一段用作 Discussion 部分输入“使用这个初始化程序显示一个给定树懒的图像表示” 当我输入时文档预览会实时更新显示符号文档的渲染版本接下来我想添加一个代码示例向大家展示如何在实践中使用这个初始化程序我先使用 Markdown 的隔离代码块语法创建一个代码块
我将指定“Swift”为源语言用于语法突出显示随后粘贴我的代码示例
该示例演示了如何创建一个渲染冰树懒图像的 SwiftUI 视图由于该示例涉及 UI 我认为这里最好提供结果视图的截屏我已经在桌面上准备好了所需截屏
但要在我的文档中实际使用这个截屏我首先需要将图像添加到 SlothCreator 的文档目录中文档目录是一个可以添加到你的 Swift 包或 Xcode 项目中的文件目录并以 Markdown 文件、图片和视频的形式提供额外的文档内容你可以在此处放置较长的文章和教程你添加的任何图片或视频都可以从文档注释中引用如果展开项目导航栏我可以看到 SlothCreator 已经有一个文档目录所以我只需拖入截屏的明暗模式版本即可
我可以把图片放在文档目录中的任何地方 Swift-DocC 自然会找到它们这给了我选择如何组织目录的灵活性从而构建对我和我的团队最有价值的结构所以当我想在页面上加入一个图像时我只需通过其基本文件名就能引用该图像同样重要的是要注意文档目录中包含的图片和其他文件只能用于文档例如如果你想在 App 中加入图像可以使用资源目录现在我准备将截屏添加到我的文档中我使用 Markdown 的图片语法提供作为 alt 文本的描述文件和图片的文件名请注意我在这里只使用了基本文件名 DocC 会自动计算出适当的明暗模式版本最后添加一些结论性文字文档完成
不错文档预览编辑器使得为这个符号创建扩展性文档变得直接而有趣接下来我打算把该方法用到首页的 Topic 组中让这个方法路径更加完善我将激活项目导航栏并在文档目录中选择 “SlothCreator”的 Markdown 文件文档预览编辑器现在显示 SlothCreator 首页的渲染内容能够使用预览编辑器来更好地理解 DocC 语法是如何工作的这可真是太棒了例如我可以看到主题组是由第二级主题标题下的第三级标题定义的要把一个页面放到一个主题组中就要在其中一个三级标题下创建一个列表项并链接到该页面下面让我为扩展的 SwiftUI Image 类型执行此操作由于图像扩展是用来在用户界面上显示树懒的我认为它属于与渲染树懒有关的其他符号属于 Sloth Views 主题组所以我将其链接到相应组中代码补全能够提供对该类型的引用
很好现在 SlothCreator 的图像扩展文档归档全面且组织良好自从 SlothCreator 文档首次发布以来我们收到了一些反馈要求提供一个示例代码项目演示该框架的一些基本原理为此我们整合了一个名为 Slothy 的小程序由 SlothCreator 提供支持我的同事已经把团队想包括在 SlothCreator 主文档中的一篇文章的粗略草案整合好了该文章链接到新的 Slothy 样本让我们一起来看看首先把文章的初稿添加到 SlothCreator 的文档目录中
这里的内容已经非常不错了它引导我了解示例 App 的各个功能甚至包括 App 的截屏和一个可以下载示例的存储库链接但我觉得还有改进空间幸运的是 Swift-DocC 的一些新功能使改进成为可能 Swift-DocC 的创作语法是在 Markdown 基础上产生的如果熟悉 Markdown 你应该可以用链接、图像、粗体和斜体文本甚至表格来格式化自己的内容然后 Swift-DocC 用指令扩展了 Markdown 的基本语法让你能够使用为文档专门打造的功能
我现在要使用其中的一些指令来润色 Slothy 的示例代码文章但请记住使用这些指令的时候不要过于教条其使用没有唯一正确的方法也没有唯一适合使用某个指令的页面想想看你可以用自己喜欢的方式来使用这些指令从而将项目的文档打造得更容易理解、更有吸引力、更令人兴奋在深入研究并对文章的布局进行修改之前我想先确定其存在的具体问题这样我就可以确定当我采用这些新的指令时我确实是在提升文档质量对我来说最突出的问题就是那些不够突出的内容这个页面的风格和其他文章相差无几尽管我的读者可能会对有些示例代码特别感兴趣就这一点而言这篇文章做出的最重要改进是链接到示例代码的源代码库尽管如此示例代码链接仍然很难识别和发现接下来是文章的正文内容此内容围绕两个图像段落对构建每个段落都有一个与其描述相关的图像但有两个问题首先图像与对应段落没有明确关联其次图像占据了太多的空间这里的图片是为了突出对应的段落但其本身并不是很有趣
最后页面底部的一个部分概述了 SlothCreator 的本地化支持在这里同样的截屏有三种不同语言的版本但是因为它们是垂直堆叠的就都失去了与本地化段落的所有关联并且在视觉上占据了太多的空间让我们看看如何使用 Swift-DocC 解决这四个问题我们从文章的正文内容开始我认为图片与对应段落问题的正确解决方案就是将它们放入网格中这将更好地强调段落相对于图像的重要性并更好地建立图像与对应段落的联系在 Swift-DocC 中网格被定义为灵活的行和列我将先定义包含一个两列的行
然后把段落放在第一列图像放在第二列
效果我很满意图像现在与对应段落联系更明确了但我认为在这种情况下段落应该优先于图像让我们加宽包含段落的列宽我可以通过给第一列添加一个 size 参数并指定一个大于默认值 1 的值来实现这一点 size 参数用于设置给定列的宽度我先试着将参数值设为 3
第一列现在跨越了四列网格中的三列似乎有点太宽了不然试试 2？
文字和图像看起来比较平衡就这么办让我们尝试对第二个段落图像对进行相同的配置
这绝对是一种改进但页面现在感觉有点失衡让我们尝试翻转图像和段落
很好这篇文章风格统一了我们在本地化部分发现的问题是图像占据了太多的垂直空间因而看不到上下文标签栏导航是这个问题的完美解决方案有了它我就能将多个元素折叠为一个让我们试一下
创建一个包含三个标签栏的初始标签栏导航结构
标签栏导航由一个 TabNavigator 指令定义其中包含任意数量的子 Tab 指令每个标签的名字都作为参数我把这三张图片放在各自的标签栏中
现在我的读者可以随意点按任意标签访问他们感兴趣的截屏
要想更上一层楼的话我想添加一个短视频真正吸引我的读者让他们在观看示例后就兴奋不已 Swift-DocC 有一个视频指令我现在将其插入
我还想添加一个海报图像在视频播放前显示包括视频本身和一段文字描述
不错让我们进入介绍部分我注意到的第一个问题是很难找到访问示例源代码存储库的链接 Swift-DocC 有一个号召性用语正是为此而设计的我将先在页面顶部添加元数据容器指令元数据指令用于指定不直接在页面上呈现的额外信息在本例中我想将号召性用语附加到页面中
我已经给出了号召性用语的目的 URL 和用途请注意我使用了值为“link”的用途或者如果这个链接直接指向下载那我可以将值设为“download” 但在这种情况下我链接的是源代码库所以“link”是更好的选择最后我希望这篇文章从 SlothCreator 文档的其他文章中脱颖而出我想确保读者不要错过这个页面包含的示例代码事实证明 Swift-DocC 对包含示例代码的文章有特殊支持我将通过键入带有“sample code” 参数的 PageKind 指令将页面类型指定为示例代码渲染后的页面现在有一个 “Sample Code”标题和一个大括号页面图标这都让这篇文章的主题一目了然现在 Swift-DocC 只支持两个 PageKind 指令的值即“article” 和“sample code” 我们很乐意了解你感兴趣的其他默认页面类型由于 Swift-DocC 是一个开源项目 Swift 论坛会是讨论此类话题以及关于 DocC 如何更好满足你的文档需求的任何其他反馈或想法的好地方
我认为对在自己的 App 中使用 SlothCreator 感兴趣的开发人员会为这篇文章而十分兴奋毕竟这篇文章引人入胜、卓有想法且趣味横生我想确保开发人员能发现这篇文章让我们回到 SlothCreator 的首页找到一个显著的位置链接到文章
首先把新文章组织到一个 Topic 组中在这种情况下我认为 Essentials 组是最合适的因为我们希望 SlothCreator 框架的新读者能够对 Slothy 示例感兴趣
这是一个好的开始但我想更进一步将这篇文章放在页面比较通用的主题部分之上 Links 指令非常适合此目的我将创建一个 Featured 组然后插入 Links 指令
Links 是突出显示某些页面的好方法你可以使用 Links 以更高级的方式为文档加入卡片图像和页面描述 Links 指令可以设置一个视觉样式参数定义链接应呈现的方式然后在其主体中列出链接列表就像一个 Topic 组一样现在我链接到 Slothy 示例
链接支持多种视觉样式从渲染得非常像默认主题部分的基本列表到详细的网格
我认为网格样式很好但我想在此处用一个自定义图像来代表 Slothy 示例让我们回到 Slothy 的 Markdown 为了使这篇 Slothy 文章为基于网格的 Links 部分展示做好最佳准备我需要在其元数据中加入一个页面图像开始吧
我会指定其用途为“card” 以便在将 Slothy 文章渲染为 card 时使用此图像然后提供图片的来源和描述作为 alt 文本返回 SlothCreator 的首页时
Slothy 已经有了自定义页面图像我还打算加入一篇名为 “Getting Started with Sloths”的文章
作为画龙点睛之笔我还将在首页添加一些额外的元数据从创建 Metadata 指令开始就像我们之前做的那样然后我会加入页面图像
这次我设置的用途是“icon”而不是“card” 因此此图像将用于页面图标渲染的任意位置包括页面的导航侧边栏和介绍部分最后我打算设置一个自定义页面颜色
默认情况下首页使用蓝色但 Swift-DocC 提供了许多内置的标准颜色比如黄色、紫色和橙色 SlothCreator 一般使用绿色作为强调色所以我认为在这个页面使用绿色会营造出更有凝聚力的体验
哇 SlothCreator 文档在短短的时间内就取得了这么大的提升我们使用了一些布局指令如 Row 和 Column Tab Navigator 和 Video 让这篇示例代码文章更流畅吸引更多读者我们还使用了 CallToAction 和 PageKind 等元数据指令以对文章进行进一步打磨我们使用 Links 指令优化特色内容并使用 PageColor 和 PageImage 指令让首页更为引人注目我非常高兴能够分享 SlothCreator 的更新文档但在我们将新版本发布到网络之前让我先演示一下如何使用自定义主题优化 SlothCreator 文档的在线呈现具有自定义主题的 SlothCreator 文档 SlothCreator 的文档会作为更大产品网站的一部分发布我想确保文档站点与产品站点在视觉上保持一致使用相同的调色板和字体集让我们看一下如何使用 Swift-DocC 中的自定义主题来实现这一目标 Swift-DocC 支持在文档站点的给定部署中完全自定义视觉样式的呈现方式如颜色、边框、图标和字体这些自定义是在一个特殊的 JSON 文件中完成的你可以将其包含在文档目录中这些自定义设置可以更好地将文档站点与其他在线站点集成为一体你可以使用 Swift-DocC 的主题工具来匹配特定的企业风格或者更好地配合营销网站或个人博客然而主题化并不一定适用于所有文档自定义设置例如如果你对定制特定页面的外观感兴趣就像我们对 SlothCreator 的示例代码页所做的那样那你应该在该页面上使用指令而不是自定义主题主题自定义是站点范围内的而不是特定于页面的还需要注意的是 Swift-DocC 主题会更倾向于某一类部署因此如果你在 Xcode 中打开文档文档仍然会用 Xcode 主题渲染与其他 Xcode 文档放在一起会看起来很棒这意味着你可以将自定义主题集中在网站的网页呈现上不用担心它会影响 Xcode 中的阅读体验但这也意味着如果你希望自定义代码同时出现在 Xcode 和网络上最好只使用一种指令让我们看看 SlothCreator 的自定义主题 Swift-DocC 中的主题是由一个名为“theme-settings.json”的 JSON 文件定义的你可以把该文件放在项目的文档目录中使用主题设置文件可以进行多种不同类型的自定义对于 SlothCreator 我只是要自定义网站的颜色和字体这些自定义项分别放在 “color”和“typography”部分
SlothCreator 在其营销材料中使用了独特的绿色色调而我也已经使用 PageColor 指令将 SlothCreator 的首页颜色设置为绿色现在我可以使用 “standard-green”颜色变量将特定的绿色阴影设置为我想要的颜色而且因为 SlothCreator 是一个针对资深 Sloth 专业人士的相当严肃的框架我打算在其在线文档中使用 Serif 字体用“html-font”排版变量就可以实现这一点当然这些自定义设置只是 Swift-DocC 主题功能最基础的部分如果你有兴趣进一步了解我推荐你阅读 Swift-DocC 的说明文档既然我们已经配置好了 “theme-settings.json”文件我会将其添加到我的文档目录中
SlothCreator 的源代码控制存储库已经配置了持续集成每当我们推送提交的新内容时都会使用“xcodebuild” 命令行工具来构建和部署 SlothCreator 的文档这是一个很好的工作流程可以确保文档始终与框架中的最新更改保持同步如果你想为自己的项目设置类似的工作流程请查看 Xcode 文档中的 Swift-DocC 部分能发布我们一起做出的这些改进我真的很兴奋抓紧提交并推送你的文档一起体验网站的新部署吧将鼠标移动到 Xcode 窗口的左上角并激活源代码控制导航器点按 Stage All 提交所有更改
点按 Commit 添加提交消息最后点按 Commit and Push 提交并推送修改
现在我打开 SlothCreator 的网站这是 SlothCreator 产品网站的主页网站使用的是与 SlothCreator 品牌相匹配的特定字体和颜色单击“Read Documentation”按钮
打开 SlothCreator 的文档网站版本有我们应用的自定义主题含有独特的字体和绿色阴影该主题还包含我们设置的自定义图标以及带有全新的 Slothy 示例代码文章的诱人且别具一格的部分点按“View sample code” 链接打开示例代码我对这篇文章的呈现效果非常满意当然 Swift-DocC 网站还有一个很棒的导航侧边栏这使得我在 SlothCreator 的 Topic 部分组织的页面导航起来更加简单易用页面顶部是 Essentials 组我们将 Slothy 示例代码文章、入门文章“Getting Started”和 Sloth 结构都放在此处单击左侧的下拉三角符号展开 Sloth 结构此时我们就可以浏览该结构的子节点当然这些符号在主题组中也组织得井井有条让我们检查一下之前文档中的图像初始化程序我将向下滚动到 Sloth 视图部分展开图像扩展符号并单击初始化程序就是这个界面作为文档作者我喜欢导航侧边栏有了它我就能为开发者打造直观的浏览体验并真正指导他们了解我的项目的 API 但有时作为文档阅读者我确切地知道我在寻找哪个页面只是需要一种简单的方式直接跳转过去使用 Xcode 15 构建的 Swift-DocC 网站拥有全新的快速导航功能这使得页面之间的跳转变得轻而易举 Swift-DocC 快速导航是又一个由社区驱动的工作我们非常高兴将其引入所有 Swift-DocC 网站与 Xcode 的 Open Quickly 功能类似只需激活一个快捷键并输入页面名称就可以直接跳转到该页面让我们试一下按 Shift-Command-O 快捷键激活快速导航
我可以立即开始过滤 SlothCreator 文档中的所有页面例如如果我正在寻找一篇入门文章我可能只需要输入“start”
看找到了我甚至可以在右侧预览这篇文档
按 Enter 键导航到该页面
但也许我需要一个关于 Sloth 不同功能的提示工具再次按下 Shift-Command-O 然后输入“power”
就找到了 PowerPicker 接着看到一个“power”属性啊这就是关于 Power 的枚举这次我通过“View more” 链接打开该页面
就像这样我就可以查看所有可用的 Sloth 功能有了新的快速导航弹窗和已有的导航侧边栏 Swift-DocC 使浏览文档成为一种绝佳的体验 Xcode 15 中的 Swift-DocC 提供了强大的新工具可以用于创建真正独特的文档网站尝试一下全新的文档预览编辑器吧你可以从探索不同的页面布局以及了解如何实时渲染中获得乐趣新的指令如 Row 和 Column、 Links 和 PageImage 让你可以制作精美且对项目有支持作用的文档考虑是否应该添加一个自定义主题以使文档的 web 版本更好地与项目的品牌或现有的线上形象一体化若想了解 Swift-DocC 的最新情况请查看 WWDC22 的 “Swift-DocC 中的新增功能”讲座这场讲座会将深入介绍 Xcode 14 发布的新工作流向你准确展示如何将内容发布到 GitHub 页面等静态托管服务如果你有兴趣通过一步一步的教程进一步了解你的文档我建议观看 “使用 DocC 构建交互式教程” 我很期待看到你用 Swift-DocC 和 Xcode 15 设计和发布的文档谢谢大家 ♪ ♪

import SwiftUI

/// An extension that facilitates the display of sloths in user interfaces.
public extension Image {
    /// Create an image from the given sloth.
    ///
    /// Use this initializer to display an image representation of a
    /// given sloth.
    ///
    /// ```swift
    /// let iceSloth = Sloth(name: "Super Sloth", color: .blue, power: .ice)
    ///
    /// var body: some View {
    ///     Image(iceSloth)
    ///         .resizable()
    ///         .aspectRatio(contentMode: .fit)
    ///     Text(iceSloth.name)
    /// }
    /// ```
    ///
    /// ![A screenshot of an ice sloth, with the text Super Sloth underneath.](iceSloth)
    ///
    /// This initializer is useful for displaying static sloth images.
    /// To create an interactive view containing a sloth, use ``SlothView``.
    init(_ sloth: Sloth) {
        self.init("\(sloth.power)-sloth")
    }
}

16:31 - Creating a grid-based layout

@Row {
    @Column(size: 2) {
        First, you customize your sloth by picking its 
        ``Sloth/power-swift.property``. The power of your sloth influences
        its abilities and how well they cope in their environment. The app
        displays a picker view that showcases the available powers and
        previews your sloth for the selected power.
    }
    
    @Column {
        ![A screenshot of the power picker user interface with four powers displayed – ice, fire, wind, and lightning](slothy-powerPicker)
    }
}

@Row {
    @Column {
        ![A screenshot of the sloth status user interface that indicates the the amount of sleep, fun, and exercise a given sloth is in need of.](slothy-status)
    }
    
    @Column(size: 2) {
        Once you've customized your sloth, it's ready to ready to thrive.
        You'll find that sloths will happily munch on a leaf, but may not be as 
        receptive to working out. Use the activity picker to send some
        encouragement.
    }
}

18:16 - Creating a tab navigator

@TabNavigator {
    @Tab("English") {
        ![Two screenshots showing the Slothy app rendering with English language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_eng)
    }
    
    @Tab("Chinese") {
        ![Two screenshots showing the Slothy app rendering with Chinese language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_zh)
    }
    
    @Tab("Spanish") {
        ![Two screenshots showing the Slothy app rendering with Spanish language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_es)
    }
}

19:07 - Adding a video

@Video(poster: "slothy-hero-poster", source: "slothy-hero", alt: "An animated video showing two screens in the Slothy app. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.")

19:50 - Specifying a page's "Call to Action" link

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
}

20:29 - Specifying a page's kind as "Sample Code"

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
    @PageKind(sampleCode)
}

21:55 - Using the "Links" directive to feature content

@Links(visualStyle: detailedGrid) {
    - <doc:GettingStarted>
    - <doc:SlothySample>
}

22:55 - Specifying a page's card image

@Metadata {
    @PageImage(
        purpose: card, 
        source: "slothy-card", 
        alt: "Two screenshots showing the Slothy app. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.")
}

23:41 - Specifying a page's icon image

@Metadata {
    @PageImage(
        purpose: icon, 
        source: "slothCreator-icon", 
        alt: "A technology icon representing the SlothCreator framework.")
}

23:42 - Specifying a page's color
```
@Metadata {
    @PageColor(green)
}
```

27:04 - theme-settings.json

{
    "theme": {
        "color": {
            "standard-green": "#83ac38"
        },
        "typography": {
            "html-font": "serif"
        }
    }
}

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

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

章节

资源

相关视频

WWDC23

WWDC22

WWDC21