pug参考文档

2019/04/10 10:10
阅读数 55

1. API

express框架的渲染模板有多种选择,官方的例子是Pug,网上找了一下,Pug没有可以参考的中文文档,于是自己动手丰衣足食。翻译水平一般,各位凑合着看吧。

ps:最近搜索了一下,中文文档还是有的,不知道为啥当时死活百度上找不到。

https://pug.bootcss.com/api/getting-started.html

https://pugjs.org/zh-cn/api/reference.html

1.1 开始

安装

通过npm安装pug:

$ npm install pug

简介

Pug的渲染语句很简单,pug.compile()方法将pug源文件(.pug)源文件编译成一个带参数(‘locals’,pug文件的路径)方法,然后调用这个结果方法就能购生成一段由pug文件转化成的html字符串。

这个pug.compile()方法可以重复使用,生成各种各样的html字符串来渲染html。

//- template.pug,pug文件
p #{name}'s Pug source code!

调用方法:

const pug = require('pug');

// 编译pug源文件
const compiledFunction = pug.compileFile('template.pug');

// 渲染数据
console.log(compiledFunction({
  name: 'Timothy'
}));
// "<p>Timothy's Pug source code!</p>"

// 渲染另一个数据
console.log(compiledFunction({
  name: 'Forbes'
}));
// "<p>Forbes's Pug source code!</p>"

Pug还提供另外一种渲染方式:pug.render系列的方法,它把编译和渲染合并成一个步骤,不需要生成编译函数,直接渲染pug源文件。当然,默认情况下调用它每次都要编译一次,这可能会影响性能。可以选择配置项cache为true,将编译函数缓存起来,不用每次都重新生成,编译。如下面的pug.renderFile方式:

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
  name: 'Timothy'
}));
// "<p>Timothy's Pug source code!</p>"

1.2 和Express整合

Pug和Express结合,参考这个指南

生产环境配置

Express中环境变量NODE_ENV用来标识当前应用是在开发环境还是生产环境。Express和Pug会根据这个环境变量自动修改一些配置选项,为用户提供友好的“开箱即用”的使用体验。

例如,在Express中使用Pug时,当process.env.NODE_ENV是“production”,compileDebug选项是false,默认情况下它是true。

可以通过设置app.locals或者res.locals为true或者false来覆盖compileDebug和cache的默认选项值。还可以通过Express的app.disable/enable('view cache')放来开修改cache选项。

更多细节,参考Express的api文档

1.2.1 配置渲染引擎

1. 在app.js文件中设置渲染引擎:

// 设置渲染引擎
app.set('views', path.join(__dirname, './views'));
app.set('view engine', 'pug');

2. 在view目录下创建pug文件

3. 在routers文件夹下的文件中创建路由以渲染pug文件,例如在routes\site.js文件中:

const express = require('express');
const router = express.Router();
/* GET users listing. */
router.get('/', function (req, res, next) {
  res.render('index', { title: '首页', message: '首页' })
});
module.exports = router;

1.3 API参考

本节详细介绍Pug的api。

提示:可以直接在浏览器的console中访问这些api,例如:pub.render('p Hello world!')。

选项

Pug中的方法参数如下:

filename:string

要编译的文件的路径和名字,使用相对路径,保留后缀,默认是'.pug'。

basedir:string

所有文件的入口目录。

doctype:string

如果没有在Pug模板中指定doctype,可以在这里指定。

pretty:boolean | string

[不建议]在渲染HTML结果中添加一些空白字符串作为空格,以便阅读。如果使用字符串,则将改字符串作为特定的空格使用(例如'\t'制表符)。不建议使用这个选项。由于这个选项修改空白的解析和渲染方式,通常会带来意想不到的后果,因此后续版本中这个选项将被取消。默认值为false。

filters:object

自定义hash table过滤器,默认未定义。

self:boolean

使用默认自定义空间的locals,加快编译速度,无需编写变量,只须指定self.variable获取locals。默认false。

debug:boolean

如果设置为true,tokens和函数体将输出到日志中。

compileDebug:boolean 

如果设置为true,错误信息中将包含方法源码便于排查(测试环境会很有用)。该选项默认开启,在正式环境关闭。

globals:Array<string>

在html模板中添加全局变量

cache:boolean

如果设置为true,将缓存编译函数。使用pug源文件的名字作为cache的键值。render类的函数有这个选项,默认是false。

inlineRuntimeFunctions:boolean

内联函数,代替require,在compileClient函数内,默认是true(不必包含运行时)。在其他编译和渲染类型的函数中,这个选项默认是flase。

name:string

模板函数名。只在compileClient函数内。默认值是‘template’。

1.3.2 方法

pug.compile(source, ?options)

将一个Pug模板编译成一个函数,根据不同参数可以被多次渲染。

source:string

要编译的pug源文件。

options:?options

选项对象。

returns:function

返回值是一个根据本地配置生成html的函数。

var pug = require('pug');

// 生成编译函数
var fn = pug.compile('string of pug', options);

// 调用编译函数渲染html
var html = fn(locals);
// => '<string>of pug</string>' 

pug.compileFile(path, ?options)

将一个pug源文件编译成一个方法,根据不同参数可以多次调用。

path:string

pug文件的路径

options:?options

选项对象

returns:function

