使用Web Components API封装跨框架JS组件

作者:像素猫

时间:2026-11-16

浏览:335

介绍如何基于原生 Web Components API(Custom Elements、Shadow DOM 与 HTML Templates)封装不依赖特定前端框架的可复用 JS 组件,并详细说明属性同步、事件穿透及在原生 HTML、Vue 3 和 React 中的接入方法。

文章目录

要在 React、Vue 和原生页面之间复用同一个前端组件,可以直接使用浏览器原生提供的 Web Components API。它由 Custom Elements(自定义元素)、Shadow DOM(影子 DOM)和 HTML Templates(HTML 模板)三部分组成,不需要引入框架运行时即可注册为标准 HTML 标签。下文以封装一个可复用的复制卡片组件 <copy-box> 为例,说明如何完成接口设计、样式隔离、事件穿透以及在不同框架中的接入配置。

使用Web Components API封装跨框架JS组件
使用浏览器原生三项 API 封装的标准组件,可在不同框架中直接以 HTML 标签形式挂载

跨框架封装的核心机制

前端框架之所以难以直接互相嵌套组件,是因为各自维护了私有的虚拟 DOM 树、响应系统或渲染调度器。Web Components 绕开了框架层的差异,直接建立在浏览器 DOM 标准之上:通过 customElements.define() 注册一个带短横线的标签名后,任何框架在渲染该标签时,都只是在创建普通 DOM 节点,浏览器会自动接管它的实例化与生命周期。

为了保证组件放进不同项目后既不破坏外部页面样式,也不被外部样式覆盖,封装时通常开启 Shadow DOM(attachShadow({ mode: 'open' }))。Shadow Root 内部就像一棵封闭的子树,外部的全局 CSS 选择器(如 button { padding: 20px; })无法穿透进去,内部样式也不会泄漏到外部。同时,配合 <slot> 插槽可以把宿主传入的子节点投影到组件内部指定位置。

在跨框架通信上,组件遵循最通用的 DOM 契约:宿主向下传递数据通过 HTML 属性(Attributes)或 DOM 对象属性(Properties),组件向上通知宿主则通过原生 CustomEvent。需要注意一个关键细节:默认创建的 CustomEvent 会在 Shadow DOM 边界处停止冒泡,必须显式设置 bubbles: true 和 composed: true,外部框架的监听器才能收到事件。

使用Web Components API封装跨框架JS组件
图 1:宿主环境通过属性、插槽、CSS 变量和可穿透的 CustomEvent 与 Shadow DOM 内部交互

动手实现一个跨框架组件

下面以封装 copy-box.js 为例,完整实现一个支持文本复制、状态反馈、禁用控制和主题微调的跨框架组件。把它保存为独立的 ES Module 文件,即可直接被不同项目引入。

编写组件完整代码

为了让每次创建组件实例时不必重新解析 HTML 字符串,代码在模块顶层预先创建一个 <template> 元素,在构造函数中通过 cloneNode(true) 克隆节点树。

// copy-box.js
const template = document.createElement('template');
template.innerHTML = `
  <style>
    :host {
      display: block;
      font-family: "PingFang SC", "Microsoft YaHei", sans-serif;
      --cb-bg: #f8f9fa;
      --cb-border: #cbd5e1;
      --cb-text: #1e293b;
      --cb-accent: #477dad;
      --cb-accent-hover: #3b6891;
    }

    :host([hidden]) {
      display: none;
    }

    .box {
      display: flex;
      align-items: center;
      justify-content: space-between;
      gap: 12px;
      padding: 10px 14px;
      background-color: var(--cb-bg);
      border: 1px solid var(--cb-border);
      border-radius: 8px;
      color: var(--cb-text);
    }

    .content {
      min-width: 0;
      flex: 1;
    }

    .label {
      display: block;
      margin-bottom: 2px;
      font-size: 12px;
      color: #4f6272;
    }

    .label:empty {
      display: none;
    }

    .value {
      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
      font-size: 14px;
      word-break: break-all;
    }

    .copy-btn {
      flex-shrink: 0;
      padding: 6px 12px;
      border: none;
      border-radius: 6px;
      background-color: var(--cb-accent);
      color: #ffffff;
      font-size: 13px;
      cursor: pointer;
      transition: background-color 0.15s ease;
    }

    .copy-btn:hover:not(:disabled) {
      background-color: var(--cb-accent-hover);
    }

    .copy-btn:disabled {
      background-color: #94a3b8;
      cursor: not-allowed;
    }
  </style>
  <div class="box">
    <div class="content">
      <span class="label" part="label"></span>
      <div class="value">
        <slot></slot>
      </div>
    </div>
    <button type="button" class="copy-btn" part="button">复制</button>
  </div>
`;

