API 概述

设置 Eta

Eta 以类（class）的形式导出，因此在使用前必须将其实例化：

import { Eta } from "eta"
const eta = new Eta(options)

参数不是必须的的。你可以在 这里 找到所有参数的列表。大多数情况需要传递 views 参数，也就是模板目录的路径。

const eta = new Eta({ views: path.join(__dirname, "templates") })

其它常用参数包括：

• debug：启用运行时输出经过格式化的错误信息。默认值是 false。
• cache：是否缓存模板。默认值是 false。
• autoEscape：是否在模板中自动转义 HTML。默认值是 true。

渲染模板文件

同步渲染

渲染模板时，使用 render 方法：

const res = eta.render("templateName", { name: "Ben" })

第一个参数是模板名称，第二个参数是要传递给模板的数据。模板名称是相对于实例化 Eta 时传递的 views 参数而言的。

如果你希望使用经过命名的模板而不是解析自文件系统的，请在模板名称前添加 @ 符号。Eta 将不会尝试从文件系统中解析这些模板，而是在缓存中查找。

异步渲染

需要异步渲染模板时，使用 renderAsync 方法：

const res = await eta.renderAsync("templateName", { name: "Ben" })

renderAsync 方法返回值是一个 promise，因此你必须使用 await 或 .then 来获取最终结果。

渲染字符串

使用 renderString 方法可以将字符串作为模板进行渲染：

const res = eta.renderString("Hello <%= it.name %>", { name: "Ben" })

或者使用 renderStringAsync 方法异步渲染字符串：

const res = eta.renderStringAsync("Hello <%= await it.someFunction() %>", {
  someFunction: () => Promise.resolve("Ben")
})

以编程方式定义模板

用 loadTemplate 方法以编程方式定义模板：

const headerPartial = `
  <header>
    <h1><%= it.title %></h1>
  </header>
`

eta.loadTemplate("@header", headerPartial)

如果你的模板不是 views 目录下的文件，则必须以在模板名称前添加 @ 符号，以便通知 Eta 不要从文件系统中解析模板。

loadTemplate 方法的第三个参数是一个 {async: boolean} 类型的对象，用于描述模板是否支持异步。默认情况下，Eta 会将模板当作是同步的。

常见用例

自定义标签

你可以通过 Eta 的 tags 参数改变其默认的标签：

const eta = new Eta({ tags: ["{{", "}}"] })

自动过滤数据

你可以通过自定义的函数自动过滤所有值：

const eta = new Eta({
  autoFilter: true,
  filterFunction: (val) => {
    if (typeof val === "string") {
      return val.toUpperCase()
    }
    return val
  }
})

摆脱 it

默认情况下，Eta 会将所有数据存储在 it 变量中。你可以通过 varName 参数来修改此变量的名称。

const eta = new Eta({ varName: "data" })

// "Hi <%= data.name %>"

如果想完全去掉 it，你可以开启 useWith 参数：

const eta = new Eta({ useWith: true })
// "Hi <%= name %>"

这通常别人为是不好的做法，因为这样可能会导致命名冲突或性能下降。

更好的做法是通过 functionHeader 参数做一些配置：

const eta = new Eta({
  functionHeader: "const name=it.name, age=it.age"
})
// "Hi <%= name %>, our records show you are <%= age %> years old"

或者，如果您想要与 useWith 类似的行为，但性能更好（仍然存在命名冲突），那么您可以这样做：

const eta = new Eta({
  functionHeader: "Object.entries({...it}||{}).forEach(([k,v])=>globalThis[k]=v)"
})
// "Hi <%= name %>"

自定义文件处理方式

你可以通过扩展 Eta 类来重写 readFile 和 resolvePath 方法从而自定义 Eta 读取文件的方式：

class CustomEta extends Eta {
  readFile = function (...) {...}

  resolvePath = function (...) {...}
}