Prettier 是一款开箱即用的代码格式化工具,主要特点是配置简单、便于集成、支持扩展。Prettier 原本聚焦于 Web 开发领域,由于表现优秀,社区也利用其扩展机制支持了 Java、PostgreSQL 等语言的格式化。
无需赘言,开发团队借助 Prettier 让团队成员保持一致的代码风格(不完全等同于代码规范)非常有必要,毕竟代码虽然是机器运行的,但主要是人在阅读;而且强迫人接受一种他可能不喜欢的风格,自然不如让工具自动统一来的容易。
其他内容大家可以查看官方文档了解更多,此处不过多介绍了。
认识插件
Prettier 主要聚焦于 Web 开发领域,因此 JavaScript、CSS 和 HTML 是默认支持的,甚至 JSX 和 Vue 也是内置支持的。
但是显然,假如你发明了一种全新的 DSL,Prettier 是不认的。那怎么办?写一款 插件!
所以,插件就是让 Prettier 能够支持你自己的编程语言的一种方式。本质上,它就是一个 普通的 JavaScript Module,暴露以下 5 个模块:
诸位明鉴,下文代码是以 TypeScript 写就的。
// index.ts import { SupportLanguage, Parser, Printer, SupportOption, ParserOptions } from 'prettier'; // 支持的语言列表 export const languages: Partial<SupportLanguage>[]; // 每个语言对应的 parser export const parsers: Record<string, Parser>; // 核心的格式化逻辑 export const printers: Record<string, Printer>; // 可选,插件的自定义配置项,此处 PluginOptions 需自行定义 export const options: Record<keyof PluginOptions, SupportOption>; // 可选,默认配置项 export const defaultOptions: Partial<ParserOptions>; 复制代码
写一个小程序 AXML 插件吧
阿里小程序(钉钉小程序、支付宝小程序等等)的上层 DSL 早已统一,但是一直都没有 AXML 自动格式化工具。
Prettier 对 JS/TS 是内置支持的,
.acss
其实就是 CSS。
可能有人尝试过将 .axml
设置为 XML 文件类型来做格式化,但肯定效果不理想。因为无法格式化 AXML 文件中的 JS 表达式。
今天我们就写一个起码的 AXML 的 Prettier 插件吧。
languages
我们为小程序 AXML 这门语言命名为 axml
,其 parser 列表是 ['axml']
(a.1)。也就是说可以为它指定多个 parser,但通常一个就够了。我们就使用 axml
这个 parser(其定义见下文)。
parser
是将源代码解析为 AST 的工具。
// index.ts import { SupportLanguage } from 'prettier'; export const languages: Partial<SupportLanguage>[] = [ { name: 'axml', parsers: ['axml'], // (a.1) extensions: ['.axml'], // (a.2) }, ]; 复制代码
parsers
在 index.ts 中新增 export const parsers
。
// index.ts import { SupportLanguage, Parser } from 'prettier'; import parse from './parse'; // prettier 指定 `node` 参数为 any,因为不同 parser 返回的 node 类型不尽相同 function locStart(node: any): number { return node.startIndex; } function locEnd(node: any): number { return node.endIndex; } export const languages: Partial<SupportLanguage>[] = [ { name: 'axml', parsers: ['axml'], extensions: ['.axml'], }, ]; export const parsers: Record<string, Parser> = { // 注意此处的 key 必须要与 languages 的 parsers 对应 axml: { parse, // (b.1) locStart, locEnd, // 为 ast 格式命个名,后面会用到 astFormat: 'axml-ast', }, }; 复制代码
parse
(b.1)是一个函数,在揭开它的面纱之前,我们先要确定解析 AXML 的 parser。
类 XML 的 DSL 市面上有很多 parser,我们就和小程序官方实现保持一致,使用 htmlparser2 来解析 AXML。所以 parse
(b.1)的定义如下:
// parse.ts import { parseDOM } from 'htmlparser2'; import { Node } from 'domhandler'; export default function parse(text: string): Node[] { const dom = parseDOM(text, { xmlMode: true, withStartIndices: true, withEndIndices: true, }); return dom; } 复制代码
htmlparser2 解析出来的 AST 相对简单,可以查看 这里 感受一下。
这里实际上还有一个棘手的问题,AXML 中的“无值属性”(如:
<view someAttr />
)其实是模仿了 JSX 的语义,即”布尔属性“(<view someAttr />
等价于<view someAttr={true} />
(JSX 语法)),但在 XML 以及 htmlparser2 这个 parser 中,它被解析为<view someAttr="" />
。这个需要我们特殊处理。
接下来是核心逻辑了。
printers
// index.ts import { SupportLanguage, Parser, Printer } from 'prettier'; import parse from './parse'; import print from './print'; import embed from './embed'; // ... 省略 export const printers: Record<string, Printer> = { // 对应 parsers 中的 astFormat 'axml-ast': { print, // (c.1) embed, // (c.2) }, }; 复制代码
print
(c.1)函数负责目标语言源代码本身的格式化逻辑,embed
(c.2)函数则用来处理目标语言当中内嵌的其他语言的格式化。
对于小程序 AXML 来说,htmlparser2 解析出来的 AST 只有以下 3 种类型(node.type
):
-
tag
- 标签,<view></view>
等等 -
text
- 标签内的文本 -
comment
- 注释,<!-- -->
,和 HTML 注释格式一致
在 print
(c.1)中:
// print.ts import { FastPath, Doc, ParserOptions, doc } from 'prettier'; const { concat } = doc.builders; export default function print( path: FastPath, _options: ParserOptions, _print: (path: FastPath) => Doc // (c.3) ): Doc { // 获取 AST 中的 node const node = path.getValue(); if (!node) return ''; // htmlparser2 的 AST 是一个数组,因此我们需要调用 _print,它会递归调用我们自己定义的 print if (Array.isArray(node)) { return concat(path.map(_print)); } // 继续判断 node.type,返回不同内容,限于篇幅,省略 } 复制代码
每一个格式化的代码片段,Prettier 将之称为 Doc
(c.3)。
需要注意的是,AXML 中有两个地方会存在 JS 表达式(expression),标签(tag
)的属性(attribute
)和文本(text
),它们存在于 {{}}
当中。这些表达式也需要格式化!
要处理 {{}}
中的 JS 表达式,则需要通过 embed
(c.2),在 embed
函数中可以调用其他 parser 来处理目标文本(用法见下文)。因为是 JS 表达式,我们调用 Prettier 内置的 babel
parser 来处理 JS 表达式就行了。
这就要求我们先解析 {{}}
。{{}}
格式是非常流行的所谓 mustache
风格,出于教学目的,我们直接用 mustache.js 来解析。
实际上简单地用 mustache.js 会有问题,因为类似
{{!a && b}}
这样的片段在 mustache.js 是有语义的({{!
表示注释);但在 AXML 里,它仅表示!a && b
表达式。这里我们就不展开了。 另,小程序框架是自行实现了一个{{}}
的解析器。
embed
Prettier 在执行时,embed
(c.2)会优先于 print
(c.1)执行:如果 embed
返回了非 null
的值,则结束格式化;反之,继续执行 print
中的逻辑。
在 embed
(c.2)中:
// embed.ts import { FastPath, Doc, ParserOptions, Options, doc } from 'prettier'; import { DataNode, Element } from 'domhandler'; import { parse } from 'mustache'; const { group, // (d.1) Prettier 最基本的方法,会根据 printWidth 等配置项自动换行(或不换行) concat, // 拼接 Doc 的方法,类似 Array.prototype.concat line, // 一个换行,如果父级 group(d.1) 后不需换行,则将其转换为一个空格 indent, // 一个缩进,如果父级 group(d.1) 后不需换行,则忽略 softline, // 一个换行,如果父级 group(d.1) 后不需换行,则忽略 } = doc.builders; export default function embed( path: FastPath, print: (path: FastPath) => Doc, textToDoc: (text: string, options: Options) => Doc, // (d.2) options: ParserOptions // (d.3) ): Doc | null { const node = path.getValue(); // 返回 null,则交给 print(c.1) 继续执行 if (!node || !node.type) return null; switch (node.type) { // 文本类型 case 'text': const text = (node as DataNode).data; // 1. 调用 mustache.parse 解析文本 // 2. 调用 textToDoc(d.2) 格式化 JS 表达式(如有) // 3. 拼接 `{{`、格式化好的表达式、`}}`(如有) // 4. 调用 group(d.1) 方法包裹前面拼接好的内容 // 标签类型 case 'tag': // 1. 如果有 children,递归调用 // 2. 提取 attribute,调用 mustache.parse 解析文本 // 3. 调用 textToDoc(d.2) 格式化 JS 表达式(如有) // 4. 拼接 `{{`、格式化好的表达式、`}}`(如有) // 5. 调用 group(d.1) 方法包裹前面拼接好的内容 default: // 返回 null,则交给 print(c.1) 继续执行 return null; } } 复制代码
特别说明一下 textToDoc
(d.2)方法,要解析 JS 表达式,按如下方式使用即可:
// embed.ts // ... const doc: Doc = textToDoc(expressionExtractedByMustache, { parser: 'babel', semi: false, singleQuote: true, }); return indent(concat([softline, doc])); 复制代码
options(d.3)参数就是我们指定的一些配置项了,也包含自定义的配置项(见下文)。
此外,关于 group
、indent
等方法,建议大家 查阅文档。
当然还有一些需要特别注意的地方,比如
style
属性可以直接这样写style="{{height: '100%', width: '100%'}}"
(实际上所有的对象型属性都可以简化写成这样),大括号里提取出来的文本并不是合法的 JS 表达式,需要我们特殊处理。此种细节都要考虑到。
options
index.ts 中的 export const options
用于指定插件所支持的自定义配置项。
假如我们希望小程序 AXML 插件支持一个 axmlBracketSameLine
的配置项,其作用类似 jsxBracketSameLine。
那么可以这样定义:
// index.ts import { SupportLanguage, Parser, Printer, SupportOption, ParserOptions } from 'prettier'; // ... 省略 interface PluginOptions { axmlBracketSameLine: boolean; } // 插件自定义的配置项 export const options: Record<keyof PluginOptions, SupportOption> = { axmlBracketSameLine: { name: 'axmlBracketSameLine', category: 'Global', type: 'boolean', default: false, description: 'Put the `>` of a multiline AXML element on a new line', }, }; 复制代码
这样,上文的 options(d.3)参数中就可以读到 options.axmlBracketSameLine
,以此决定是否要将开标签的结束字符 >
放置在同一行。
defaultOptions
插件的默认配置项,会覆盖 Prettier 的同名默认配置项,可以指定内置配置项和插件自定义配置项。
例如:
// index.ts import { SupportLanguage, Parser, Printer, SupportOption, ParserOptions } from 'prettier'; // ... 省略 export const defaultOptions: Partial<ParserOptions> = { tabWidth: 2, // 2 个空格缩进 printWidth: 80, // 打印宽度 80 }; 复制代码
到这里,我们的 AXML 插件就开发完成了。
使用插件
插件使用起来非常简单,只需将我们的插件发布到 npm(或 yarn,或私有化的 npm 服务如 tnpm),且其 package 名称以下述字符开头,Prettier 执行时就会自动加载插件、自动识别文件类型并调用对应插件:
@prettier/plugin-
prettier-plugin-
@<scope>/prettier-plugin-
假设我们将小程序 AXML 插件发布到 npm 上,并命名为 prettier-plugin-axml
,那么只需要在你的项目中安装:
npm i --save-dev prettier prettier-plugin-axml 复制代码
然后执行:
./node_modules/.bin/prettier --write "src/**/*.axml" 复制代码
就大功告成了。
因为我们已经在
extensions
中(a.2)指定了文件后缀为.axml
,所以 prettier 会自动为此类文件匹配我们的插件,因此不用显式指定plugin
。
总结
概括来说,要开发一个 Prettier 插件,总共分三步:
- 用一个或多个 parser 把源代码解析为 AST;
- 调用 Prettier 的 API 按需加入换行、空格、缩进等;
- 没了。
是不是很简单呢?
参考链接
作者:钉钉前端团队