@github/jtml

中文文档
0.5.1发布于 2023/05/10MITES Module近 30 天下载 4722

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

中文使用文档
文档目录7 节
  1. @github/jtml (英语)
  2. 基本用途
  3. 表达式
  4. 指令
  5. 由指令构建
  6. 直至
  7. CSP 信任类型

@github/jtml (英语)

此库设计为顶部的一层 @ github/ 模板部分 以提供声明,JavaScript为基础的HTML模板标记.

这个图书馆的灵感很大 lit-html,GitHub在生产中使用了一段时间。 这是独立创建的 lit-html 理由如下:

基本用途

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

html 是一个 “ 标记模板” 函数。与其叫它,不如叫它“Tag”一个模板字符串 html 它会返回一个 TemplateResult 它可用于安全地使 HTML 在客户端.

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

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

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

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 属性可以包含占位符表达式,但这些 必须 在属性的引用部分内。 属性的名称不能使用占位符表达式,只使用值 .

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!
布尔值

如果一个属性映射到一个 "布尔属性",属性值包括 仅 的占位符表达式,该表达式对布尔值进行评价,然后可用于切换打开或关闭属性。 例如:

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>`
多个值, 空白

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

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(' ')) (中文(简体) ). 这意味着你可以在一个字符串阵列中通过,它会作为空格分隔的列表被渲染出. 这些仍然可以与其他占位符表达式或静态值相混合. 一个例子是:

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,例如:

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安全. 这不是由库手动处理的,而是设计的核心 - 意思是浏览器处理这个逃跑! 一个例子是:

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>`
子模板

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

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>`

文件碎片

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

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 节点。 阵列的所有内容将一体化. 一些例子:

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还包括一些指令(见下文).

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

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

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

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 以若干应许换取任何应许,然后,使那些应许如愿以偿。 这对于在同步值中传递作为第一个参数,超时消息作为中间值,以及占位符值的同步值,如:

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>
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 信任的类型政策,可以执行(同步)过滤或拒绝已提供模板:

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 类型。您可能想要使用 建议的微量填充 构建一个不在其他浏览器中引起问题的策略.

版本与发布记录

@github/jtml 共发布 13 个版本,首次发布于 2020/10/27;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.5.1latest2023/05/103 年前
0.5.02022/12/133 年前
0.4.12022/01/264 年前
0.4.02021/03/095 年前
0.3.42021/03/015 年前
0.3.32021/01/265 年前

关于 @github/jtml 的常见问题

@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 和提交记录判断。