Flutter Web 引擎编码规范精读：web_ui 目录约定与 CanvasKit/Skwasm 术语体系

本文基于 Flutter Web 引擎源码目录下的规范文档 CODE_CONVENTIONS.md（其适用范围为 web_ui 目录）展开，系统讲解 Flutter Web 引擎在命名、目录结构与术语使用上的专属约定：从 CanvasKit 渲染器的 canvaskit 目录与 canvaskit_api.dart 绑定层，到 Ck 前缀的 Skia 封装命名规则，再到 CanvasKit 与 Skwasm 两个渲染后端共享的 Semantics（无障碍）与文本编辑模块，以及公共小工具的去目录化策略。读完本文，你将掌握一套可直接指导 Flutter Web 引擎二次开发与代码评审的规范地图，能准确区分"Flutter 全局风格指南"与"Web 引擎局部约定"各自的管辖范围。

一、文档定位：它是 Web 引擎特有的命名与结构约定，不是一份代码风格指南

Web 引擎源码数量庞大，且同时承载 CanvasKit、Skwasm 两套渲染后端，命名混乱会显著抬高检索与维护成本。为此 CODE_CONVENTIONS.md 专门规定了仅适用于 web_ui 目录的命名与结构约定，其开篇即明确了两点边界：

• 本文档不是代码风格指南（"This is not a code style guide"）。缩进、括号、注释格式等通用风格问题，应遵循 Flutter 仓库统一的风格文档 Style-guide-for-Flutter-repo.md；
• 本文档约定不适用于 web_ui 目录之外的代码。换言之，Flutter 框架层、引擎其他模块依然以全局风格指南为准。

这种"全局风格 + 局部约定"的双层架构，是大型代码库处理特例时的典型做法：Web 引擎因为要与 Skia / CanvasKit 的 JavaScript API 直接对接，产生了大量"反 Flutter 惯例"的特殊写法，因此必须用局部文档为这些例外提供依据，避免评审者误判。

web_ui 目录本身是 Flutter Web 引擎源码的入口，位于 engine/src/flutter/lib/web_ui，其中 lib/src/engine 是其核心实现区，从目录清单可以看到 backend/、canvaskit/、skwasm/、semantics/、text_editing/、compositing/、platform_views/ 等职能划分清晰的子目录，本文档所讲的结构约定正是这套组织方式的"总纲"。

二、CanvasKit 渲染器：目录、绑定、命名三层约定

CanvasKit 是 Flutter Web 的主要渲染后端，Skia 被编译为 WebAssembly 后以 JavaScript API（CanvasKit）暴露给引擎层。围绕这套"桥接代码"，规范文档给出了四个维度的硬性约定。

2.1 代码归属：所有 CanvasKit 专属代码收敛于单一目录

All code specific to the CanvasKit renderer lives in lib/src/engine/canvaskit.

所有 CanvasKit 渲染器专属代码必须位于 lib/src/engine/canvaskit 目录（仓库实际路径为 lib/src/engine/canvaskit）。仓库中该目录下的真实文件可以直观佐证其收敛程度，例如：

• canvaskit_api.dart —— CanvasKit JS API 的唯一 Dart 绑定入口；
• canvas.dart、surface.dart、picture.dart、picture_recorder.dart —— 绘制面与录制；
• painting.dart、color_filter.dart、image_filter.dart、mask_filter.dart、shader.dart、fragment_shader.dart —— 绘制状态与特效；
• image.dart、animated_image.dart、text.dart、fonts.dart、web_paragraph_painter.dart —— 图像与文本；
• path.dart、path_metrics.dart、vertices.dart —— 几何；
• renderer.dart、native_memory.dart、util.dart —— 渲染器装配与辅助。

把渲染器专属逻辑限制在单一目录内，能保证后续引入 Skwasm 等新后端时，不会出现"CanvasKit 逻辑散落各处"的交叉耦合，也让按渲染器筛选的单元测试（例如 felt test --renderer canvaskit）可以精确圈定受影响的文件。

