真正可集成的起点是<template id="xxx">：它不渲染、不执行脚本、不触发资源加载，纯结构声明；模板须放<body>内、内容为合法HTML片段、占位符用data-bind属性；组件初始化须通过工厂函数显式控制生命周期；样式隔离依赖Shadow DOM；第三方脚本需Promise化加载并提供降级fallback。
用 <template> 声明结构，别直接写死在 DOM 里
直接把第三方组件 HTML 写进 <body> 或某个容器里，后续想复用、替换、传参就全得靠 JS 字符串拼接或正则替换——极易出错且不可维护。真正可集成的起点是 <template id="xxx">：它不渲染、不执行脚本、不触发资源加载，纯结构声明。
常见错误是把 <template> 放在 <head> 里（部分浏览器会忽略），或给它加 class/id 试图用 CSS 选中——它不在主 DOM 树中，选择器无效。
- 模板内容必须是合法 HTML 片段，不能有顶层文本节点（比如开头换行或空格）
- 占位符统一用
data-bind属性，例如<h2 data-bind="title"></h2>，避免和框架冲突 - 如果组件含
<slot>，确保父容器用<my-component><span slot="header">自定义头</span></my-component>方式传入，而不是往 template 里硬塞
组件初始化必须走 JS 实例化，别依赖全局变量或自动执行
第三方组件一旦被多个页面或模块同时引入，靠 window.xxxInit() 或文档就绪后自动扫描 data-component 的方式极易冲突——你改了，别人没改；你升级了，旧版本还在跑。
可靠做法是暴露一个工厂函数，由调用方显式控制生命周期：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
function createAlert({ type = 'info', message, duration = 3000 }) {
const tpl = document.getElementById('alert-template').content.cloneNode(true);
tpl.querySelector('[data-bind="message"]').textContent = message;
tpl.querySelector('.alert').className += ` alert-${type}`;
const el = document.createElement('div');
el.appendChild(tpl);
setTimeout(() => el.remove(), duration);
return el;
}
- 所有参数必须有默认值，避免调用时漏传导致崩溃
- 返回值要是完整 DOM 节点，不是字符串或 fragment——否则插入位置难控制
- 内部不操作
document.body，由调用方决定挂载点，比如container.appendChild(createAlert(...))
样式隔离靠 Shadow DOM，别指望 class 前缀或命名约定
用 my-alert、third-party-modal 这类前缀防冲突？实际项目里只要第三方库自己带 .btn、.container，你的全局 CSS 就可能被覆盖或反向影响它。唯一能真正隔离的只有 Shadow DOM。
但注意：Shadow DOM 不是万能胶。如果组件本身依赖外部样式（比如 Bootstrap 的 .table 类），强行塞进 shadow root 后这些样式就失效了——它只认自己内部 <style> 或 <link> 引入的 CSS。
- 用
this.attachShadow({ mode: 'open' })，别用'closed'——调试时看不到内部结构 - CSS 必须通过
this.shadowRoot.innerHTML = '<style>...</style>...'或const link = document.createElement('link'); link.rel = 'stylesheet'; link.href = '/css/xxx.css'; this.shadowRoot.appendChild(link);注入 - 若第三方组件含内联
<script>，innerHTML不会执行，需手动提取并eval()或import()，但要确认 CSP 允许
CDN 加载失败要有降级 fallback，别让整个页面卡住
一行 <script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script> 看似简洁，但网络抖动、CDN 限流、域名污染都可能导致 JS 加载失败，而你的图表区域变成空白——用户根本不知道发生了什么。
真正可集成的方案必须内置加载状态与失败兜底：
function loadChartJS() {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/chart.js@4';
script.onload = () => resolve(window.Chart);
script.onerror = () => reject(new Error('Chart.js load failed'));
document.head.appendChild(script);
});
}
- Promise 化后可配合
async/await控制 UI 状态，比如显示 loading spinner 或 “图表暂不可用” 提示 - fallback 不一定是“不显示”，可以是纯 HTML 表格替代、静态图片、甚至本地缓存的 minified 版本（需提前打包）
- 不要在
<head>里写多个第三方 script 标签拼顺序——异步加载下执行顺序不可控，用 JS 动态加载才能保证依赖链
最难处理的其实是第三方组件的“隐式依赖”：比如某个 UI 库要求必须先加载 Popper.js，而它的文档没写清楚；或者图标字体路径写死为 /fonts/fa-solid-900.woff2，但你 CDN 地址是 https://cdnjs.cloudflare.com/...。这类问题不会报错，只会静默失效——得靠 DevTools 的 Network 面板逐个核对请求路径，而不是猜。
