迁移到 Pug v2 ~~ Migrating to Pug 2

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

  1. \\\\\\\\\\ old.pug <
  2. //- 旧版本
  4. mixin foo('whatever')
  5. \\\\\\\\\\ new.pug >
  6. //- 新版本
  8. +foo('whatever')

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

属性嵌入 ~~ Attribute Interpolation

  1. \\\\\\\\\\ old.pug <
  2. //- 旧版本
  4. a(href='#{link}')
  6. a(href='before#{link}after')
  7. \\\\\\\\\\ new.pug >
  8. //- 新版本
  10. a(href=link)
  12. //- (在 Node.js/io.js ≥ 1.0.0)
  13. a(href=`before${link}after`)
  14. //- (任何场合)
  15. a(href='before' + link + 'after')

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

带有前缀的 each 语法 ~~ Prefixed each Syntax

  1. \\\\\\\\\\ old.pug <
  2. //- 旧版本
  4. - each a in b
  5.   = a
  7. - for a in b
  8.   = a
  9. \\\\\\\\\\ new.pug >
  10. //- 新版本
  12. each a in b
  13.   = a
  15. for a in b
  16.   = 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-gen，pug-lexer 和 pug-parser 这几个包，并且有各种与旧版本不兼容的变更。

选项 ~~ Options

compiler, lexer, parser

这些选项曾被用于已经被移除的 Compiler，Lexer 和 Parser 类。

client

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