2.2 绑定命名：精确复刻 CanvasKit JavaScript API 名称

CanvasKit bindings should use the exact names defined in CanvasKit's JavaScript API, even if it violates Flutter's style guide, such as function names that start with a capital letter (e.g. "MakeSkVertices").

这是全文最具"颠覆性"的一条约定：绑定层的 Dart 命名必须与 CanvasKit JS API 完全一致，即使它违反 Flutter 风格指南（典型如以大写字母开头的函数名 MakeSkVertices）。其根本原因是可检索性——当绑定名称与 Skia/C++ 侧名称一一对应时，开发者可以立刻在 Skia 源码中定位对应实现，跨语言追踪时无需再做一层"名称翻译"。

仓库中 canvaskit_api.dart 是该约定的直接载体，其第 82–96 行展示了从"外部声明到 Dart 友好封装"的标准模式：

@JS('MakeVertices')
external SkVertices _MakeVertices(
  SkVertexMode mode,
  JSFloat32Array positions,
  JSFloat32Array? textureCoordinates,
  JSUint32Array? colors,
  JSUint16Array? indices,
);
SkVertices MakeVertices(
  SkVertexMode mode,
  Float32List positions,
  Float32List? textureCoordinates,
  Uint32List? colors,
  Uint16List? indices,
) => _MakeVertices(mode, positions.toJS, textureCoordinates?.toJS, colors?.toJS, indices?.toJS);

可以看到：底层用 @JS('MakeVertices') 精确指向 CanvasKit 的真实导出名；私有声明 _MakeVertices 直接使用 JS 侧类型（JSFloat32Array 等）；对外再提供同名的、接收 Dart 原生类型（Float32List 等）的封装方法。同一文件内还大量存在这种大写字母开头的绑定，例如 MakeWebGLCanvasSurface、MakeSurface、MakeBlur（第 110–111、961 行附近），均严格遵循"名称与 Skia/CanvasKit 一致"原则。

2.3 拼写约定：目录与变量各走各路

规范对 "CanvasKit" 一词在不同上下文中的拼写给出了区分性要求：

• 文件与目录一律使用全小写无标点的 canvaskit，禁止 canvasKit、canvas-kit、canvas_kit 等变体，这与 Skia 自身的命名习惯保持一致。仓库 lib/src/engine/canvaskit 目录本身即为实例；
• 变量、函数、方法、类名则使用驼峰式 canvasKit / CanvasKit（即"目录名全小写，标识符驼峰"的双轨制）。

这条看似细碎的规则其实解决了真实痛点：代码里会频繁引用 canvaskit（路径/目录）、canvasKit（全局绑定实例）、CanvasKit（类型名）三种形态，若不固定拼写规则，全局检索时很容易漏掉变体。

2.4 文档称呼：必须写作 "CanvasKit renderer"

In documentation ... refer to Flutter's usage of CanvasKit as "CanvasKit renderer"

在文档注释、flutter.dev 网站、Markdown 文件、博客等面向人的描述中，必须把"Flutter 内嵌使用的 CanvasKit"写作 CanvasKit renderer，避免与"作为独立库的 CanvasKit"混淆——后者可以脱离 Flutter 单独使用。这个术语区分的意义在于：CanvasKit 本身是通用图形库，而 Flutter Web 只是它的一个使用方，文档中清晰区分可以防止读者误以为相关接口是 Flutter 通用能力。

2.5 封装类命名：用 Ck 前缀替换 Sk 前缀

Classes that wrap CanvasKit classes should replace the Sk class prefix with Ck (which stands for "CanvasKit"), e.g. CkPaint wraps SkPaint, CkImage wraps SkImage.

对于封装 CanvasKit（Skia）对象的 Dart 类，命名规则是把 Skia 的 Sk 类前缀替换为 Ck（"CanvasKit"的缩写）：CkPaint 封装 SkPaint、CkImage 封装 SkImage。这一约定使读者能一眼看出"Dart 类 ⇄ Skia 对象"的对应关系，同时避免与 Sk 前缀的原始对象混淆。

