直接用template标签写组件会失效，因为template不渲染、不执行脚本、不加载资源，仅作声明式模具；其content需cloneNode(true)手动克隆插入，且内部script/style被忽略，事件和样式须克隆后动态绑定与注入。
为什么直接用 template 标签写组件会失效
因为 <template> 本身不渲染、不执行脚本、不加载资源，它只是个“模具”，浏览器不会自动把它变成可交互的 DOM。你写进去的 <script> 和 <style> 都被静默忽略——这不是 bug，是规范行为。
常见错误现象：document.querySelector('template').content.innerHTML 看起来有内容，但点击事件没响应、CSS 不生效、console.log 没输出。
- 必须手动克隆
content并插入到文档中 -
<style>要显式注入<head>或组件容器内（否则作用域外无效） -
<script>不能写在<template>里，得在克隆后动态创建并appendChild
如何让样式真正局部化且不污染全局
靠 scoped 属性或 Shadow DOM 是最直接的解法，但兼容性与复杂度差异很大。
如果目标环境支持现代浏览器（Chrome 80+ / Firefox 63+ / Safari 14+），优先用 attachShadow({mode: 'closed'})。它天然隔离样式、事件和查询，连 querySelector 都查不到内部节点。
立即学习“前端免费学习笔记（深入）”；
- 不要用
{mode: 'open'}—— 外部 JS 可以随意篡改 shadow root，失去封装意义 - 避免在 shadow root 中直接写
<style>标签：CSSOM 注入更可控，也方便复用变量 - 若需 fallback 到 light DOM，用
:host和:host-context()控制外层上下文样式，而不是靠 class 堆砌
怎样让组件接收属性并响应更新
HTML 自定义元素（customElements.define）是唯一标准路径。纯 <template> + JS 手动挂载无法监听属性变更，除非你自己实现 MutationObserver。
关键点不在“怎么渲染”，而在“什么时候重渲染”。原生 attributeChangedCallback 只触发字符串变化，数值/对象/布尔值都要自己 parse 和深比较。
- 声明
observedAttributes静态 getter，列出要监听的 attribute 名（如['count', 'disabled']） - 在
attributeChangedCallback里用JSON.parse(attrValue)处理 JSON 字符串传参（比如data-config='{"size":"large"}'） - 对布尔属性（如
disabled），检查newValue === null表示存在即 true，oldValue !== null && newValue === null表示移除
打包时如何确保组件真正“自包含”
所谓自包含，不是指单个文件，而是运行时不依赖外部构建产物或全局变量。很多“独立组件”在 vite/webpack 下跑得好，放到纯 HTML 里就报 defineCustomElement is not defined，本质是缺少注册逻辑和 polyfill。
- 用
export default class MyButton extends HTMLElement写类，最后加customElements.define('my-button', MyButton)—— 这行不能省，也不能延迟执行 - 如果要用 ES modules，确保 script 标签带
type="module"，且路径为相对或绝对 URL（import不支持 bare specifier） - IE11 或旧安卓 WebView？必须引入
@webcomponents/custom-elements和@webcomponents/template，且 polyfill 要在 define 前加载
最易被忽略的是资源路径：组件内图片、字体用相对路径，在单独 HTML 中可能 404；建议统一用 new URL('./icon.svg', import.meta.url) 构造，这是目前最稳的方案。
