HTML模板与自定义元素实现组件化封装-html教程-PHP中文网

customelements.define()报“not a valid custom element name”是因为html规范强制要求自定义标签名必须包含至少一个ascii短横线且全小写，如user-card合法，而myheader、usercard、sidebar因缺短横线或含大写等违反规范被浏览器硬拦截拒绝注册。

html模板与自定义元素实现组件化封装

customElements.define() 为什么报 “not a valid custom element name”

因为浏览器强制要求自定义标签名必须含短横线，否则直接拒绝注册。customElements.define() 遇到 myheader、UserCard 或 sidebar 这类名字，会抛出 Failed to execute 'define' on 'CustomElementRegistry': The name "xxx" is not a valid custom element name。

这不是兼容性问题，是 HTML 规范层的硬拦截——目的是让解析器能无歧义区分原生标签（如 header、article）和自定义扩展。

合法： main-layout、user-card、responsive-grid
非法：header（原生已有）、MyCard（无短横线+大驼峰）、usercard（小写无短横线）
别试图用 data- 前缀绕过，data-user-card 也不是合法标签名

布局类组件该不该用 Shadow DOM

大多数布局模板（比如三栏、顶部导航+主内容、响应式栅格）**不该用** Shadow DOM。它的核心代价是样式穿透被切断，外部 CSS 写 main-layout .content 就完全失效。

布局组件要的是结构复用 + 语义化 + 外部可控，不是强封装。强行加 this.attachShadow({ mode: 'open' }) 反而让下游开发者没法调整 padding、margin、颜色等基础表现。

适合 Shadow DOM 的：按钮、输入框、模态框等自带行为与样式的 UI 控件
布局组件更推荐直接操作 this.innerHTML 或 this.append()，保持样式作用域开放
若真需局部样式隔离（如默认页头背景），只在内部加一层 <style></style>，不要整个容器 Shadow

attributeChangedCallback 为什么没触发

它只响应 HTML 属性变更（setAttribute()、removeAttribute()、初始 HTML 中写的属性），对 JS 属性赋值（el.mode = 'dark'）完全静默。

Article To Html

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

下载

常见误判是以为监听了 mode 就能捕获所有修改，结果用户代码里写 myLayout.mode = 'mobile'，UI 却毫无反应。

必须显式声明 static get observedAttributes() { return ['mode', 'breakpoint']; }
首次初始化时 oldValue 是 null，别直接用 === 'old' 判断，改用 oldValue !== newValue
布尔属性（如 collapsed）的 newValue 是字符串 "true" 或 null，需手动转布尔：!!newValue
若需支持 JS 属性同步，得在 setter 里补 this.setAttribute('mode', value)

template.content.cloneNode(true) 为什么不能直接用 content

<template></template> 的 content 是一个离线 DocumentFragment，直接 appendChild(content) 会把节点“移动”过去，只有一份；后续再用就空了。直接 innerHTML = template.content 会丢失事件绑定、破坏 ID 唯一性、甚至静默失败。

正确做法永远是克隆：用 template.content.cloneNode(true) 得到一份全新副本，再填充数据、绑定事件、插入 DOM。

<template id="card"><div class="card"> <h3 data-bind="title"></h3> <p data-bind="desc"></p> </div></template>
克隆后遍历找 data-bind，写入对应字段：instance.querySelector('[data-bind="title"]').textContent = data.title
内联 onclick 在克隆后无效，改用 instance.querySelector('button').addEventListener('click', handler)

真正难的不是写出来，而是想清楚：这个组件到底需要多强的封装边界？布局结构要不要被外部样式控制？属性变更是否必须实时响应？这些判断比语法细节更能决定最终能否落地。