export class CopyBoxElement extends HTMLElement {
  static get observedAttributes() {
    return ['label', 'value', 'disabled'];
  }

  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));

    this._labelEl = shadow.querySelector('.label');
    this._slotEl = shadow.querySelector('slot');
    this._valueEl = shadow.querySelector('.value');
    this._btnEl = shadow.querySelector('.copy-btn');
    this._resetTimer = null;

    this._handleCopy = this._handleCopy.bind(this);
  }

  get label() {
    return this.getAttribute('label') || '';
  }

  set label(val) {
    if (val === null || val === undefined || val === '') {
      this.removeAttribute('label');
    } else {
      this.setAttribute('label', String(val));
    }
  }

  get value() {
    return this.getAttribute('value') || '';
  }

  set value(val) {
    if (val === null || val === undefined) {
      this.removeAttribute('value');
    } else {
      this.setAttribute('value', String(val));
    }
  }

  get disabled() {
    return this.hasAttribute('disabled');
  }

  set disabled(val) {
    if (Boolean(val)) {
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  connectedCallback() {
    this._btnEl.addEventListener('click', this._handleCopy);
    this._render();
  }

  disconnectedCallback() {
    this._btnEl.removeEventListener('click', this._handleCopy);
    if (this._resetTimer) {
      clearTimeout(this._resetTimer);
      this._resetTimer = null;
    }
  }

  attributeChangedCallback() {
    this._render();
  }

  _render() {
    if (!this._labelEl) return;
    this._labelEl.textContent = this.label;
    this._btnEl.disabled = this.disabled;

    // 传入 value 属性时优先展示属性值,否则保留默认 slot 中的内容
    if (this.hasAttribute('value')) {
      this._valueEl.textContent = this.value;
    } else if (!this._valueEl.contains(this._slotEl)) {
      this._valueEl.textContent = '';
      this._valueEl.appendChild(this._slotEl);
    }
  }

  _getCopyText() {
    if (this.hasAttribute('value')) {
      return this.value;
    }
    const assigned = this._slotEl.assignedNodes({ flatten: true });
    return assigned.map((node) => node.textContent).join('').trim();
  }

  async _handleCopy() {
    if (this.disabled) return;
    const text = this._getCopyText();
    if (!text) return;

    try {
      await navigator.clipboard.writeText(text);
      this._btnEl.textContent = '已复制';
      clearTimeout(this._resetTimer);
      this._resetTimer = setTimeout(() => {
        this._btnEl.textContent = '复制';
      }, 1500);

      this.dispatchEvent(
        new CustomEvent('copy-success', {
          detail: { value: text },
          bubbles: true,
          composed: true
        })
      );
    } catch (err) {
      this.dispatchEvent(
        new CustomEvent('copy-error', {
          detail: { error: err },
          bubbles: true,
          composed: true
        })
      );
    }
  }
}

if (typeof window !== 'undefined' && !customElements.get('copy-box')) {
  customElements.define('copy-box', CopyBoxElement);
}

封装过程中的四个关键细节

编写上述组件时,有四处实现直接决定它在多框架环境下的稳定性:

  • Attribute 与 Property 双向同步:HTML 属性只支持字符串,而 JS 框架经常直接设置 DOM 属性(例如布尔值 el.disabled = true)。通过 getter / setter 把 JS 属性读写映射到 setAttribute / removeAttribute,再由 observedAttributes 统一触发 attributeChangedCallback,可以保证无论宿主用 HTML 模板传值还是用 JS 赋值,渲染逻辑都走同一条路径。
  • 生命周期中的监听清理:在 connectedCallback 绑定事件,在 disconnectedCallback 中移除监听并清理 setTimeout。当组件在 Vue 的 v-if 或 React 条件渲染中被频繁销毁重建时,这一步能防止定时器回调访问已卸载的节点。
  • 防重复注册检查:微前端架构或开发服务器热更新可能导致同一个组件文件被执行两次,直接调用 customElements.define 会抛出 DOMException。提前判断 !customElements.get('copy-box') 可以避免重复注册报错。
  • 剪贴板 API 的环境条件:示例中调用了 navigator.clipboard.writeText(),浏览器要求页面运行在 HTTPS 或 localhost 安全上下文中;若部署在普通 HTTP 内网地址下,该方法会拒绝执行并触发 copy-error 事件。
使用Web Components API封装跨框架JS组件
图 2:封装自定义元素的四个核心步骤,以及元素挂载前后各生命周期回调的触发顺序

在不同前端框架中接入组件

组件注册完成后,原生 HTML、Vue 和 React 都可以直接渲染 <copy-box>,但在自定义事件监听和模板编译警告处理上各有要求。

原生 HTML 页面

在普通 HTML 文件中通过 type="module" 引入脚本,即可直接使用标签并通过 addEventListener 接收事件,也可以通过 CSS 变量和 ::part(button) 覆盖局部样式。

<style>
  copy-box.theme-dark {
    --cb-bg: #f1f5f9;
    --cb-accent: #4f6272;
  }
  copy-box::part(button) {
    border-radius: 999px;
  }
</style>

<copy-box id="api-box" class="theme-dark" label="接口密钥" value="sk-demo-123456"></copy-box>
<copy-box label="安装命令">npm install @example/copy-box</copy-box>

<script type="module">
  import './copy-box.js';

  document.getElementById('api-box').addEventListener('copy-success', (event) => {
    console.log('已复制内容:', event.detail.value);
  });
</script>

Vue 3 项目

Vue 3 对自定义元素支持较为直接,模板中可以像普通组件一样绑定属性和监听自定义事件 @copy-success。唯一需要处理的是编译期警告:Vue 默认把未知标签当作 Vue 组件解析,如果在浏览器控制台看到 Failed to resolve component: copy-box,需要在构建配置中声明自定义元素匹配规则。

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 告知 Vue 编译器将 copy- 开头或包含短横线的标签视为原生自定义元素
          isCustomElement: (tag) => tag === 'copy-box'
        }
      }
    })
  ]
});
<!-- App.vue -->
<script setup>
import { ref } from 'vue';
import './copy-box.js';

