如何使用HTML自定义元素构建可扩展的卡片组件-html教程-PHP中文网

必须先用customelements.define()注册卡片元素，标签名须含短横线（如card-item），类须继承htmlelement且在domcontentloaded后注册；未注册时document.createelement('card-item')无效。

如何使用html自定义元素构建可扩展的卡片组件

如何用 `customElements.define()` 注册可复用的卡片元素

直接用 document.createElement('card-item') 不会生效，必须先注册。浏览器只认已注册的自定义标签名，且名称中必须包含短横线（-），比如 card-item 合法，carditem 会报错。

注册前确保类继承 HTMLElement，否则无法挂载生命周期钩子
不能在中立即调用 customElements.define()，DOM 尚未就绪；建议放在 DOMContentLoaded 事件后或模块顶层（ESM 环境下）
若重复注册同一名字，会抛出 DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "card-item" has already been used

基础注册示例：

class CardItem extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }
  connectedCallback() {
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: block; border: 1px solid #eee; border-radius: 8px; }
        .content { padding: 16px; }
      </style><div class="content"><slot></slot></div>
    `;
  }
}
customElements.define('card-item', CardItem);

为什么必须用 `Shadow DOM` 而不是普通子节点

不用 shadowRoot，样式和结构就暴露在外，父页面的 CSS 可能意外覆盖卡片内部布局，比如全局设置了 h2 { margin: 0 }，你的卡片标题就塌了——这在多人协作或引入第三方库时极常见。

Shadow DOM 提供样式封闭性，外部 CSS 无法穿透，:host 是唯一可控入口
插槽（<slot></slot>）是内容分发核心，不写它，传进 <card-item>Hello</card-item> 的文本不会渲染
若用 { mode: 'closed' }，JavaScript 也无法从外部访问 shadowRoot，调试困难，日常开发推荐 'open'

`attributeChangedCallback` 怎么响应卡片状态变化

卡片常需根据属性切换展开/收起、禁用、主题色等状态，但 observedAttributes 必须显式声明，否则 attributeChangedCallback 根本不触发。

Html2md

使用 Readability + Turndown 将 HTML 页面转换为干净的、Agent 友好的 Markdown。去除导航栏、广告、页脚、Cookie 横幅、社交按钮等干扰元素。支持 URL...

下载

只监听字符串属性：布尔值如 expanded 实际传入的是空字符串或 "expanded"，需用 this.hasAttribute('expanded') 判断
数值属性（如 priority="2"）仍为字符串，需手动 parseInt() 或 parseFloat()
避免在回调里直接操作 shadowRoot.innerHTML，频繁重写会清空事件监听器；推荐用 this.shadowRoot.querySelector('.status').textContent = newValue

示例：

static get observedAttributes() {
  return ['expanded', 'theme'];
}
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'expanded') {
    this.shadowRoot.querySelector('.body').hidden = !this.hasAttribute('expanded');
  }
}

如何让卡片支持响应式布局与外部 CSS 控制尺寸

:host 支持大部分 CSS 属性，但不能设 display: flex 或 grid——因为它是“宿主”，不是容器。真正控制排列方式的是卡片的父容器。

用 :host([expanded]) 匹配带属性的实例，实现条件样式
允许外部通过 width、max-width、margin 控制卡片尺寸，但不要在 shadow 内设 width: 100%，否则会被父级约束截断
若需内部网格布局，应在 shadow 内部用 .container { display: grid }，而非依赖 :host
媒体查询写在 shadow 内部有效，但注意：CSS 变量（--card-padding）可从外部传入并被 :host 使用，这是跨边界通信最轻量的方式