@github/jtml (英语)
此库设计为顶部的一层 @ github/ 模板部分 以提供声明,JavaScript为基础的HTML模板标记.
这个图书馆的灵感很大 lit-html,GitHub在生产中使用了一段时间。 这是独立创建的 lit-html 理由如下:
- 为了重新使用我们使用的代码 @ github/ 模板部分 它正在GitHub生产.
- 更接近于
Template Parts什么提议? 通过使用 @ github/ 模板部分 我们的目标是与模板部分提案密切配合,希望有一天不再依赖 @ github/ 模板部分。 。 。 .
基本用途
这个图书馆有一套出口,主要两个是 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><script>alert(1)</script></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 类型。您可能想要使用 建议的微量填充 构建一个不在其他浏览器中引起问题的策略.