苦于无法手把手教小伙伴学 Flutter?一文带你玩转 DartPad 之 Workshop 制作

大家好,我是每天只有 24 小时但能卷 25 小时的 Alex。

前言

2022 年度 Google I/O 大会已至,在今年的 I/O 准备流程中, Flutter 团队面向 insiders 征集了 Workshop 选题, 最终我制作的 Implement LazyIndexedStack DartPad Workshop (需要外网) 荣幸的成为了入选作品之一, 展示在 I/O Adventure 的 Flutter 专场中供大家浏览和学习。

Workshop 展台实现 LazyIndexedStack
Workshop 展台实现 LazyIndexedStack

借此机会,向大家介绍 DartPad 的新玩法:Workshop。

Workshop 是什么?

如果你未曾听过或不了解什么是 DartPad,你可以访问 dartpad.cn 在 Web 页面上体验 Dart 和 Flutter。

Dart 2.13 (Flutter 2.2) 起, DartPad 新增了 Workshop 的支持。 Workshop 是一种全新的 DartPad 内容交互方式。 以往的 DartPad 内容基于 GitHub Gist 分享, 仅能分享一份代码,并且没有引导式的步骤和交互。 而 Workshop 是一套可交互、多步骤、引导式且基于 Web Server 的内容架构。 作者可以自定义 workshop 名称,定义每一个步骤的内容和解法, 使用 Markdown 展示步骤的介绍,最后使用多种方式托管 workshop 源文件以进行使用。

DartPad Workshop 架构

从头开始,本文将一步步带你学习从使用、创建、撰写到发布 workshop 的所有必要步骤, 成为 Dart/Flutter 教学大师!

Workshop 怎么玩?

工欲善其事,必先利其器。 想要写好一个 workshop,首先要了解 workshop 最终会呈现什么效果。

此处推荐浏览官方的 Sliver Workshop,简单把玩一番。

Flutter Sliver Workshop

从上图中我们不难看出,整个 workshop 被一分为三, 左侧为介绍内容块,同时可以进行步骤的切换;右上为代码编辑器, 可以点击 Run 运行代码;右下则为界面输出、控制台以及文档界面。

将鼠标放在左侧下方的 Step 1 上,将出现步骤切换列表,展示出所有的可切换步骤。

Workshop 步骤切换

当某个步骤包含解答(有 solution.darthas_solutiontrue)时, 左侧介绍内容块的右下角将显示 Show Solution 按钮, 点击后右侧的代码内容将使用解答代码完整替换。

Workshop 显示解答

整个过程中,无论是 workshop 为你准备好的代码, 还是点击 Show Solution 替换的解答代码, 都可以在右侧的代码编辑器中进行修改并运行

Workshop 怎么写?

新建一个目录,名字随意(例如 my_workshop),在 workshop 完成时,结构应当如下:

my_workshop/
|---meta.yaml          # 元数据声明文件
|---step_01/           # 步骤目录(任意名称)
   |---instructions.md    # 步骤介绍 Markdown 文档
   |---snippet.dart       # 代码文件
   |---solution.dart      # 解答文件(可选)
|---step_02/
   |---instructions.md
   |---snippet.dart

meta.yml

在元数据声明文件中,你需要声明如下结构的内容:

name: My workshop      # Workshop 的名称
type: dart             # Workshop 的类型,可为 "dart" 或 "flutter"
steps:                 # 声明步骤
  - name: Step 1         # 步骤的名称
    directory: step_01   # 步骤对应的目录
    has_solution: true   # 步骤是否有解答
  - name: Step 2
    directory: step_02
    has_solution: false

如果你的某一个步骤需要开发者动手修改,最后提供一份解答, 你可以将 has_solution 设置为 true 并且创建 solution.dart 文件进行交互。

每个步骤包含的内容大同小异,但在开始写一个具体的步骤前, 我们还有一项有利于我们开发 Workshop 的操作, 那就是 在项目的同级目录新建一个 pubspec.yamlpubspec.yaml 有助于 CLI/IDE 识别并配置你的 Dart/Flutter 项目。 如此你便可以像正常的 Dart/Flutter 项目一样编写你的 workshop。

步骤内容

instructions.md

instructions.md 是每一个步骤对应的介绍文档,支持以 Markdown 的形式编写。 实测在 DartPad 环境中可以支持 <iframe> 标签进行嵌入, 你可以嵌入视频或者其他交互式内容来辅助你的介绍。 (参考:instructions.md

步骤介绍

snippet.dart

该文件是每个步骤对应的必需 Dart 代码片段, 在切换步骤时对应的代码将直接替换到代码编辑器内。 代码文件有时候并不需要开发者关注所有的内容, 在这样的情况,推荐在文件中使用 TODO 标记需要开发者修改的内容。 (参考:snippet.dart

TODO 标记代码

solution.dart

该文件是可选的步骤解答。在使用它前,你需要在 meta.yml 中把对应步骤的 has_solution 设置为 true 方可生效。 它和 snippet.dart 格式基本相同, 在前文中我们介绍到,点击 Show Solution 按钮, 可以将已有的代码替换为你编写的解答内容。 当你想教会开发者一种特定的实现方式时,解法文件可以发挥它的作用。 但如果对应的步骤是开放性的体验尝试,就无需提供特定的解法。

Workshop 放到哪?

Workshop 支持以 HTTP 服务器的方式被托管。 总的来说有三种主要的托管方式:

  • 使用你的个人服务器进行部署,也可以托管在本地或局域网给同事或者学生分享。 此时的访问网址应当是:https://dartpad.cn/workshops.html?webserver=https://www.example.com/my_workshop
  • 使用 Web 应用服务商提供的服务,类似于 Firebase、web.app、Web+、Webify 等 PaaS 服务; 此时的访问网址应当是:https://dartpad.cn/workshops.html?webserver=https://your_app.web.app/path/to/my_workshop
  • 直接将代码上传至 GitHub,通过 GitHub API 或者 Raw user content 进行访问。 此时的访问网址可以是:https://dartpad.cn/workshops.html?webserver=https://raw.githubusercontent.com/your_name/my_workshop 也可以是:https://dartpad.cn/workshops.html?gh_owner=your_name&gh_repo=my_workshop

体验 Workshops

在 Google I/O 大会期间,I/O Adventure 的 Flutter 分区提供了 15 个由 Flutter GDE 制作的 workshops,欢迎大家前往体验!

DartPad Workshop 展区

你也可以查看 这篇文章 了解每个 workshop 的内容。

小结

通过以上的丝滑小连招,你的 workshop 就已经准备好分享给其他人进行学习了。 自 2019 年开始入行 Flutter 以来,我已经通过 GitHub Gist 的方式分享了 共计 25 份 Dart/Flutter 代码片段。 而从现在开始,第一份个人 workshop 的出炉代表着全新教学路线的探索已经展开。 希望有兴趣的小伙伴能善用 workshop,更好地教会有兴趣学习 Dart/Flutter 的开发者。

最后,如果你有任何与 Flutter 有关的问题,欢迎在评论区与我沟通, 也欢迎大家 加入最活跃的 Flutter QQ 群 (FlutterCandies🍭) 持续学习 Flutter 的相关知识。

alex-flutter