企业官网建设流程全解析

• 编程语言
• 编译器
• 语言运行时

CSS 单位（如px、em、vw）是样式系统中最基础的元数据之一。本篇文章以 apps/imba.io/scripts/mdn-data/css/units.md 为核心，结合仓库中实际落盘的 units.json 数据文件、units.schema.json 校验规则与 definitions.json 模块清单，完整解析这套 CSS 单位元数据的数据结构、字段语义与校验方式。读完本文，你将掌握如何阅读、校验和扩展这套单位数据，并理解它在 Imba 官网文档工具链中的位置与用途。

一、这套数据是什么、在仓库中的位置

units.md所描述的，是 MDN 开源数据仓库中css/units.json这一数据文件的格式规范。imba.io 官网项目在 apps/imba.io/scripts/mdn-data/ 目录下维护了整套 MDN CSS 数据的副本，其中 CSS 部分包括六类数据文件，全部位于 apps/imba.io/scripts/mdn-data/css/：

从该目录下的 readme.md 可以看出，这些文件是对应 MDN Web 文档中 CSS 语言特性（at-rules、properties、selectors、syntaxes、types、units）的结构化描述。units 数据集记录了 CSS 单位本身（em、px等），其大部分单位定义来源于 CSS Values and Units 规范。文档的核心信息是：每个单位记录由groups（所属模块组）与status（标准化状态）两个必填字段构成。

二、units.json：单位清单与统计概览

打开 units.json，可以看到当前仓库实际收录了 28 个 CSS 单位，全部以单位名称为键（如ch、px、deg），值为记录对象：

{ "ch": { "groups": ["CSS Units", "CSS Lengths"], "status": "standard" }, "px": { "groups": ["CSS Units", "CSS Lengths"], "status": "standard" }, "fr": { "groups": ["CSS Units", "CSS Flexible Lengths", "CSS Grid Layout"], "status": "standard" } }

完整的 28 个单位清单为：ch、cm、deg、dpcm、dpi、dppx、em、ex、fr、grad、Hz、in、kHz、mm、ms、pc、pt、px、Q、rad、rem、s、turn、vh、vmax、vmin、vw、x。

按groups字段聚合统计，当前数据集覆盖的模块分布如下：

• CSS Lengths（长度，15 个）：ch、cm、em、ex、in、mm、pc、pt、px、Q、rem、vh、vmax、vmin、vw
• CSS Angles（角度，4 个）：deg、grad、rad、turn
• CSS Resolutions（分辨率，4 个）：dpcm、dpi、dppx、x
• CSS Frequencies（频率，2 个）：Hz、kHz
• CSS Times（时间，2 个）：ms、s
• CSS Flexible Lengths + CSS Grid Layout（弹性长度/网格，1 个）：fr

值得注意的是，fr是唯一同时归属于两个业务模块（CSS Flexible Lengths 与 CSS Grid Layout）的单位，这正体现了groups数组支持"一个单位可同时属于多个模块"的设计。

三、记录结构：groups 与 status 两个必填字段

units.md明确指出，每个单位记录包含两个均必填的属性，缺一不可：

3.1groups（字符串数组）：单位所属的 CSS 模块

CSS 规范按模块组织，例如 "CSS Units"（CSS 单位）或 "CSS Lengths"（CSS 长度）。MDN 也以同样的分组方式组织特性，因此groups中应包含定义该单位的一个或多个模块名。

• 类型：array of strings
• 约束：至少包含 1 个模块名，且不能有重复项
• 约定：所有单位都必然首先属于 "CSS Units" 组，再按语义归入具体模块组

以ch为例，它同时被标注为 "CSS Units" 与 "CSS Lengths" 两个模块的成员；deg则属于 "CSS Units" 与 "CSS Angles"。

3.2status（枚举字符串）：单位的标准化状态

status是一个枚举字段，取值只能是以下三者之一，用于标识该特性的标准化进度：

当前 units.json 中的 28 个单位状态全部为standard，即数据集内不包含任何非标准或实验性的单位。

四、groups 的取值边界：definitions.json 中的模块清单

groups并不是任意字符串，其取值受到 definitions.json 中groupList枚举的严格约束。该文件定义了一份完整的 CSS 模块名清单，共约 70 个条目，涵盖：

• 基础模块：Basic Selectors、CSS Color、CSS Text、CSS Fonts、CSS Box Model、CSS Backgrounds and Borders 等
• 布局模块：CSS Grid Layout、CSS Flexible Box Layout、CSS Box Alignment、CSS Display、CSS Positioning 等
• 特效与动画：CSS Animations、CSS Transitions、CSS Transforms、Compositing and Blending、Filter Effects 等
• 单位相关：CSS Units、CSS Lengths、CSS Angles、CSS Resolutions、CSS Frequencies、CSS Times、CSS Flexible Lengths
• 其他：Media Queries、CSS Variables、CSS Houdini、MathML 以及 Microsoft / Mozilla / WebKit 扩展组等

