Web Components 实战：从自定义元素到跨框架复用

// 最小可用的自定义元素：名字必须含连字符，避免与内置标签冲突
class MyCounter extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from custom element';
  }
}

customElements.define('my-counter', MyCounter);

<!-- 之后在任何页面、任何框架里都这样用 -->
<my-counter></my-counter>

class StarRating extends HTMLElement {
  static observedAttributes = ['value'];

  // constructor 只做状态初始化，规范禁止读取子节点与属性
  constructor() {
    super();
    this._value = 0;
    this._cleanup = null;
  }

  connectedCallback() {
    if (!this.shadowRoot) {
      this.attachShadow({ mode: 'open' }).innerHTML = `
        <style>
          :host { display: inline-flex; gap: 4px; cursor: pointer; }
          .star { color: #c8c8c8; }
          .star.on { color: #f5a623; }
        </style>
        <span class="star">★</span><span class="star">★</span>
        <span class="star">★</span><span class="star">★</span>
        <span class="star">★</span>`;
    }
    this._render();

    // disconnectedCallback 一定能配对清理
    const onClick = (e) => {
      const stars = [...this.shadowRoot.querySelectorAll('.star')];
      const next = stars.indexOf(e.target) + 1;
      this.value = next || 1;
      this.dispatchEvent(new CustomEvent('change', {
        detail: { value: this._value },
        bubbles: true,    // 冒泡到父级
        composed: true,   // 穿过 shadow 边界
      }));
    };
    this.shadowRoot.addEventListener('click', onClick);
    this._cleanup = () => this.shadowRoot.removeEventListener('click', onClick);
  }

  disconnectedCallback() {
    this._cleanup?.();
    this._cleanup = null;
  }

  attributeChangedCallback(name, _old, next) {
    if (name !== 'value') return;
    this._value = Number(next) || 0;
    this._render();
  }

  // property 入口：外部 JS 直接读写 .value
  get value() { return this._value; }
  set value(v) {
    this._value = v;
    this.setAttribute('value', String(v)); // 反射回 attribute，CSS 选择器可见
  }

  _render() {
    if (!this.shadowRoot) return;
    const stars = [...this.shadowRoot.querySelectorAll('.star')];
    stars.forEach((s, i) => s.classList.toggle('on', i < this._value));
  }
}

customElements.define('star-rating', StarRating);

<user-card user-id="42">
  <span slot="title">高级会员</span>
  <p>这里是默认插槽内容，进无名 slot</p>
</user-card>

// 组件内部：具名插槽对位，未命名的落进默认 slot
class UserCard extends HTMLElement {
  connectedCallback() {
    this.attachShadow({ mode: 'open' }).innerHTML = `
      <style>
        :host { display: block; border: 1px solid #ddd; padding: 8px; }
        ::slotted([slot='title']) { font-weight: 600; }
        slot { color: #666; }
      </style>
      <div part="title"><slot name="title">默认标题</slot></div>
      <div><slot>无内容时的回退文案</slot></div>`;
  }
}
customElements.define('user-card', UserCard);

const slot = this.shadowRoot.querySelector('slot');
slot.addEventListener('slotchange', () => {
  const nodes = slot.assignedNodes(); // 拿到实际分发进来的节点
  this._renderCount(nodes.length);
});

/* 使用方：只通过变量与 ::part 定制，不用知道内部结构 */
star-rating {
  --star-size: 24px;
}

star-rating::part(title) {
  color: #333;
}

<!-- 组件内部需配合 exportparts，把内部 part 再导出 -->
<div part="title" exportparts="title">…</div>

this.dispatchEvent(new CustomEvent('change', {
  detail: { value: this._value },
  bubbles: true,   // 沿 DOM 树向上
  composed: true,  // 穿过 shadow root 边界
}));

// React 18 及以前：对象 props 会变成 "[object Object]" 字符串，事件必须手动绑
function App() {
  const ref = useRef(null);

  useEffect(() => {
    const el = ref.current;
    const onChange = (e) => setRating(e.detail.value);
    el.addEventListener('change', onChange);
    return () => el.removeEventListener('change', onChange);
  }, []);

  return <star-rating ref={ref} value="3"></star-rating>;
}

// React 19 起：非字符串 prop 直接按 property 设置
function App() {
  return <star-rating value={3} max-value={5}></star-rating>;
}

// Vue 3.2+：同一套 .vue 组件可以编译成 Web Component 输出
import { defineCustomElement } from 'vue';
import RatingCard from './RatingCard.ce.vue';

customElements.define('rating-card', defineCustomElement(RatingCard));

---
// src/components/StarCounter.astro —— 默认输出零 JS 的静态 HTML
const { initial = 0 } = Astro.props;
---
<star-counter data-initial={initial}>
  <!-- 无 JS 时仍然可见的回退内容 -->
  <span slot="label">收藏数</span>
</star-counter>

<script>
  class StarCounter extends HTMLElement {
    connectedCallback() {
      const n = Number(this.dataset.initial || 0);
      this.querySelector('[slot="label"]').append(`：${n}`);
    }
  }
  customElements.define('star-counter', StarCounter);
</script>