const token = ref('sk-vue-987654');
const isDisabled = ref(false);

function onCopySuccess(event) {
  console.log('Vue 收到复制事件:', event.detail.value);
}
</script>

<template>
  <copy-box
    label="Vue 示例密钥"
    :value="token"
    :disabled="isDisabled"
    @copy-success="onCopySuccess"
  />
</template>

React 项目

接入 React 时需要注意版本差异。在 React 18 及更早版本中,React 的合成事件系统不会自动把 onCopySuccess 这类驼峰 JSX 属性映射成原生的 copy-success 事件监听,同时非字符串类型的属性(例如对象或数组)直接写在 JSX 上会被转成字符串。标准做法是通过 useRef 获取 DOM 节点引用,再在 useEffect 中使用 addEventListener 绑定自定义事件。

// CopyCard.jsx(兼容 React 18 及更早版本)
import { useEffect, useRef } from 'react';
import './copy-box.js';

export function CopyCard({ label, value, disabled = false, onCopied }) {
  const boxRef = useRef(null);

  useEffect(() => {
    const el = boxRef.current;
    if (!el || !onCopied) return;

    const handler = (event) => onCopied(event.detail.value);
    el.addEventListener('copy-success', handler);
    return () => el.removeEventListener('copy-success', handler);
  }, [onCopied]);

  useEffect(() => {
    if (boxRef.current) {
      boxRef.current.disabled = disabled;
    }
  }, [disabled]);

  return <copy-box ref={boxRef} label={label} value={value} />;
}
版本提示:React 19 在官方发布中新增了对 Custom Elements 属性分配和自定义事件绑定的原生支持;实际项目是否需要保留上述 useRef 适配层,应根据项目当前使用的 React 主版本号决定。
使用Web Components API封装跨框架JS组件
图 3:原生 HTML、Vue 3 与 React 18 在属性传递、事件绑定和构建配置上的实际差异

类型提示、服务端渲染与使用边界

把组件发布到团队内部仓库或 npm 包时,除了提供 ES Module 入口文件,还常会遇到 TypeScript 类型提示、SSR 兼容性以及表单行为三类边界问题。

场景 容易出现的问题 处理方式
TypeScript 模板校验 TSX 或 Vue 模板中报错 Property 'copy-box' does not exist on type 'JSX.IntrinsicElements' 在 .d.ts 文件中扩展 HTMLElementTagNameMap 与框架对应的元素类型声明(如 React 的 JSX.IntrinsicElements)。
SSR 服务端渲染(Next.js / Nuxt) Node.js 环境没有 HTMLElement 和 customElements,直接导入会抛出 ReferenceError 把组件文件改为在客户端挂载钩子中动态导入(import('./copy-box.js')),或在组件内部先判断 typeof window !== 'undefined' 且推迟类继承求值。
原生表单提交 Shadow DOM 内部的 <input> 不会被外部 <form> 的 FormData 自动收集 若封装的是输入型组件,需声明 static formAssociated = true 并调用 this.attachInternals() 关联表单值。
宿主需要修改内部细节样式 外部 CSS 类名无法直接选中 Shadow Root 里的按钮或标题 预留 CSS 自定义属性(如 --cb-accent)并在关键节点上添加 part="button",避免放弃 Shadow DOM。

需要补充说明的是,在 TypeScript 中如果组件只在部分页面按需引入,最稳妥的做法是把类型声明放在独立的 copy-box.d.ts 中并在包的 package.json 里通过 "types" 字段导出:

// copy-box.d.ts
import type { CopyBoxElement } from './copy-box.js';

declare global {
  interface HTMLElementTagNameMap {
    'copy-box': CopyBoxElement;
  }
}
使用Web Components API封装跨框架JS组件
图 4:跨框架 Web Components 组件从接口设计到多宿主上线验证的完整检查路径

如果组件本身交互独立、对外参数简单(例如播放器、代码复制卡片、通用弹窗或状态徽章),采用上述标准即可同时覆盖原生页面与主流框架;如果组件高度依赖复杂嵌套状态或需要大量表单联动,则要提前评估 ElementInternals 的集成成本再决定是否下沉到 Web Components 层。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章