返回值是一个根据本地配置生成html的函数。

var pug = require('pug');

// 生成编译函数
var fn = pug.compileFile('path to pug file', options);

// 调用编译函数渲染html
var html = fn(locals);
// => '<string>of pug</string>' 

pug.compileClient(source, ?options)

将一个pug源文件编译成一段JavaScript函数字符串,可以用在客户端,调用这个函数返回html代码。

path:string

pug文件的路径

options:?options

选项对象

returns:function

返回值是一个JavaScript函数字符串

var pug = require('pug');

// 生成编译函数
var fn = pug.compileClient('string of pug', options);

// 调用编译函数生成一个函数字符串,这个函数函数返回html代码
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }' 

pug.compileClientWithDependenciesTracked(source, ?options)

和compileClient方法类似,不同之处在与这个函数返回一个dom结构对象。如下:

{
  'body': 'function (locals) {...}',
  'dependencies': ['filename.pug']
}

仅当需要依赖来实现诸如监视Pug文件的更改之类的操作时,才应使用此方法。

pug.compileFileClient(path, ?options)

编译一个Pug源文件便以为可在客户端与pug运行时一起使用的JavaScript字符串。

path:string

pug文件的路径

options:?options

选项对象

options.name:string

如果在options选项中指定了name属性,它将作为客户端模板函数的名称

returns:function

返回值是一个JavaScript函数主体

假设下面是pug文件内容:

h1 This is a Pug template
h2 By #{author} 

然后将pug文件编译为函数字符串。

var fs = require('fs');
var pug = require('pug');

// 将模板编译为函数字符串
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// 可以将所有模板便以为template.js文件提供给客户端
fs.writeFileSync("templates.js", jsFunctionString); 

这是输出函数字符串的样子(写到templates.js)

function fancyTemplateFun(locals) {
  var buf = [];
  var pug_mixins = {};
  var pug_interp;

  var locals_for_with = (locals || {});

  (function (author) {
    buf.push("<h1>This is a Pug template</h1><h2>By "
      + (pug.escape((pug_interp = author) == null ? '' : pug_interp))
      + "</h2>");
  }.call(this, "author" in locals_for_with ?
    locals_for_with.author : typeof author !== "undefined" ?
      author : undefined)
  );

  return buf.join("");
}

除了编译的模板之外,还要确保将Pug运行时(node_modules / pug / runtime.js)发送给客户端。如下:

<!DOCTYPE html>
<html>
  <head>
    <script src="/runtime.js"></script>
    <script src="/templates.js"></script>
  </head>

  <body>
    <h1>This is one fancy template.</h1>

    <script type="text/javascript">
      var html = window.fancyTemplateFun({author: "enlore"});
      var div = document.createElement("div");
      div.innerHTML = html;
      document.body.appendChild(div);
    </script>
  </body>
</html> 

pug.render(source, ?options, ?callback)

source:string

要渲染的pug模板

options:?options

选项对象

callback: ?function

一个接受渲染结果回调函数,可以同步调用。

returns:function

返回值是一个JavaScript函数字符串

var pug = require('pug');

var html = pug.render('string of pug', options);
// => '<string>of pug</string>

pug.renderFile(path, ?options, ?callback)

path:string

pug文件的路径

options:?options

选项对象

callback: ?function

一个接受渲染结果回调函数,可以同步调用。

returns:function

返回值是HTML字符串

var pug = require('pug');

var html = pug.renderFile('path/to/file.pug', options);
// ... 

1.4 filters选项

pug.filters

自定义的过滤器

该对象的语义与选项中的过滤器语义相同,但是全局应用于所有Pug编译。 当pug.filters和options.filters中都存在过滤器时,filters选项优先

提示:不推荐使用此属性,而推荐使用滤镜选项。

2. 语法参考

2.1 属性

pug代码中的标记属性看起来和HTML(带逗号),但是它的值只是普通的JavaScript。(注意:此页面上的示例使用竖线字符(|)进行空白控制。)

a(href='google.com') Google
|
|
a(class='button' href='google.com') Google
|
|
a(class='button', href='google.com') Google 

生成结果:

<a href="google.com">Google</a>
<a class="button" href="google.com">Google</a>
<a class="button" href="google.com">Google</a> 

普通的JavaScript也可以正常工作

- var authenticated = true
body(class=authenticated ? 'authed' : 'anon')
<body class="authed"></body> 

多个属性

如果有多个属性,还可以把他们放在多行

input(
  type='checkbox'
  name='agreement'
  checked
)
<input type="checkbox" name="agreement" checked="checked" /> 

如果你的JavaScript环境支持ES2015中的模板字符串(包含Node.js/io.js 1.0.0或后续版本),可以使用模板字符串,如果属性值很长,这将会很有用。

input(data-json=`
  {
    "very-long": "piece of ",
    "data": true
  }
`) 
<input data-json="
  {
    &quot;very-long&quot;: &quot;piece of &quot;,
    &quot;data&quot;: true
  }
" /> 

引用属性

如果属性名中包可能会干扰JavaScript语法的含奇怪字符,请使用双引号或者单引号区分不同的属性。包含[]和()(Angular2中经常使用)

