前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载导读本文围绕microsoft/fast-element公开导出的TrustedTypesPolicy类型展开讲解它在 fast-element 模板系统中的作用、与浏览器原生 Trusted Types 平台 API 的对接方式以及如何在应用中通过自定义策略控制 HTML 注入与 DOM 写入。读完本文你将掌握TrustedTypesPolicy的准确定义、默认的fast-html策略创建逻辑、通过DOMPolicy.create()注入自定义策略的方法以及结合测试用例验证策略生效的完整链路。TrustedTypesPolicy 类型是什么在浏览器安全模型中Trusted Types 是一套用于防御 DOM XSS 的 API当站点通过 CSPContent 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 报告中。它只有一个成员成员签名说明createHTML(html: string): string将传入的 HTML 字符串标记或转换为可信内容并返回注意两点实现细节类型层面返回值声明为string这与浏览器原生TrustedTypePolicy.createHTML()返回TrustedHTML类型略有差异是 fast-element 为兼容未启用 Trusted Types 的环境而做的简化抽象运行时层面fast-element 并不要求返回值必须是原生TrustedHTML对象它只负责把字符串交给该回调处理。fast-element 如何使用 TrustedTypesPolicyTrustedTypesPolicy在 fast-element 中有两处核心消费点都位于模板与 DOM 交互的边界上。1. 模块级默认策略fast-html在 dom.ts 中fast-element 在模块加载时立即创建默认策略fastTrustedTypeconst 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?: PartialDOMGuards; };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 安全模型的关键衔接点它统一描述了接受 HTML 字符串、产出可信内容的策略契约兼容原生 Trusted Types 与无 Trusted Types 环境模块默认注册fast-html策略dom.tsDOMPolicy.create()未指定时自动复用该名称dom-policy.ts应用可通过DOMPolicyOptions.trustedType注入自定义策略配合guards对特定元素/属性的 DOM sink 进行拦截或净化例如默认的safeURL会过滤javascript:、vbscript:、data:等危险协议dom-policy.ts而script、iframe.srcdoc等高风险写入默认直接blockdom-policy.ts。在启用require-trusted-types-for script的 CSP 站点中正是经由这一契约fast-element 的模板绑定才能合法、可控地完成 HTML 写入——既满足了浏览器的 Trusted Types 强制校验又把什么 HTML 可信的决策权交还给了应用开发者。延伸阅读类型完整定义interfaces.ts默认策略创建与DOM.policydom.ts策略创建与守卫机制dom-policy.ts官方 API 报告api-report.api.mdPlaywright 测试用例dom-policy.pw.spec.ts赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐探索Web安全新边界Trusted Types 项目详解探索Web安全新边界Trusted Types 项目详解 在Web开发中数据注入攻击是一种常见的安全隐患例如XSS跨站脚本攻击。为了解决这个问题W3免费开源简历构建工具 Reactive-Resume 快速上手从本地部署到导出分享免费开源简历构建工具 Reactive Resume 快速上手从本地部署到导出分享 简历投出去石沉大海问题常常不在能力而在呈现。Reactive Resu前端后端AI 应用MCP 服务dsh-pluginDOMPurify与Trusted Types现代Web安全的最佳实践DOMPurify与Trusted Types现代Web安全的最佳实践 在当今Web应用开发中 XSS攻击防护 已成为前端安全的重中之重。DOMPurify应用安全网络安全上一篇Ente Photos 自定义域名Custom Domains完整指南用自己的域名托管分享链接下一篇Hallmark 宏结构 14 · Narrative Workflow用编号阶段与过程时间线为有真实流程的产品搭建落地页创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考