仓库中的封装类高度一致地践行了该规则：

• painting.dart 第 13 行 class CkPaint implements ui.Paint 实现 Flutter 的 ui.Paint 接口，内部通过 toSkPaint()（第 20–30 行）将状态逐项同步到真正的 SkPaint（skPaint.setAntiAlias(...)、skPaint.setBlendMode(...)、skPaint.setColorInt(...) 等），并负责 SkPaint 原生对象的生命周期管理；
• image.dart 第 8 行 class CkImageDelegate implements BackendImage，内部持有 SkImage skImage，其 width/height 直接委托给 skImage.width()/skImage.height()，dispose() 则调用 skImage.delete() 释放 Skia 侧原生内存；
• vertices.dart 第 12 行 class CkVertices implements BackendVertices，工厂构造函数会把 Dart 的 VertexMode、Float32List 坐标等转换成 Skia 类型；
• 同理还有 CkShader、CkImageFilter、CkColorFilter 等，均可在 shader.dart、image_filter.dart 等文件中找到对应类。

值得注意的是，这些 Ck* 类通常实现 Backend* 抽象接口（如 BackendImage、BackendVertices），说明 Flutter Web 引擎通过"接口 + 后端实现"的设计，为 CanvasKit 与 Skwasm 两套渲染后端提供统一的抽象层——这正是下一节"共享代码"约定得以成立的结构前提。

三、Semantics（无障碍）模块：跨渲染器共享的代码归属

The semantics (accessibility) code is shared between CanvasKit and Skwasm. All semantics code lives in lib/src/engine/semantics.

Semantics（语义/无障碍）代码在 CanvasKit 与 Skwasm 两个渲染后端之间共享，因此统一收口在 lib/src/engine/semantics 目录。仓库中该目录的文件按"无障碍角色"组织，覆盖了 Web 无障碍语义树的常见角色，例如：

• 基础角色：button（按钮）类对应文件、checkbox（复选框）类、radio（单选）、link（链接）、image（图像）、header/heading（标题）、list（列表）、table（表格）、tabs（标签页）、menus（菜单）等；
• 行为语义：expandable（可展开，如手风琴）、scrollable（可滚动区域）、focusable（可聚焦）、live_region（实时区域，供屏幕阅读器播报动态内容）、progress_bar（进度条）等；
• 表单语义：form、checkable、requirable、incrementable、text_field 等；
• 聚合逻辑：semantics.dart、semantics_helper.dart、accessibility.dart。

从 semantics/semantics.dart 中定义的 EngineSemantics、EngineSemanticsOwner 等核心类可以看出，无障碍语义树的创建、更新与 DOM 桥接都由这一共享模块承担。将这类代码放在公共目录而非某个渲染器目录下，避免了同一套无障碍逻辑在 CanvasKit 与 Skwasm 中重复实现、进而产生行为漂移的风险。

四、文本编辑模块：同样遵循"共享代码归公共目录"

Text editing code is shared between CanvasKit and Skwasm, and it lives in lib/src/engine/text_editing.

与 Semantics 类似，文本编辑代码也是两个渲染后端共享的，统一位于 lib/src/engine/text_editing 目录。仓库中该目录包含：

• text_editing.dart —— 文本编辑状态与逻辑主体；
• composition_aware_mixin.dart —— 处理输入法组合（composition）状态的 mixin；
• input_type.dart、input_action.dart、autofill_hint.dart —— 移动端/浏览器键盘输入的类型、动作键与自动填充语义；
• text_capitalization.dart —— 首字母自动大写策略。

这些能力与浏览器 contenteditable、输入法（IME）、自动填充的交互密切相关，且与具体渲染后端无关，因此放在共享目录，两个渲染器均可复用。

综合第三、四节可以得到一个清晰的目录组织心智模型：

