迁移到 Pug v2 migration-v2

Pug中文使用手册~api 迁移到 Pug v2

Pug v2 已经在 2016 年 8 月发布。为了尽可能改善新版本的体验,我们不得不作出决定,移除、或者不赞成使用一些 API 和未归档的特性。我们努力让这些变更尽可能不具破坏性。当前,这些变更大多数会以控制台输出的方式进行警告。

此页面将详细介绍您应该如何将代码从旧版本迁移到最新版本的 Pug 上。

新的名称 Project Rename

因为商标方面的问题,这个项目的名称已经在 Pug v2 发布之际从“Jade”变更为“Pug”。这也意味着官方支持的文件扩展名从 .jade 变为 .pug。尽管依然支持 .jade,但这是不赞成的,我们建议所有的用户都立刻将其改为 .pug

已经移除的语言特性 Removed Language Features

绝大多数被移除的内容都可以被 pug-lint 自动检测出来,这是我们官方提供的代码规范器。

传统 Mixin 调用 Legacy Mixin Call

旧版本
pug
mixin foo('whatever')
新版本
pug
+foo('whatever')

我们移除了传统的调用 mixin 的语句,这样可以更容易区分 Mixin 的声明和调用。所有这类旧语句在 Jade v1 里都已经警告。

属性嵌入 Attribute Interpolation

旧版本
pug
a(href='#{link}')

a(href='before#{link}after')
新版本
pug
a(href=link)
//- (在 Node.js/io.js ≥ 1.0.0)
a(href=`before${link}after`)
//- (任何场合)
a(href='before' + link + 'after')

我们移除了在标签属性里的嵌入支持。它给实现平添了不必要的复杂度,而且也让用户不易注意到属性的赋值其实可以是任意的 JavaScript 表达式。阅读属性的文档来了解更多关于标签属性的语法。

带有前缀的each语法

旧版本
pug
- each a in b
  = a

- for a in b
  = a
新版本
pug
each a in b
  = a

for a in b
  = a

这里的 each 并非 JavaScript 的语法,在 JavaScript 代码行中使用 each“关键字”会让人感到非常困惑。没有括号的 for 关键字也是同样的情况。

只需要简单地删去 -,您的代码应该就能重新工作。

已删除的 API Removed API

以下导出属性和编译选项已经被移除。请确保您的代码没有使用它们。

属性 Properties

doctype

此前,未归档的对象 jade.doctype 是一个存放 doctype 缩写的哈希表。用户可以通过扩充这个对象来自定义额外的 doctype 缩写,或者修改已有的 doctype 缩写。

在 Pug v2 中,这个对象已经从 Pug 分离出来,单独成为一个叫做 doctypes 的包。如果您要扩充 doctype 缩写,可以写成一个 codeGen 的插件。

nodes

此前,未归档的对象 jade.nodes 是一个存放(未归档的)Jade 抽象语法树节点的构造函数的哈希表。

在 Pug v2 中,我们弃用了这种做法,取而代之的是使用抽象语法树节点的 type 属性实现鸭子类型。

selfClosing

此前,未归档的数组 jade.selfClosing 可以用于添加或者修改自闭合标签的条目。

在 Pug v2 中,这个数组已经从 Pug 分离出来,单独成为一个叫做 void-elements 的包。如果您要修改这个数组,可以写成一个 codeGen 的插件。

utils

此前,jade.utils 对象包含了三个模板引擎内部比较有用的函数:

utils.merge 已经从 Pug 中移除并不再使用。其功能大体上可以用 ECMAScript 2015 的 Object.assign 方法及其他变种来实现。

utils.stringify 已经从 Pug 分离出来到叫做 js-stringify 的包,同时有额外的跨站脚本攻击保护。建议所有用户都改用此代码包。

utils.walkAST 已经分离到一个叫做 pug-walk 的包。

Compiler, Lexer, Parser

此前,未归档的 Jade 的编译器(Compiler)、词法分析器(Lexer)和解析器(Parser)通过这三个属性导出。用户可以从这些类创建自己的编译器、词法分析器和解析器,从而自定义编译的行为。

Pug v2 允许通过插件自定义编译的行为,同时移除这些导出属性。

对应到 Pug v2 中,这几个类现在已经分为 pug-code-genpug-lexerpug-parser 这几个包,并且有各种与旧版本不兼容的变更。

选项 Options

compiler, lexer, parser

这些选项曾被用于已经被移除的 CompilerLexerParser

client

该选项曾用于模板函数的编译。大约从 2013 年起不推荐使用,并用 compileClient 函数代替,从那时起已经进行了警告。