这意味着，任何单位记录中groups内出现的模块名，都必须能在groupList中找到。units.json 中实际用到的 8 个模块组（CSS Units、CSS Lengths、CSS Angles、CSS Resolutions、CSS Frequencies、CSS Times、CSS Flexible Lengths、CSS Grid Layout）均是该枚举的有效成员。

五、JSON Schema 校验：units.schema.json 的规则解读

units.schema.json 是这套数据的机器可读校验规则，与文档描述一一对应：

{ "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "groups": { "type": "array", "minitems": 1, "uniqueItems": true, "items": { "$ref": "definitions.json#/groupList" } }, "status": { "enum": ["standard", "nonstandard", "experimental"] } }, "required": ["groups", "status"] } }

逐条解读其校验约束：

• 顶层为对象：units.json整体是一个以单位名为键的对象。
• additionalProperties: false：单位记录内不允许出现未知字段，数据必须保持纯净，只有groups与status两个字段。
• groups约束：必须是数组（type: array），至少 1 个元素（minitems: 1），元素不可重复（uniqueItems: true），且每个元素通过$ref引用definitions.json#/groupList的枚举，即必须属于既定的模块名清单。
• status约束：必须是standard、nonstandard、experimental三者之一。
• required: ["groups", "status"]：两个字段均必填，缺任一字段即校验失败。

这套 schema 与同目录下其他数据文件的 schema 保持一致的风格。作为参照，types.schema.json（数据类型）在相同的groups+status必填结构基础上，额外允许一个可选的mdn_url字符串字段（须以https://developer.mozilla.org/docs/Web/CSS/开头）；而 units 数据目前不包含 URL 字段，这从侧面说明单位数据更侧重于"分类 + 状态"的轻量描述。

六、在项目中的消费方式与配套结构

6.1 统一入口：index.js

apps/imba.io/scripts/mdn-data/css/index.js 是这套 CSS 数据的统一导出入口：

module.exports = { atRules: require('./at-rules'), selectors: require('./selectors'), types: require('./types'), properties: require('./properties'), syntaxes: require('./syntaxes'), units: require('./units'), }

因此，在脚本中可以直接以require('./mdn-data/css').units的方式拿到全部单位记录，再结合 schema 做数据完整性校验，或按groups字段过滤出某个模块下的单位集合（例如筛选出所有属于 "CSS Lengths" 的单位用于渲染文档导航）。

6.2 数据文件与站点构建的关系

从目录结构看，mdn-data位于 apps/imba.io/scripts/ 下，与 build-content.imba、build-api-docs.imba等站点构建脚本同级，是 imba.io 官网内容生成流程中使用的静态数据资产。同一mdn-data目录下还维护了api/子目录（如inheritance.json及其 schema），用于描述 Web API 的继承关系，说明这类"数据 + schema + 说明文档"三件套是该项目沉淀外部 Web 平台数据的统一模式。

6.3 与 Imba 样式系统的间接关联

Imba 的样式系统与 CSS 单位存在天然联系：在 packages/imba/typings/styles.generated.d.ts 中，大量样式属性的注释直接引用 MDN 文档链接（如width、position、margin等属性的[MDN Reference]注释），说明 Imba 的样式类型体系以 CSS 规范为事实来源。可以推断，官网这套 mdn-data 数据正是为了支撑站点中 CSS 相关的文档渲染、类型提示与 API 参考内容而 vendored 进仓库的。

七、实践要点小结

1. 数据读取：以单位名为键遍历 units.json，每个值必然含groups（数组）与status（枚举）两个字段。
2. 数据校验：使用 units.schema.json 配合 JSON Schema 校验器（如ajv）验证数据完整性；additionalProperties: false意味着任何多余字段都会导致校验失败。
3. 新增单位：若需录入新单位，必须同时满足三条约束——groups中的模块名来自 definitions.json 的groupList枚举、status取三个合法值之一、两个字段缺一不可。
4. 语义区分：standard/nonstandard/experimental三态直接决定了文档中该单位能否被推荐使用，非标准或实验性单位应在 UI 上给出对应提示。

这套规范的价值在于：它以极简的两字段结构，把 CSS 单位的"分类归属"与"标准化状态"两种关键信息机器可读化，再通过 JSON Schema 保证数据质量，为文档站、类型生成器等下游消费方提供了稳定可靠的数据契约。

• 编程语言
• 编译器
• 语言运行时