[ WWDC2018 ] - 创建属于你自己的 Swift Playgrounds 订阅 Create Your Own Swift Playgrounds Subscriptio

Swift Playgrounds 是一款革命性的 iPad 应用,可以用强大的 Swift 语言进行教学。苹果推崇在 Swift Playgrounds 上人人都能使用 Swift 编程的原则,让所有人都能学习、编码以及教授代码课程。

本 Session 主要讲如何利用 WWDC2018 新的模板工具制作出属于自己的 Playground Book以及如何托管自己的订阅源并分享给他人。让我们带着这两个问题来阅读本文。

Playground 电子书简介

苹果在 Swift Playgrounds 应用上提供了很多学习编程相关的 Playground Book,本文就通俗的称之为电子书

Playground 电子书(.playgroundbook),它能够帮助你管理内容,生成浏览目录,使你更容易找到自己想要学习的章节及页面,下面是 Playground 电子书页面的一张截图,感受一下:

swift_playground_preview.jpeg

图的左边是源代码编辑器,右边是“所见即所得”的实时视图。相比于 Xcode Playgrounds 功能更加强大,感兴趣的读者可以查阅相关资料,本文不做详述。

WWDC2016 - Session 408 Introducing Swift Playgrounds

目录格式

在学习如何利用新的版本工具前,我们先快速了解下 Playground 电子书的目录格式。 Playground 电子书,是一个带有 .playgroundbook 后缀名的文件,可以理解为一个文件夹资源包,它是一个嵌套的文件夹结构格式,其中包括所有资源文件。

playground_book_package_structure.png

我们根据目录结构主要把它区分三个层次:

  • ContentsPlayground 电子书根目录,包含所有资源文件,属于最高层级,其中包含 Chapters 文件夹以及一个配置文件 Manifest.plist

  • Chapters:总章节文件夹,包含所有章节文件夹。每个章节文件夹都带有 .playgroundchapter 后缀,并且其目录下都包含 Pages 文件夹以及一个配置文件 Manifest.plist

  • Pages: 总页面文件夹,包含所有页面文件夹,每个页面文件夹都带有 .playgroundpage 后缀,其目录下都包含着自己运行所需要的所有资源以及一个配置文件 Manifest.plist

package_structure_folder_names.png

上述的三个目录下都有属于自己 Manifest 配置文件,有什么作用呢?

