customElements.define()仅注册元素，不自动绑定事件或响应属性变化；须在connectedCallback中获取shadowRoot并手动添加事件监听器，声明observedAttributes并在attributeChangedCallback中处理变更。

customElements.define()注册后交互逻辑必须手动绑定

注册自定义标签只是让浏览器识别新元素，customElements.define()本身不注入任何事件或响应式行为。所有点击、输入、状态变更都得在类内部显式处理。

常见错误是以为加了onclick属性或写个button就能自动响应——实际在 Shadow DOM 里，外部绑定的事件监听器根本触达不到内部节点。

• 在 connectedCallback() 中获取 this.shadowRoot 后再查子元素并调用 addEventListener()
• 避免在 constructor() 里绑定事件：此时 shadowRoot 已创建，但 DOM 尚未挂载，querySelector 会返回 null
• 若需响应属性变化（如 disabled 或 loading），必须在 observedAttributes 静态 getter 中声明，并在 attributeChangedCallback() 里做具体处理

Shadow DOM 中读取和透传 CSS 自定义属性

CSS 变量（如 --primary-color）不会自动穿透 Shadow DOM 边界。组件想用主题色、字号等变量，必须主动从 light DOM 拿，再赋值给内部样式或内联 style。

典型错误是直接在 shadowRoot 的 <style> 里写 color: var(--primary-color)，结果始终 fallback 到初始值——因为该变量没在 shadowRoot 范围内声明。

立即学习“前端免费学习笔记（深入）”；

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

• 推荐方式：在 connectedCallback() 或 attributeChangedCallback() 中调用 getComputedStyle(this).getPropertyValue('--primary-color') 获取值
• 把拿到的值设为内部元素的 style.color 或通过 setAttribute('style', ...) 注入，确保实时生效
• 不要在每次渲染时重复调用 getComputedStyle；可缓存值，或监听 attributeChangedCallback 触发更新

如何封装带状态管理的复杂交互组件（如折叠面板、表单控件）

HTML 组件化不提供内置状态系统。你要自己维护 this.state、触发重渲染、同步属性与 DOM，否则用户操作后界面不会更新。

比如一个可展开/收起的面板，点击后只改了 this._isOpen，但没更新 shadowRoot.innerHTML 或 class，视觉上就“没反应”。

• 在事件处理器中修改内部状态后，立即调用私有方法（如 this._render()）刷新 UI
• _render() 应完全基于当前 this.state 和 this.attributes 重建结构，避免局部 patch，减少状态不一致风险
• 对频繁触发的操作（如输入框 input 事件），考虑节流或使用 requestIdleCallback 避免卡顿
• 注意生命周期清理：在 disconnectedCallback() 中移除事件监听器，尤其委托到 shadowRoot 的监听器，否则容易内存泄漏

组件间通信：属性、事件、slot 的分工边界

别试图用属性传函数，也别在 slot 里塞逻辑——HTML 组件化只支持字符串属性、自定义事件和内容投影三种标准通路。

常见误区是把回调函数作为属性传进组件，结果发现接收到的是 [object Function] 字符串，因为属性值只能是字符串。

• 配置类数据走属性（label="用户名"、required），布尔属性存在即 true
• 向外通知用自定义事件：this.dispatchEvent(new CustomEvent('change', { detail: { value } }))，父级用 addEventListener('change', ...) 监听
• slot 仅用于结构内容分发，不承载逻辑；如需定制按钮行为，应结合属性控制显隐 + 事件通知，而非让父级往 slot 里塞带 onclick 的 HTML
• 跨组件状态共享？别绕开 DOM 树搞全局 store；优先用事件冒泡 + 父组件协调，或通过 document.querySelector 显式查找（仅限强耦合场景）

组件最难的部分不是写结构，而是守住边界：CSS 变量不自动透传、事件不自动绑定、状态不自动同步。每个“应该自动”的地方，恰恰是需要你亲手补全的缝隙。