• lib/src/engine/canvaskit/ 与 lib/src/engine/skwasm/（仓库中存在于 lib/src/engine/skwasm，含 skwasm_impl/ 等实现文件）存放渲染后端专属代码；
• lib/src/engine/semantics/ 与 lib/src/engine/text_editing/ 存放跨后端共享代码；
• 新增功能时，先判断"是否与渲染器绑定"，再决定落入哪个目录，这是评审时最常用的判断依据。

五、公共小工具：无需独立目录，直接落在 lib/src/engine 根下

Small common utilities do not need dedicated directories. It is OK to put all such utilities in lib/src/engine

对于"体积小、用途通用"的公共工具函数，规范明确不要求为其开辟专属目录，直接放置在 lib/src/engine 根目录即可，文档给出的范例是 alarm_clock.dart。

仓库中该文件确实直接存在于 lib/src/engine/alarm_clock.dart。这一约定旨在避免"目录碎片化"：Web 引擎中大量十几行的工具函数，若每个都独立建目录反而会淹没真正有规模的核心模块。与它同处根目录的 util.dart、browser_detection.dart、font_change_util.dart、safe_browser_api.dart、image_format_detector.dart 等文件，也都属于这种"通用辅助"定位，与之形成互补的是各职能模块（pointer_binding/、platform_views/、navigation/、keyboard_binding.dart 等）依然保持各自目录。

六、规范速查表与实践建议

6.1 约定速查

关注点	约定	仓库依据
CanvasKit 专属代码归属	统一位于 lib/src/engine/canvaskit	lib/src/engine/canvaskit
CanvasKit JS 绑定命名	与 CanvasKit/Skia JS API 完全一致，即使大写开头	canvaskit_api.dart 中 MakeVertices、MakeWebGLCanvasSurface 等
文件/目录拼写	一律小写 canvaskit，无分隔符	目录名 canvaskit
标识符拼写	驼峰 canvasKit / CanvasKit	CkPaint、CkImage 等
文档描述用词	统一称 "CanvasKit renderer"	本文档及仓库说明文字
Skia 封装类前缀	Sk → Ck，如 CkPaint 包 SkPaint	painting.dart、image.dart
Semantics 代码	共享，位于 lib/src/engine/semantics	lib/src/engine/semantics
文本编辑代码	共享，位于 lib/src/engine/text_editing	lib/src/engine/text_editing
公共小工具	直接放入 lib/src/engine 根目录	alarm_clock.dart、util.dart
通用代码风格	遵循仓库全局风格指南	Style-guide-for-Flutter-repo.md
约定适用范围	仅 web_ui 目录	本文档开篇声明

6.2 给代码贡献者的三条实操建议

1. 先判断"风格"还是"约定"再动手：涉及缩进、注释、格式化类问题，参考全局风格指南；涉及 CanvasKit/Semantics/文本编辑等目录归属与命名问题，以 CODE_CONVENTIONS.md 为准，评审时不要用 Flutter 通用风格去否定绑定层的大写函数名。
2. 封装 Skia 对象必用 Ck 前缀并管好生命周期：新建 SkXxx 的 Dart 封装时，类名取 CkXxx，内部持有原始对象并在 dispose() 中调用 xxx.delete()，可参照 CkImageDelegate 的实现模式（见 image.dart）。
3. 新代码先对号入座再落盘：先确认功能是渲染后端专属（进 canvaskit/ 或 skwasm/）还是跨后端共享（进 semantics/、text_editing/ 或 lib/src/engine 根目录），避免复制式实现造成 CanvasKit 与 Skwasm 行为不一致。

6.3 关联阅读

• 若需了解 Web 引擎的构建与测试工具链，可阅读 web_ui 目录 README，其中介绍了 felt 工具的 build / test 子命令、--renderer canvaskit|skwasm 等筛选参数，以及 --local-web-sdk=wasm_release 的本地调试方式——这些命令中的 canvaskit、skwasm 正是本文命名约定的直接应用场景。
• 若需对照各约定在框架层的落地位置，可继续浏览 lib/src/engine 的完整目录结构，观察"渲染器专属 / 跨渲染器共享 / 公共工具"三种目录形态在同一层级下的共存关系。