企业官网建设流程全解析

• 前端
• UI组件

导读

本文围绕@microsoft/fast-element公开导出的TrustedTypesPolicy类型展开，讲解它在 fast-element 模板系统中的作用、与浏览器原生 Trusted Types 平台 API 的对接方式，以及如何在应用中通过自定义策略控制 HTML 注入与 DOM 写入。读完本文，你将掌握TrustedTypesPolicy的准确定义、默认的fast-html策略创建逻辑、通过DOMPolicy.create()注入自定义策略的方法，以及结合测试用例验证策略生效的完整链路。

TrustedTypesPolicy 类型是什么

在浏览器安全模型中，Trusted Types 是一套用于防御 DOM XSS 的 API：当站点通过 CSP（Content Security Policy）开启require-trusted-types-for 'script'后，浏览器会拦截所有以字符串形式写入innerHTML、document.write、script.src等危险 DOM sink 的操作，要求开发者必须经由名为"策略"（policy）的对象显式创建受信数据。

@microsoft/fast-element为此定义了一个轻量类型别名TrustedTypesPolicy，用于描述"可用于标准 trustedTypes 平台 API 的策略"：

export type TrustedTypesPolicy = { createHTML(html: string): string; };

该类型定义位于 interfaces.ts，公开导出（@public），并同时出现在 api-report.api.md 的正式 API 报告中。它只有一个成员：

注意两点实现细节：

• 类型层面：返回值声明为string，这与浏览器原生TrustedTypePolicy.createHTML()返回TrustedHTML类型略有差异，是 fast-element 为兼容"未启用 Trusted Types 的环境"而做的简化抽象；
• 运行时层面：fast-element 并不要求返回值必须是原生TrustedHTML对象，它只负责把字符串交给该回调处理。

fast-element 如何使用 TrustedTypesPolicy

TrustedTypesPolicy在 fast-element 中有两处核心消费点，都位于模板与 DOM 交互的边界上。

1. 模块级默认策略：fast-html

在 dom.ts 中，fast-element 在模块加载时立即创建默认策略fastTrustedType：

const createHTML = html => html; const fastTrustedType: TrustedTypesPolicy = globalThis.trustedTypes ? globalThis.trustedTypes.createPolicy("fast-html", { createHTML }) : { createHTML };

其逻辑是：

• 若运行环境存在globalThis.trustedTypes（即浏览器已支持 Trusted Types），则调用trustedTypes.createPolicy("fast-html", { createHTML })注册名为fast-html的原生策略；
• 否则退化为普通对象{ createHTML }，createHTML直接原样返回字符串，保证在无 Trusted Types 的环境中行为一致。

从源码结构看，该策略名fast-html是固定常量，这也被 dom-policy.pw.spec.ts 中的测试直接验证：拦截createPolicy调用后运行DOMPolicy.create()，断言策略名数组等于["fast-html", "fast-html"]。

2. DOMPolicy 的 trustedType 选项

在 dom-policy.ts 中，TrustedTypesPolicy作为创建 DOM 安全策略的选项出现：

export type DOMPolicyOptions = { /** * The trusted type to use for HTML creation. */ trustedType?: TrustedTypesPolicy; /** * The DOM guards used to override or extend the defaults. */ guards?: Partial<DOMGuards>; };

DOMPolicy.create(options)在创建策略时：

const trustedType = options.trustedType ?? createTrustedType();

即：未显式传入trustedType时，使用createTrustedType()（dom-policy.ts）生成默认策略；该函数与dom.ts中的逻辑一致，同样优先走globalThis.trustedTypes.createPolicy("fast-html", ...)。

最终生成的DOMPolicy通过createHTML(value)委托给该 trusted type 处理：

createHTML(value: string): string { return trustedType.createHTML(value); }

也就是说，TrustedTypesPolicy.createHTML是整个 DOM 写入安全链路的第一道闸门：所有经由策略生成的 HTML 都会先经过它，再流入模板绑定系统。

如何在应用中注入自定义 TrustedTypesPolicy

将自定义策略接入 fast-element 的方式非常直观，在应用启动阶段调用DOMPolicy.create()并传入trustedType即可：

import { DOMPolicy } from "@microsoft/fast-element"; // 方式一：使用浏览器原生策略（推荐，可配合 CSP） const createHTML = html => html; const nativePolicy = globalThis.trustedTypes ? globalThis.trustedTypes.createPolicy("app-fast-html", { createHTML }) : { createHTML }; const policy = DOMPolicy.create({ trustedType: nativePolicy }); // 方式二：直接传入满足 TrustedTypesPolicy 形状的普通对象 const customPolicy = DOMPolicy.create({ trustedType: { createHTML(html: string): string { // 可在写入前做净化、审计、统计等 return sanitize(html); }, }, });

对应测试 dom-policy.pw.spec.ts 验证了该路径：传入自定义createHTML（内部置位invoked标志）后调用policy.createHTML("Hello world")，断言回调确实被触发。

与 DOM.policy 的关系

DOMPolicy与全局单例DOM.policy是两个层次的概念：

• DOM.policy是模板系统默认使用的策略，可通过DOM.setPolicy()一次性替换（dom.ts），且出于安全原因只能设置一次，重复调用会抛出错误码1201 onlySetDOMPolicyOnce对应的错误；
• DOMPolicy.create()用于按需创建带自定义trustedType与guards的策略对象，可单独绑定到特定 binding（绑定工厂如 one-way.ts 均接受可选的policy?: DOMPolicy参数）。

常见误用与报错

在 debug.ts 中记录了与 trusted types 相关的调试信息：

"To bind innerHTML, you must use a TrustedTypesPolicy."（错误码1202 bindingInnerHTMLRequiresTrustedTypes）

这提示：当应用启用了 Trusted Types 但试图绑定innerHTML而未提供相应策略时，fast-element 会给出明确的错误指引。正确的做法是确保应用启动时已通过DOMPolicy.create({ trustedType })或DOM.setPolicy()提供满足TrustedTypesPolicy形状的策略。

结语：TrustedTypesPolicy 在安全体系中的位置

综合源码可以看到，TrustedTypesPolicy虽然只是一个结构极其简单的类型别名，却是 fast-element 安全模型的关键衔接点：

1. 它统一描述了"接受 HTML 字符串、产出可信内容"的策略契约，兼容原生 Trusted Types 与无 Trusted Types 环境；
2. 模块默认注册fast-html策略（dom.ts），DOMPolicy.create()未指定时自动复用该名称（dom-policy.ts）；
3. 应用可通过DOMPolicyOptions.trustedType注入自定义策略，配合guards对特定元素/属性的 DOM sink 进行拦截或净化，例如默认的safeURL会过滤javascript:、vbscript:、data:等危险协议（dom-policy.ts），而script、iframe.srcdoc等高风险写入默认直接block（dom-policy.ts）。

在启用require-trusted-types-for 'script'的 CSP 站点中，正是经由这一契约，fast-element 的模板绑定才能合法、可控地完成 HTML 写入——既满足了浏览器的 Trusted Types 强制校验，又把"什么 HTML 可信"的决策权交还给了应用开发者。

延伸阅读

• 类型完整定义：interfaces.ts
• 默认策略创建与DOM.policy：dom.ts
• 策略创建与守卫机制：dom-policy.ts
• 官方 API 报告：api-report.api.md
• Playwright 测试用例：dom-policy.pw.spec.ts

• 前端
• UI组件