//- In this case, `(click)` is treated as a
//- function call instead of a attribute name,
//- resulting in the unusual error.
div(class='div-class' (click)='play()'

报错:

index.pug:4:11
    2| //- function call instead of a attribute name,
    3| //- resulting in the unusual error.
  > 4| div(class='div-class' (click)='play()')
-----------------^

Syntax Error: Assigning to rvalue 

正确的写法是:

div(class='div-class', (click)='play()')
div(class='div-class' '(click)'='play()'
<div class="div-class" (click)="play()"></div>
<div class="div-class" (click)="play()"></div> 

属性插值

注意:Pug/Jade的早期版本支持插值语法,例如:

a(href="/#{url}") Link

不再支持此语法。 替代方法如下。 (有关Pug v2与先前版本之间其他不兼容性的更多信息,请参阅我们的迁移指南。)

在属性中包含变量,可以使用以下替代方法:

1.在JavaScript中使用属性

- var url = 'pug-test.html';
a(href='/' + url) Link
|
|
- url = 'https://example.com/'
a(href=url) Another link 

结果如下:

<a href="/pug-test.html">Link</a>
<a href="https://example.com/">Another link</a> 

2.如果你的JavaScript环境支持ES2015(包含Node.js/io.js及更高版本),还可以使用其语法来简化属性

- var btnType = 'info'
- var btnSize = 'lg'
button(type='button' class='btn btn-' + btnType + ' btn-' + btnSize)
|
|
button(type='button' class=`btn btn-${btnType} btn-${btnSize}`) 

结果如下

<button class="btn btn-info btn-lg" type="button"></button>
<button class="btn btn-info btn-lg" type="button"></button> 

未转义的属性

默认情况下,所有属性均被转义(即特殊字符被替换成转义序列)以防止攻击(例如:跨站攻击)。如果需要使用特殊符号,请使用 != 代替 =

div(escaped="<code>")
div(unescaped!="<code>"

结果如下:

<div escaped="&lt;code&gt;"></div>
<div unescaped="<code>"></div> 

注意:未转义的代码是很危险的。必须确保清除用户输入中没有这种代码,以避免跨站脚本攻击

布尔类型的属性

pug中布尔类型的属性被自动转换为true,false。如果未指定任何值,则假定为true

input(type='checkbox' checked)
|
|
input(type='checkbox' checked=true)
|
|
input(type='checkbox' checked=false)
|
|
input(type='checkbox' checked=true.toString()) 

结果如下:

<input type="checkbox" checked="checked" />
<input type="checkbox" checked="checked" />
<input type="checkbox" />
<input type="checkbox" checked="true" /> 

ps:用两个竖线分隔换行,pug代码比html代码还长!这是搞什么鸡毛啊。

style属性

像普通属性一样,style属性可以是一个字符串;同时它也可以是一个对象,这样生成样式会很方便。

a(style={color: 'red', background: 'green'}) 
<a style="color:red;background:green;"></a> 

class属性

像普通属性一样,class属性可以是一个字符串;同时它也可以是一个对象,这样生成样式会很方便。

- var classes = ['foo', 'bar', 'baz']
a(class=classes)
|
|
//- class属性可以merge多个
a.bang(class=classes class=['bing'])
<a class="foo bar baz"></a>
<a class="bang foo bar baz bing"></a> 

它也可以是将类名映射为true或false的对象。 这对于应用条件类很有用

- var currentUrl = '/about'
a(class={active: currentUrl === '/'} href='/') Home
|
|
a(class={active: currentUrl === '/about'} href='/about') About
<a href="/">Home</a>
<a class="active" href="/about">About</a> 

class选择器语法

可以使用.classname语法创建class属性

a.button
<a class="button"></a> 

由于div是一个常用的dom,如果声乐标签名,默认生成一个dom,如下:

.content
<div class="content"></div> 

ps:这个比较人性化

ID语法

使用id语法#idname可以创建元素

a#main-link
<a id="main-link"></a>

由于div是一个常用的dom,如果声乐标签名,默认生成一个dom,如下:

#content
<div id="content"></div> 

自定义属性

使用&attributes语法可以创建多个自定义属性

div#foo(data-bar="foo")&attributes({'data-foo': 'bar'})
<div id="foo" data-bar="foo" data-foo="bar"></div> 

上面例子中启示可以使用object语法创建多个属性,也可以使用变量灵活处理。(参考:Mixin属性)

- var attributes = {};
- attributes.class = 'baz';
div#foo(data-bar="foo")&attributes(attributes) 
<div class="baz" id="foo" data-bar="foo"></div> 

注意:使用&attributes属性不会自动转义,使用的时候必须注意验证用户输入,避免跨站攻击。使用mixin调用可以自动完成转义。

2.2 Case语法

在JavaScript中case语法是和switch配合使用,pug中也可以使用switch...case,如下:

- var friends = 10
case friends
  when 0
    p you have no friends
  when 1
    p you have a friend
  default
    p you have #{friends} friends
<p>you have 10 friends</p> 

Case

pug中的case语法和JavaScript中的switch类似,如下:

- var friends = 0
case friends
  when 0
  when 1
    p you have very few friends
  default
    p you have #{friends} friends 
<p>you have very few friends</p> 

但是和JavaScript中的case还是有区别,pud中没有不是switch-case,而是case-when,如果不想在switch语句中输出任何内容,可以添加一个显式的break,如下:

- var friends = 0
case friends
  when 0
    - break
  when 1
    p you have very few friends
  default
    p you have #{friends} friends 

这个case语句不会输出任何内容

case块语法也可以像下面这样:

- var friends = 1
case friends
  when 0: p you have no friends
  when 1: p you have a friend
  default: p you have #{friends} friends
<p>you have a friend</p> 

2.3 内联代码

Pug允许在模版中编写内联JavaScript代码。有三种类型的代码:Unbuffered(未缓存?),Buffered(缓冲?)和Unescaped Buffered(未转义的缓冲)

Unbuffered Code

Unbuffered代码以-开头,注意这一句不会输出任何内容

- for (var x = 0; x < 3; x++)
  li item
<li>item</li>
<li>item</li>
<li>item</li> 

当然,也支持块输出:

-
  var list = ["Uno", "Dos", "Tres",
          "Cuatro", "Cinco", "Seis"]
each item in list
  li= item
<li>Uno</li>
<li>Dos</li>
<li>Tres</li>
<li>Cuatro</li>
<li>Cinco</li>
<li>Seis</li> 

Buffered Code

Buffered代码以=开头。它先计算JavaScript表达式并输出结果,为安全起见,Buffered代码首先转义为HTML

p
  = 'This code is <escaped>!'
<p>This code is &lt;escaped&gt;!</p> 

它也可以以内联属性编写,并支持所有JavaScript表达式

p= 'This code is' + ' <escaped>!'
<p>This code is &lt;escaped&gt;!</p> 

Unescaped Buffered Code

未转义的Buffered代码以!=开头。它计算JavaScript表达式并输出结果,但是输出的Html代码是未转义的,因此对用户而言是不安全的

p
  != 'This code is <strong>not</strong> escaped!'
<p>This code is <strong>not</strong> escaped!</p> 

和转义的Buffered代码一样,它可以以内联形式编写属性,支持所有的JavaScript表达式

p!= 'This code is' + ' <strong>not</strong> escaped!' 
<p>This code is <strong>not</strong> escaped!</p> 

注意:未转义的Buffered代码可能是非常危险的。必须处理用户输入,避免跨站攻击

2.5 注释

缓冲注释和JavaScript中的单行注释一样,它的行为类似于标记标签,渲染的时候生成html注释。

// just some paragraphs
p foo
p bar
<!-- just some paragraphs-->
<p>foo</p>
<p>bar</p> 

Pug还支持无缓冲注释,只需在注释开头加上字符-。这种注释只是对Pug代码本身进行注释,不会呈现在HTML中。

//- will not output within markup
p foo
p bar 
<p>foo</p>
<p>bar</p> 

块注释

块注释方式如下:

body
  //-
    Comments for your template writers.
    Use as much text as you want.
  //
    Comments for your HTML readers.
    Use as much text as you want.
<body>
  <!--Comments for your HTML readers.
Use as much text as you want.-->
</body> 

条件注释 

Pug中的条件注释和html一样,没有特殊的语法。(条件注释是为旧版本的Internet Explorer添加回退标记的一种特殊方法。)

Pug中以<开头被视为纯文本,普通的JavaScript条件注释在Pug中可以正常工作。

doctype html

<!--[if IE 8]>
<html lang="en" class="lt-ie9">
<![endif]-->
<!--[if gt IE 8]><!-->
<html lang="en">
<!--<![endif]-->
body
  p Supporting old web browsers is a pain.

</html> 
<!DOCTYPE html>
<!--[if IE 8]>
<html lang="en" class="lt-ie9">
<![endif]-->
<!--[if gt IE 8]><!-->
<html lang="en">
<!--<![endif]-->
<body>
  <p>Supporting old web browsers is a pain.</p>
</body>

</html> 

2.6 条件语句

Pug中条件语句可以不使用括号包裹

- var user = { description: 'foo bar baz' }
- var authorised = false
#user
  if user.description
    h2.green Description
    p.description= user.description
  else if authorised
    h2.blue Description
    p.description.
      User has no description,
      why not add one...
  else
    h2.red Description
    p.description User has no description
<div id="user">
  <h2 class="green">Description</h2>
  <p class="description">foo bar baz</p>
</div> 

Pug还提供条件判断语句unless,它和if是相反的,如下两种判断是等价的。

unless user.isAnonymous
  p You're logged in as #{user.name}
if !user.isAnonymous
  p You're logged in as #{user.name} 

2.7 文档类型

doctype html
<!DOCTYPE html> 

文档类型缩写

常用文档内省有一些快捷方式:

doctype html

<!DOCTYPE html> 

doctype xml

<?xml version="1.0" encoding="utf-8" ?> 

doctype transitional

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 

doctype strict

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 

doctype frameset

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"> 

doctype 1.1

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> 

doctype basic

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 

doctype mobile

<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd"> 

doctype plist

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 

自定义文档类型

还可以自定义自己的文档类型,如下:

doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"

Doctype选项

除了在输出中缓冲外,Pug中的doctype还可能影响编译。 例如,自动关闭的标签是否以/>或>结尾取决于是否指定了HTML或XML。 布尔属性的输出也可能会受到影响。

如果由于其他原因无法使用doctype关键字(例如,仅渲染HTML片段),但是仍然希望指定模板的doctype,则可以通过doctype选项进行操作。

var pug = require('pug');

var source = 'img(src="foo.png")';

pug.render(source);
// => '<img src="foo.png"/>'

pug.render(source, {doctype: 'xml'});
// => '<img src="foo.png"></img>'

pug.render(source, {doctype: 'html'});
// => '<img src="foo.png">'

2.7 过滤器

过滤器允许在Pug模板中使用其他的语言,他们作为一块文本输入。要将选项传递给过滤器,需要在过滤器后的括号内添加(就像标记属性一样)例如:

:less(ieCompat=false

所有JSTransformer模块都可以用作Pug过滤器。 流行的过滤器包括:babel,:uglify-js,:scss和:markdown-it。 请查看JSTransformer的文档,以了解特定过滤器支持的选项。

如果找不到适合您的用例的过滤器,则可以编写自己的自定义过滤器。

例如,如果您希望能够在Pug模板中使用CoffeeScript和Markdown(使用Markdown-it渲染器),则首先要确保已安装以下插件:

$ npm install --save jstransformer-coffee-script
$ npm install --save jstransformer-markdown-it

现在,您应该能够使用以下模板渲染:

:markdown-it(linkify langPrefix='highlight-')
  # Markdown

  Markdown document with http://links.com and

  ```js
  var codeBlocks;
  ```
script
  :coffee-script
    console.log 'This is coffee script'
<h1>Markdown</h1>
<p>Markdown document with <a href="http://links.com">http://links.com</a> and</p>
<pre><code class="highlight-js">var codeBlocks;
</code></pre>
<script>
  (function() {
    console.log('This is coffee script');

  }).call(this);
</script> 

警告:过滤器在编译时渲染。 这使它们快速运行,但也意味着它们不能支持动态内容或选项。默认情况下,浏览器中的编译无法访问基于JSTransformer的筛选器,除非JSTransformer模块已明确通过CommonJS平台打包(例如Browserify或Webpack)。 实际上,您正当前这个页面正式使用使用Browserify打包使得过滤器在浏览器中可用。在服务器上预编译的模板没有此限制。

内联语法

如果过滤器的内容比较短,甚至可以像使用标签那样使用过滤器。

p
  :markdown-it(inline) **BOLD TEXT**

p.
  In the midst of a large amount of plain
  text, suddenly a wild #[:markdown-it(inline) *Markdown*]
  appeared.
<p><strong>BOLD TEXT</strong></p>
<p>In the midst of a large amount of plain text, suddenly a wild <em>Markdown</em> appeared.
</p> 

包含语法

在使用过滤器的时候,可以通过包含语法将外部文件包含进来。

嵌套的过滤器

可以在同一文本快上应用多个过滤器,为此只需在同一行使用过滤器语法。

过滤器以相反的顺序应用。 文本首先传递到最后一个过滤器; 然后,结果将传递到倒数第二个过滤器,依此类推。在以下示例中,脚本首先由babel转换,然后由cdata-js转换。

script
  :cdata-js:babel(presets=['es2015'])
    const myFunc = () => `This is ES2015 in a CD${'ATA'}`; 
f.default.existsSync is not a function 

自定义过滤器

通过filters选项,可以定义自定义过滤器

options.filters = {
  'my-own-filter': function (text, options) {
    if (options.addStart) text = 'Start\n' + text;
    if (options.addEnd)   text = text + '\nEnd';
    return text;
  }
}; 
p
  :my-own-filter(addStart addEnd)
    Filter
    Body 
<p>
  Start
  Filter
  Body
  End
</p> 

2.8 文件包含

包含语法允许在一个Pug文件中包含另一个Pug文件。

//- index.pug
doctype html
html
  include includes/head.pug
  body
    h1 My Site
    p Welcome to my super lame site.
    include includes/foot.pug
//- includes/head.pug
head
  title My Site
  script(src='/javascripts/jquery.js')
  script(src='/javascripts/app.js')
//- includes/foot.pug
footer#footer
  p Copyright (c) foobar 

结果如下:

<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
  <script src="/javascripts/jquery.js"></script>
  <script src="/javascripts/app.js"></script>
</head>
<body>
  <h1>My Site</h1>
  <p>Welcome to my super lame site.</p>
  <footer id="footer">
    <p>Copyright (c) foobar</p>
  </footer>
</body>
</html> 

如果使用绝对路径,可以使用options.basedir变量拼接,否则按照相对当前文件的路径解析。

如果没有后缀,.pug将作为默认后缀。

包含纯文本

包含的文件不是pug,则当做纯文本来处理。

//- index.pug
doctype html
html
  head
    style
      include style.css
  body
    h1 My Site
    p Welcome to my super lame site.
    script
      include script.js
/* style.css */
h1 {
  color: red;
}
// script.js
console.log('You are awesome');
<!DOCTYPE html>
<html>

<head>
  <style>
    /* style.css */

    h1 {
      color: red;
    }
  </style>
</head>

<body>
  <h1>My Site</h1>
  <p>Welcome to my super lame site.</p>
  <script>
    // script.js
    console.log('You are awesome');
  </script>
</body>
</html> 

包含过滤器

可以将过滤器与当前Pug文件结合使用。

//- index.pug
doctype html
html
  head
    title An Article
  body
    include:markdown-it article.md
# article.md

This is an article written in markdown.
<!DOCTYPE html>
<html>
  <head>
    <title>An Article</title>
  </head>
  <body>
    <h1>article.md</h1>
    <p>This is an article written in markdown.</p>
  </body>
</html> 

2.8 模板继承

Pug支持模板继承,模板继承通过关键字“block”和“extends”实现。在模板中,block关键字表示这个块在子模块中可以被替换。此过程是递归的。下面示例定义了头部,块内容和脚。

//- layout.pug
html
  head
    title My Site - #{title}
    block scripts
      script(src='/jquery.js')
  body
    block content
    block foot
      #footer
        p some footer content 

创建新Pug文件来继承上面的Pug模板,在新的文件中使用extends关键字来继承,然后Pug模板中的block块会被继承下来。

注意foot块没有定义,所以使用父模板中的fug块,输出“some footer content”。而其他块将在自身基础上继承父模板的内容。

//- page-a.pug
extends layout.pug

block scripts
  script(src='/jquery.js')
  script(src='/pets.js')

block content
  h1= title
  - var pets = ['cat', 'dog']
  each petName in pets
    include pet.pug
//- pet.pug
p= petName 

还可以覆盖某个块以提供其他的块,在下面例子中,content块中暴露了sidebar和primary块(但是子模块可以完全覆盖掉content)

//- sub-layout.pug
extends layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing
//- page-b.pug
extends sub-layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing 

块的前置,后置

Pug允许替换(默认),前置,后置一个块。

假设您希望在每个页面的head块中都包含默认脚本。 您可以这样做:

//- layout.pug
html
  head
    block head
      script(src='/vendor/jquery.js')
      script(src='/vendor/caustic.js')
  body
    block content 

例如,现在考虑您的JavaScript游戏页面。 您需要一些与游戏相关的脚本以及这些默认脚本。 您可以简单地添加块:

//- page.pug
extends layout.pug

block append head
  script(src='/vendor/three.js')
  script(src='/game.js'

在使用append,prepend的时候可以省去block关键字,如下:

//- page.pug
extends layout

append head
  script(src='/vendor/three.js')
  script(src='/game.js'

常见错误

Pug的模板继承是一项强大的功能,可让您将复杂的页面模板结构拆分为更小,更简单的文件。 但是,如果将许多模板链接在一起,则可能会使页面复杂得不可维护。

请注意,只有命名块(block)和混合定义可以出现在子模板的顶层(未缩进),顶层不能出现其他内容,如lin(),script,和普通的标签如div(class="content")。 这个很重要! 否则会报错:Only named blocks and mixins can appear at the top level of an extending template。父模板定义页面的整体结构,子模板只能附加,添加或替换特定的标记和逻辑块。 如果子模板试图在块外添加内容,Pug将无法知道将其放置在最终页面的何处。

使用未缓冲的代码,如果需要在子模块中使用变量,则可以使用下面几种不同的方法:

  • 将变量添加到Pug选项对象,或在父模板的未缓冲代码中定义它们。 子模板将继承这些变量。
  • 在子模板的块中定义变量。 扩展模板必须至少包含一个块,否则将为空-只需在此处定义变量即可。

出于同样的原因,Pug的缓冲注释不能出现在扩展模板的顶层:它们产生的HTML注释在生成的HTML中无处渲染。 (但是,无缓冲的Pug注释仍然可以)

2.10 插值

Pug提供多种方式在html中插入一个值。

转义的字符串

下面例子中title,author,theGreat变量作为本地变量被插入到代码中。

- var title = "On Dogs: Man's Best Friend";
- var author = "enlore";
- var theGreat = "<span>escape!</span>";

h1= title
p Written with love by #{author}
p This will be safe: #{theGreat}
<h1>On Dogs: Man's Best Friend</h1>
<p>Written with love by enlore</p>
<p>This will be safe: &lt;span&gt;escape!&lt;/span&gt;</p> 

title演示的是最基本的使用方法,再是在#{}中使用变量将会被转义,并将结果缓冲到要渲染的模板中。

还可以使用表达式,只要是合法的,任何地方都可以使用。

- var msg = "not my inside voice";
p This is #{msg.toUpperCase()}
<p>This is NOT MY INSIDE VOICE</p> 

Pug可以自动找出判断表达式是否结束,甚至可以包含未转义的符号,例如}

p No escaping for #{'}'}!
<p>No escaping for }!</p> 

如果想在html中输出#{,可以将其转义,或者使用插值。

p Escaping works with \#{interpolation}
p Interpolation works with #{'#{interpolation}'} too!
<p>Escaping works with #{interpolation}</p>
<p>Interpolation works with #{interpolation} too!</p> 

未转义的字符串

可以将未转义的字符串缓冲在模板中。

- var riskyBusiness = "<em>Some of the girls are wearing my mother's clothing.</em>";
.quote
  p Joel: !{riskyBusiness}
<div class="quote">
  <p>Joel: <em>Some of the girls are wearing my mother's clothing.</em></p>
</div> 

注意:如果原内容来自用户输入,则将未转义的内容缓冲到模板中可能带来很大的风险。永远不要相信用户的输入。

标签插入

不仅可以使用JavaScript插入变量,还可以在Pug内容中插入标签,如下:

p.
  This is a very long and boring paragraph that spans multiple lines.
  Suddenly there is a #[strong strongly worded phrase] that cannot be
  #[em ignored].
p.
  And here's an example of an interpolated tag with an attribute:
  #[q(lang="es") ¡Hola Mundo!]
<p>This is a very long and boring paragraph that spans multiple lines. Suddenly there is a <strong>strongly worded phrase</strong> that cannot be
  <em>ignored</em>.</p>
<p>And here's an example of an interpolated tag with an attribute:
  <q lang="es">¡Hola Mundo!</q></p> 

您可以通过编写与Pug内联的HTML标签来完成相同的事,但是,编写Pug的目的是什么? 将内嵌的Pug标签声明包装在#[]中,它将被评估并缓冲到其包含标签的内容中。

空格控制

默认情况下,Pug会删除标记之前和之后所有的空格,如下:

p
  | If I don't write the paragraph with tag interpolation, tags like
  strong strong
  | and
  em em
  | might produce unexpected results.
p.
  If I do, whitespace is #[strong respected] and #[em everybody] is happy.
<p>If I don't write the paragraph with tag interpolation, tags like<strong>strong</strong>and<em>em</em>might produce unexpected results.</p>
<p>If I do, whitespace is <strong>respected</strong> and <em>everybody</em> is happy.</p>

有关此主题的更多讨论,请参见Plain Text。

2.11 循环输出

Pug中支持两种方式的循环输出:each和while

each

Pug中第一种循环输出语法each可以迭代模板中的数组和对象。

ul
  each val in [1, 2, 3, 4, 5]
    li= val
<ul>
  <li>1</li>
  <li>2</li>
  <li>3</li>
  <li>4</li>
  <li>5</li>
</ul> 

循环中可以从第二个参数中获取当前index

ul
  each val, index in ['zero', 'one', 'two']
    li= index + ': ' + val
<ul>
  <li>0: zero</li>
  <li>1: one</li>
  <li>2: two</li>
</ul> 

Pug中甚至可以迭代中获取对象的key

ul
  each val, index in {1:'one',2:'two',3:'three'}
    li= index + ': ' + val 
<ul>
  <li>1: one</li>
  <li>2: two</li>
  <li>3: three</li>
</ul> 

要迭代的对象或数组只是纯JavaScript。 因此,它可以是变量,也可以是函数调用的结果,或者几乎是其他任何东西。

- var values = [];
ul
  each val in values.length ? values : ['There are no values']
    li= val
<ul>
  <li>There are no values</li>
</ul>

如果数组或对象不包含要迭代的值,则还可以添加一个else块,该块将被执行。 以下等效于上面的示例:

- var values = [];
ul
  each val in values
    li= val
  else
    li There are no values 
<ul>
  <li>There are no values</li>
</ul> 

还可以使用for关键字代替each,效果是一样的。

while

还可以使用while来迭代,如下:

- var n = 0;
ul
  while n < 4
    li= n++ 
<ul>
  <li>0</li>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul> 

2.12 Mixins

Mixins允许创建可重用的块。

//- Declaration
mixin list
  ul
    li foo
    li bar
    li baz
//- Use
+list
+list 
<ul>
  <li>foo</li>
  <li>bar</li>
  <li>baz</li>
</ul>
<ul>
  <li>foo</li>
  <li>bar</li>
  <li>baz</li>
</ul> 

Mixins允许传入参数

mixin pet(name)
  li.pet= name
ul
  +pet('cat')
  +pet('dog')
  +pet('pig'
<ul>
  <li class="pet">cat</li>
  <li class="pet">dog</li>
  <li class="pet">pig</li>
</ul> 

混入块

Mixins还可以使用Pug块作为内容:

mixin article(title)
  .article
    .article-wrapper
      h1= title
      if block
        block
      else
        p No content provided

+article('Hello world')

+article('Hello world')
  p This is my
  p Amazing article 
<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
    <p>No content provided</p>
  </div>
</div>
<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
    <p>This is my</p>
    <p>Amazing article</p>
  </div>
</div> 

混合属性

混合还可以传入一个隐式参数,可以用来给属性赋值

mixin link(href, name)
  //- attributes == {class: "btn"}
  a(class!=attributes.class href=href)= name

+link('/foo', 'foo')(class="btn")
<a class="btn" href="/foo">foo</a> 

注意:默认情况下,属性中的值已被转义! 您应该使用!=以避免再次转义它们。 (另请参见未转义的属性。)

可以在混合中使用&attributes:

mixin link(href, name)
  a(href=href)&attributes(attributes)= name

+link('/foo', 'foo')(class="btn")
<a class="btn" href="/foo">foo</a> 

注意:语法+ link(class =“ btn”)也是有效的,并且等价于+ link()(class =“ btn”),因为Pug会尝试检测括号的内容是属性还是参数。 但是,建议您使用第二种语法,因为您没有明确传递任何参数,并且确保第一个括号是参数列表。

默认参数值

还可以设置参数的默认值,和ES6中设置函数的默认参数值是类似的:

//- Declaration
mixin article(title='Default Title')
  .article
    .article-wrapper
      h1= title

//- Use
+article()

+article('Hello world'
<div class="article">
  <div class="article-wrapper">
    <h1>Default Title</h1>
  </div>
</div>
<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
  </div>
</div> 

解析参数

在Mixins中可以使用解析参数来传递多个参数

mixin list(id, ...items)
  ul(id=id)
    each item in items
      li= item

+list('my-list', 1, 2, 3, 4
<ul id="my-list">
  <li>1</li>
  <li>2</li>
  <li>3</li>
  <li>4</li>
</ul> 

2.13 纯文本

Pug提供了四种获取纯文本的方法-即将未经处理的代码,文本渲染在HTML中,有时候会很有用。

纯文本仍然使用标记和字符串插值,但该行的第一个单词不是Pug标记。 并且由于不会转义纯文本,因此您还可以包括文字HTML。

一个常见的缺陷是在渲染的HTML中使用空白,将在后面讨论。

内联标签

插入纯文本最早的方式是使用内敛标签。第一个词是标签名,后面所有内容都是标签的内容。如果内容很短或者不介意这一行内容太长,这样是没有任何问题的。

p This is plain old <em>text</em> content.
<p>This is plain old <em>text</em> content.</p> 

HTML文本

当整行以左尖括号(<)开头时,它们也被视为纯文本,有时不方便的地方编写文字HTML标签很有用。 例如,一种用例是条件注释。 由于文字HTML标记不会得到处理,因此与Pug标记不同,它们不会自动关闭。

<html>
body
  p Indenting the body tag here would make no difference.
  p HTML itself isn't whitespace-sensitive.
</html> 
<html>
<body>
  <p>Indenting the body tag here would make no difference.</p>
  <p>HTML itself isn't whitespace-sensitive.</p>
</body>
</html> 

竖线隔开

将纯文本添加到模板的另一种方法是在行的前面加上竖线字符(|)。 如我们稍后在“空白内容”部分中所述,此方法对于将纯文本与内联标签混合很有用。

p
  | The pipe always goes at the beginning of its own line,
  | not counting indentation.
<p>The pipe always goes at the beginning of its own line, not counting indentation.</p> 

通常,您可能希望标签中包含大块文本。 一个很好的例子是在script和style标签中编写JavaScript和CSS代码。 为此,只需添加一个逗号, 如果标签具有属性,则在标签名称之后,或者在右括号之后。

注意在tag和逗号之间不能有空格,标签的纯文本内容必须缩进一级。

script.
  if (usingPug)
    console.log('you are awesome')
  else
    console.log('use pug')
<script>
  if (usingPug)
    console.log('you are awesome')
  else
    console.log('use pug')
</script> 

还可以在tag标签内部再使用逗号创建一个块:

div
  p This text belongs to the paragraph tag.
  br
  .
    This text belongs to the div tag. 
<div>
  <p>This text belongs to the paragraph tag.</p><br/>This text belongs to the div tag.</div> 

空格控制

处理HTML中的空白可能是学习Pug最麻烦的地方,不过掌握窍门之后就很容易了。只需要记住两点:

  1. Pug默认删除缩进,和元素间的所有空白。因此html结束符将和下一个html开始符相邻。这对一些块级元素(例如段落)是没有问题的,因为他们在浏览器中是单独的段落(处理使用css的display属性修)。但是如果确实需要在元素之间插入空格,参考下面第二条:
  2. Pug保留元素内的空白,包括:
    文本中的所有空格
    超出块缩进的空白区域
    尾部空格
    纯文本块内或者连续竖线换行之间的

 所以,Pug删除了标签之间的空格,保留标签内部的空格。这样可以控制是否可以在tag或者纯文本中出的空格。甚至单词之间的空格。

| You put the em
em pha
| sis on the wrong syl
em la
| ble. 
You put the em<em>pha</em>sis on the wrong syl<em>la</em>ble. 

去掉空格需要考虑控制标签和文本是否连接在一起。

a ...sentence ending with a link
| . 
<a>...sentence ending with a link</a>

如果需要添加空格,参考下面方法

推荐的方法

添加一个或者多个竖线,表示空白的管道符,在HTMl渲染的时候就会有空格出现。

| Don't
|
button#self-destruct touch
|
| me!
Don't
<button id="self-destruct">touch</button> me! 

如果你的内嵌标签不需要太多属性,可以在纯文本中使用标签值或者HTML

p.
  Using regular tags can help keep your lines short,
  but interpolated tags may be easier to #[em visualize]
  whether the tags and text are whitespace-separated.
<p>Using regular tags can help keep your lines short, but interpolated tags may be easier to <em>visualize</em> whether the tags and text are whitespace-separated.</p> 

不推荐的做法

根据需要的空格,可以在文本的开头(在块缩进,竖线字符和/或标记之后)添加一个额外的空格。 或者,您可以在文本末尾添加尾随空格。

| Hey, check out 
a(href="http://example.biz/kitteh.png") this picture
|  of my cat
| Hey, check out 
a(href="http://example.biz/kitteh.png") this picture
|  of my cat! 

上面的解决方案可以很好地工作,但是肯定会有些危险:默认情况下,许多代码编辑器都会在保存时删除尾随空格。 你的同时可能必须配置编辑器,以防止自动删除部空格。

 

参考连接:https://pugjs.org/api/getting-started.html

原文出处:https://www.cnblogs.com/tylerdonet/p/11883833.html

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
OSCHINA
登录后可查看更多优质内容
返回顶部
顶部