# @github/jtml 中文文档

规范地址：https://npmcn.com/package/%40github/jtml/

版本：0\.5\.1
npm 元数据更新时间：2026-10-15T16:20:47.010Z
中文译文更新时间：2026-11-16T11:37:24.783Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40github/jtml
原文对照：https://npmcn.com/package/%40github/jtml/?lang=original
项目主页：https://github.com/github/jtml
源码仓库：https://github.com/github/jtml

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：40.3 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2020-10-27T12:33:39.682Z
- 最新版本发布：2023-05-10T10:58:48.794Z
- 近 30 天下载量：4722（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

使用模板标签在 JavaScript 中写入 HTML

## 安装

```sh
npm install @github/jtml
```

也可以使用：`pnpm add @github/jtml`、`yarn add @github/jtml`、`bun add @github/jtml`

## README

### @github/jtml (英语)

此库设计为顶部的一层 [@ github/ 模板部分](https://github.com/github/template-parts/) 以提供声明,JavaScript为基础的HTML模板标记.

这个图书馆的灵感很大 [`lit-html`](https://github.com/Polymer/lit-html),GitHub在生产中使用了一段时间。 这是独立创建的 `lit-html` 理由如下:

-   为了重新使用我们使用的代码 [@ github/ 模板部分](https://github.com/github/template-parts/) 它正在GitHub生产.
-   更接近于 `Template Parts` 什么提议? 通过使用 [@ github/ 模板部分](https://github.com/github/template-parts/) 我们的目标是与模板部分提案密切配合,希望有一天不再依赖 [@ github/ 模板部分](https://github.com/github/template-parts/)。 。 。 .

### 基本用途

这个图书馆有一套出口,主要两个是 `html` 财务报告和审定财务报表 `render`。 。 。 .

`html` 是一个 [“ 标记模板” 函数](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates)。与其叫它,不如叫它“Tag”一个模板字符串 `html` 它会返回一个 `TemplateResult` 它可用于安全地使 HTML 在客户端.

```js
import {html, render} from '@github/jtml'

const greeting = 'Hello'
render(html`<h1>${greeting} World</h1>`, document.body)
```

这的好处 超越,比如说,设置 `innerHTML` 被标记的模板可以被高效地重新使用,在 DOM 中导致的突变较少:

```js
import {html, render} from '@github/jtml'

const theTime = date => html`<p>The time is ${date.toString()}</p>`
setInterval(() => render(theTime(new Date()), document.body), 1000)
```

### 表达式

jtml 以特殊的方式将占位符表达式插入整个模板。 取决于您将占位符表达式放在哪里( `${}` 语法是一种占位符表达式)取决于它做什么. _重要的是_ "属性"的表现与"节点"不同. 以下是一份综合清单:

#### 属性

HTML 属性可以包含占位符表达式,但这些 _必须_ 在属性的引用部分内。 属性的名称不能使用占位符表达式,只使用值 .

```js
import {html, render} from '@github/jtml'

const className = `red-box`

html`<p class="${className}"></p>` // This is valid

html`<p class=${className}></p>` // !! This is INVALID!
html`<p ${attr}="test"></p>` // !! This is INVALID!
```

##### 布尔值

如果一个属性映射到一个 ["布尔属性"](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes),属性值包括 _仅_ 的占位符表达式,该表达式对布尔值进行评价,然后可用于切换打开或关闭属性。 例如:

```js
import {html, render} from '@github/jtml'

const input = (required = false) => html`<input required="${required}" />`
const div = (hidden = false) => html`<div hidden="${hidden}"></div>`

render(input(false), document.body) // Will render `<input />`
render(input(true), document.body) // Will render `<input required />`

render(div(true), document.body) // Will render `<div></div>`
render(div(false), document.body) // Will render `<div></div>`
```

##### 多个值, 空白

如果一个属性包含多个占位符表达式,这些都会被映射为字符串. 任何包含的白地空间也会像您所期望的那样释放出来. 举个例子:

```js
import {html, render} from '@github/jtml'

const p = ({classOne, classTwo, classThree}) => html`<p class="${classOne} ${classTwo} ${classThree}"></p>`

render(p({classOne: 'red', classTwo: 'box', classThree: ''}), document.body)
// ^ Renders `<p class="red box  "></p>`

const i = ({classOne, classTwo}) => html`<i class="${classOne}-${classTwo}"></i>`

render(i({classOne: 'red', classTwo: 'box'}), document.body)
// ^ Renders `<i class="red-box"></i>`
```

##### 可移动( 如阵列)

任何占位符表达式,如果评价到一个阵列/不可移动,则与空格(`Array.from(value).join(' ')`) (中文(简体) ). 这意味着你可以在一个字符串阵列中通过,它会作为空格分隔的列表被渲染出. 这些仍然可以与其他占位符表达式或静态值相混合. 一个例子是:

```js
import {html, render} from '@github/jtml'

const p = ({classes, hidden = false}) => html`<p class="bold ${classes} ${hidden ? 'd-none' : ''}"></p>

render(p({classes: ['red', 'box'], hidden: true}), document.body)
// ^ Renders `<p class="bold red box d-none"></p>`

render(p({classes: ['red', 'box'], hidden: false}), document.body)
// ^ Renders `<p class="bold red box "></p>`
```

##### 活动

如果属性名称开始于 `on`,而值则由单个占位符表达式组成,该表达式对某个函数进行评价,然后它将成为事件倾听器,其中事件名称是属性名称,而不包含 `on`,例如:

```js
import {html, render} from '@github/jtml'

const handleClick = e => console.log('User clicked!')

render(html`<button onclick="${handleClick}"></button>`, document.body)
// ^ Renders `<button></button>`
// Effectively calls `button.addEventListener('click', handleClick)`
```

事件名称可以是任何也可以作为属性的事件名称, 例如 `onloaded` 将聆听 `loaded` 事件, `onwill-load` 将约束于 `will-load` 活动。 特殊字符如 `:`s 不允许作为属性名称,因此,您无法使用此图案将这些特殊字符绑定在一个事件名称上.

#### 节点

也可以将占位符表达式放入一个HTML节点可能的位置——换句话说,放在标记内,而不是在属性内. 这些在属性值内对占位符表达式的表现不同:

##### HTML 逃逸

字符串内的任何 HTML 都会自动逃脱。 数值作为 `Text` 节点,意思是,除非您明确想要,否则不可能注入HTML,这使得这些节点对XSS安全. 这不是由库手动处理的,而是设计的核心 - 意思是浏览器处理这个逃跑! 一个例子是:

```js
import {html, render} from '@github/jtml'

const unsafe = '<script>alert(1)</script>'

render(html`<div>${unsafe}</div>`, document.body)
// ^ Renders `<div>&lt;script&gt;alert(1)&lt;/script&gt;</div>`
```

##### 子模板

如果占位符表达式对子模板进行评价,那么子模板将会被渲染出来并作为一个孩子被添加到节点中,处于您期望的位置:

```js
import {html, render} from '@github/jtml'

const embolden = word => html`<strong>${word}</strong>`

render(html`<div>Hello ${embolden('world')}!</div>`, document.body)
// ^ Renders `<div>Hello <strong>world</strong>!</div>`
```

#### 文件碎片

您也可以将文件片段传入, 并且会按您预期的那样被渲染出来 。 用于混合和匹配模板库:

```js
import {html, render} from '@github/jtml'

const vanillaEmbolden = word => {
  const frag = document.createDocumentFragment()
  const strong = document.createElement('strong')
  strong.append(String(word))
  frag.append(strong)
  return frag
}

render(html`<div>Hello ${vanillaEmbolden('world')}!</div>`, document.body)
// ^ Renders `<div>Hello <strong>world</strong>!</div>`
```

##### 可移动( 如阵列)

任何占位符表达式,如果评价到一个矩阵/不可移动,则按每个项目进行评价。 如果单个项目是文档断块或子模板,则将按您预期的那样进行渲染,否则将被视为字符串并添加为 `Text` 节点。 阵列的所有内容将一体化. 一些例子:

```js
import {html, render} from '@github/jtml'

const data = [ { name: 'Spanner', value: 5 }, { name: 'Wrench', value: 5 } ]

const row = ({name, value}) => html`<tr><td>${name}</td><td>${value}</td></td>`
const table = rows => html`<table>${rows.map(row)}</table>`

render(table(data), document.body)
// ^ Renders 
// <table>
//   <tr><td>Spanner</td><td>5</td></tr>
//   <tr><td>Wrench</td><td>5</td></tr>
// </table>
```

### 指令

对于更先进的行为,一个功能可以与 `directive` 函数创建 `Directive` 可以自定义渲染流程。 jtml还包括一些指令(见下文).

指令必须遵循下列签名。 它可以使用任意数量的参数(被忽略),并且必须返回接收模板部分的函数:

```typescript
type Directive = (...values: unknown[]) => (part: TemplatePart) => void
```

以下是指令如何发挥作用的例子:

```js
import {html, render, directive} from '@github/jtml'

// A directive can take any number of arguments, and must return a function that takes a `TemplatePart`.
const renderLater = directive((text, ms) => part => {
  // A parts value can be set using `.value`
  part.value = 'Loading...'
  setTimeout(() => part.value = text, ms)
})

render(html`<div>${renderLater('Hello world', 1000)}`, document.body)
// ^ Renders <div>Loading...</div>
// After 1000ms, changes to `<div>Hello world</div>`
```

### 由指令构建

### 直至

jttml 有处理承诺值内置指令的船舶,称为 `until`。 。 。 . `until` 以若干应许换取任何应许,然后,使那些应许如愿以偿。 这对于在同步值中传递作为第一个参数,超时消息作为中间值,以及占位符值的同步值,如:

```js
import {html, render, until} from '@github/jtml'

const delay = (ms, value) => new Promise(resolve => setTimeout(resolve, ms, value))

const request = delay(1000, 'Hello World')
const loading = 'Loading...'
const timeout = delay(2000, 'Failed to load')

render(html`<div>${until(request, timeout, loading)}</div>`)
// ^ renders <div>Loading...</div>
// After 1000ms will render <div>Hello World</div>
```

```js
import {html, render, until} from '@github/jtml'

const delay = (ms, value) => new Promise(resolve => setTimeout(resolve, ms, value))

const request = delay(3000, 'Hello World') // Request takes longer than the timeout
const loading = 'Loading...'
const timeout = delay(2000, 'Failed to load')

render(html`<div>${until(request, timeout, loading)}</div>`)
// ^ renders <div>Loading...</div>
// After 2000ms will render <div>Failed to load</div>
```

### CSP 信任类型

你可以打电话 `TemplateResult.setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null)` 从 Java 脚本设置 [CSP 信任的类型政策](https://web.dev/trusted-types/),可以执行(同步)过滤或拒绝已提供模板:

```ts
import {TemplateResult} from "@github/jtml";
import DOMPurify from "dompurify"; // Using https://github.com/cure53/DOMPurify

// This policy removes all HTML markup except links.
const policy = trustedTypes.createPolicy("links-only", {
  createHTML: (htmlText: string) => {
    return DOMPurify.sanitize(htmlText, {
      ALLOWED_TAGS: ["a"],
      ALLOWED_ATTR: ["href"],
      RETURN_TRUSTED_TYPE: true,
    });
  },
});
TemplateResult.setCSPTrustedTypesPolicy(policy);
```

注意:

-   只有单一的政策可以制定,由所有人共享 `render` 财务报告和审定财务报表 `unsafeHTML` 打电话.
-   你应该打电话 `TemplateResult.setCSPTrustedTypesPolicy()` 在任何其他呼吁之前 `@github/jtml` 在你的代码.
-   不是所有的浏览器 [支持 JavaScript 中信任的 API 类型](https://caniuse.com/mdn-api_trustedtypes)。您可能想要使用 [建议的微量填充](https://github.com/w3c/trusted-types#tinyfill) 构建一个不在其他浏览器中引起问题的策略.

## 常见问题

### @github/jtml 是什么？

使用模板标签在 JavaScript 中写入 HTML

### 如何安装 @github/jtml？

在项目目录运行 npm install @github/jtml，或使用 pnpm add / yarn add / bun add。

### @github/jtml 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/github\_\_jtml 是否存在。

### @github/jtml 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @github/jtml 可以商用吗？

@github/jtml 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @github/jtml 的下载量有多少？

根据 npm 官方下载统计，@github/jtml 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,722 次，日均约 157 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @github/jtml 还在维护吗？

最新版本 0\.5\.1 发布于 2023/05/10（3 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