分别如下:

  • 描述电子书的信息

  • 描述章节及目录信息

  • 描述页面信息以及其行为(详述请移步至官方文档

至此,你可能会有个小疑惑,为何文件夹会有后缀,干啥用的呢?

  • .playgroundbook

  • .playgroundpage

  • .playgroundchapter

这个设计官方给出了一个解释:仅仅就是为了表明其类型。(No more thing.)

此外还有两种文件夹,一般放置与 Contents 目录下:

  • Sources:辅助的 Swift 源文件,如果放置在 Contens 目录下,意味着所有 Page 都能访问,属于全局范畴

  • Resources:电子书的资源文件,一般放置一些图片、音频文件等等,其他类似于 Sources 文件夹。

PlaygroundSupport

在制作 Playground 电子书时,PlaygroundSupport 对于我们来说是一个非常有帮助的组件,我们可以利用该组件在 PlaygroundLiveView 之间进行交互,如:

  • 共享和访问持久化数据

  • 访问 Playground 并对其进行管理

  • 操作 LiveView 显示或者隐藏

  • PlaygroundLiveView 之间进行消息传递

  • 保存用户的学习进度等等

如果我们想在 LiveView 上显示一个 View,利用 PlaygroundSupport 可以这样写:

import UIKit  
import PlaygroundSupport

let view = UIView(frame: CGRect(x: 0, y:0, width: 200, height: 200)

PlaygroundPage.current.live = view 

使用 Swift Playgrounds 模板

了解了上述的一些基本知识后,再来看看 Swift Playgrounds 模板,这是今年 WWDC2018 新推出的,支持 Xcode 9.3 以上,首先我们先抛出一个问题,为何会有 Swift Playgrounds 模板这东西?

回顾

从 WWDC 2016 Swift Playground Books 诞生开始,制作 Playground 电子书是比较麻烦的,笔者认为主要原因有两点:

  • 因为你要严格按照上述所说的文件目录结构的格式来整理你的文件,如果万一中间某个处弄错了,那么在 iPad 上就无法正常运行。像这种操作应该实现自动化生成文件目录结构,让开发者更加关注其实现。

  • 从上面这一条可以看出,调试起来是个坑,很难定位的自己是哪出错了。在程序上,调试只能以打印 Log 的方式进行,无法进行断点调试也是个痛点。

当然网上也有人写过一些工具来解决上述的问题。但今年,WWDC2018 苹果自家终于推出专门的模板来解决上述所提到的痛点。下面我们赶紧来看看如何使用该模板制作 Playground 电子书吧。

模板介绍

Swift Playgrounds 模板是一个帮助制作者调试、快速创建的一个 Xcode 工程,让制作者更加关注于内容的创建。

这个 Xcode 工程有三个不同的 Target 来帮助你创作属于你的 Playground 电子书:

swift_playground_template_target.png

PlaygroundBook Target

这个 Target 主要用于自动生成 Playground 电子书,解决了上述所说的第一个痛点

playground_book_target.png

通过 Xcode 目录可知,这个 Target 所有文件都在 PlaygroundBook 文件夹下,其中包含文章前所说的 Sources 和 PrivateResources(Resources) 文件夹,还有默认包含一个章节以及一个页面。

Book_Sources Target

book_sources_target.png

这个 Target 我们可以简单理解为把 Sources 源文件编译成一个静态库,供 LiveViewTestApp Target 使用,这里有个点需要注意,如果你创建了多个 Page,并且需要进行调试的时候要明确你要调试那个 LiveView,从而并进行 Debug 视图切换。

LiveViewTestApp Target

live_view_test_app_target.png

这个 Target 目的已经很明确了,就是针对 LiveView 进行调试的,解决了上述所说的第二个痛点。此处不再详述。

模板使用

我们先简单剖析模板的源码,上述已经解释了三个 Target 的作用,下面我们来看下,它们之间是怎么交互的。

在 Sources 文件夹中有两个源文件:

  • LiveViewController.swift

sources_code_review_liveviewcontoller.png

这里需要注意的是 Swift 类被起了个别名 @objc(BookSourcesLiveViewController) 暴露给 Objective-C。

  • LiveViewSupport.swift

sources_code_review_liveviewsupport.png

这个源文件仅仅声明了一个 public 方法,并返回 Storyboard 中的一个控制器实例。

初学者可能会觉得疑惑LiveViewController 貌似没有遵循 PlaygroundLiveViewable 协议,怎么没有报编译错误?原因是在 PlaygroundSupport 组件中就给 UIViewController 加了个扩展,并遵循其协议。

下面我们来看看是如何在 Pages 中的 LiveView 引用的:

pages_code_liveview.png

有些童鞋这此处又会有一个疑惑,那就是 instantiateLiveView 在 Pages 是怎么识别的?回顾上文,你会找出答案。(Sources 文件夹中的源文件属于 Global files,并且该方法还是 public

我们再来看看 LiveViewTestApp Target 中的 AppDelegate.swift:

liveview_test_app_code_review.png

setUpLiveView 方法是直接调用 Book_Sources Target 生成的静态库调用其方法实现的,当有多个不同的 LiveView 进行调试时,此处要记得更改。

至此,模板的原理及使用应该都差不多了。下面我们再回到这个 Session 的另一个主题:如何托管自己的订阅源并分享给他人?

如何把制作好的 Playground 电子书安装到 iPad?

这里有两种较为常用的方法:

  • AirDrop,没错,直接把 .playgroundbook 文件通过 AirDrop 丢给 iPad。

  • iCloud Drive(iCloud 云盘)

Swift Playgrounds 订阅 Feeds 格式

上文已经讲了很多关于制作 Playground 电子书的知识,现在开始我们要关注,如果把制作的电子书分享给他人学习呢?

我们一般把一系列的 Playground 电子书相关资源托管至远端,并把其描述成一个 Feeds JSON 文件,然后 Swift Playgrounds 再通过解析其内容来达到订阅的目的。下面我们来了解一下该 JSON 的数据格式及结构。

{
    "title": "WWDC Photo Filters",
    "publisherName": "Holly and Grace",
    "feedIdentifier": "io.github.WWDCPhotoFilters",
    "contactURL": "mailto:example@apple.com", // 订阅发布者的联系方式
    "formatVersion": "1.0", //订阅 Feed 发布版本号
    "documents": [
        {
            "title": "Image Transitions",
            "overviewSubtitle": "CIFilters in the Transition Category.",
            "detailSubtitle": "Filters in CICategoryTransition.",
            "description": "Learn some ways to use Core Image to transition between images.",
            "contentIdentifier": "io.github.WWDCPhotoFilters.imageTransitions",
            "contentVersion": "1.0",
            "url": "https://WWDCPhotoFilters.github.io/ImageTransitions/ImageTransitions.playgroundbook.zip",
            "publishedDate": "2018-05-18T12:00:00+00:00",
            "lastUpdatedDate": "2018-05-18T12:00:00+00:00",
            "thumbnailURL": "ImageTransitions/thumbnail.png",
            "bannerImageURL": "ImageTransitions/bannerImage.png",
            "additionalInformation": [
                {
                    "name": "Languages",
                    "value": "English"
                }
            ],
            "previewImageURLs": []
        }
    ]
}

订阅 Feeds JSON 数据分两部分:

1.订阅 Feed 相关信息

  • title:订阅 Feed 的标题

subscription_title.png

  • publisherName:订阅发布者的名称

subscription_publisher_name.png

  • feedIdentifier:订阅 Feed 的唯一ID,一般直接用翻转域名来标识

2.document:即电子书相关信息

  • title:电子书的标题

  • overviewSubtitle:电子书概览标题

subscription_document_title.png

  • detailSubtitle:电子书更加具体的标题

subscription_document_subtitle.png

  • description:电子书相关信息的一些描述

subscription_document_description.png

  • contentIdentifier: 电子书的唯一ID,一般是在 feedIdentifier 的基础上拼接电子书的名称

  • contentVersion:电子书发布版本号

  • thumbnailURL:电子书 icon

subscription_document_thumbnail1.png

subscription_document_thumbnail2.png

  • bannerImageURL:电子书 banner,用于展示及推广相关视觉图

subscription_document_banner.png

  • additionalInformation:额外信息,采用 Key-Value 的方式

  • previewImageURLs:电子书预览图

subscription_document_preview.png

字段比较多,建议刷下官方文档有点印象

托管你的订阅源

了解了订阅 Feeds JSON 数据格式后,那么如何托管自己的订阅源并分享给他人,我们可以把一系列 Playground 电子书的所有资源托管至第三方,创建自己的 JSON 文件,生成自己的订阅链接,然后再通过 Safari 进行订阅。

下面我们以 GitHub Page 为例,来展示如果托管自己的订阅源:

subscription_web_hosts.png

1.首先创建一个属于自己的 GitHub Page。不知道创建 GitHub Page 的童鞋请移步至官方文档

subscription_create_own_repo (1).png

2.然后在仓库设置中配置好 GitHub Page。

subscription_create_own_repo_github_pages.png

3.创建 Feeds JSON 文件,为了举例笔者直接用 WWDC 上演示的 JSON 链接

4.在仓库中新建一个 index.html 或 README.md 文件,并把自己的订阅链接放入其中。

<a href="https://developer.apple.com/ul/sp0?url=https://WWDCPhotoFilters.github.io/feed.json"> Subscribe  
</a>

5.都配置好后,我们的订阅源已经托管至GitHub了,现在可以分享给其他小伙伴了,如何分享呢?

订阅电子书 Feeds 的方式有两种:

  • 通过装有 Swift Playgrounds 应用的 iPad,使用 Safari 访问 GitHub Page,即 http://tingxins.com/Playground.github.io 。 点击之前已配置好的链接进行访问,即点击 Subscribe,然后系统会自动调取 Swift Playgrounds 应用。

subscription_create_own_repo_github_pages_link.png

  • 直接在 Swift Playgrounds 应用内进行收到添加订阅链接的方式进行订阅。

manual_subscription_indicator.jpg

小结

本文针对 Session 主要总结了两个主要点并通过举例加深读者对其印象:

  • 如何利用 WWDC2018 新的模板工具制作出属于自己的 Playground Book

  • 如何托管自己的订阅源并分享给他人

感兴趣的童鞋还可以看看往期的 WWDC:

WWDC 2018 - Session 402 Getting the Most out of Playgrounds in Xcode

WWDC 2018 - Session 418 Source Control Workflows in Xcode

WWDC 2017 - Session 410 Localizing Content for Swift Playgrounds

WWDC 2017 - Session 416 Teaching with Swift Playgrounds

WWDC 2017 - Session 408 What’s New in Swift Playgrounds

本文总阅读量