一、为啥要把Bootstrap和Web Components凑一起用

做前端开发的人，应该都用过Bootstrap吧？就是那个能快速出好看页面的UI库，按钮、表格、弹窗啥的都有现成的，不用自己从零写样式。但你有没有碰到过这种麻烦：项目里同时用了好几个组件库，或者自己写的组件和Bootstrap混着用，结果样式乱了？比如自己写的自定义按钮，本来想让它和Bootstrap的按钮风格统一，结果要么Bootstrap的样式把自己的按钮覆盖了，要么自己的样式把Bootstrap的改乱了，互相抢样式控制权。

还有一种情况，就是做那种可以在多个项目里复用的组件包，比如公司内部的组件库，想让组件拿过去就能用，不用用户再额外引入一堆样式。要是直接把Bootstrap的样式写在组件里，用户项目里已经有Bootstrap的话，就会重复引入，导致样式冲突；要是不写，组件拿过去又没样式。

这时候Web Components就派上用场了。简单说，Web Components是浏览器原生支持的一套技术，能把HTML、CSS、JS打包成一个独立的组件，就像一个黑盒子，内部的样式和结构不会被外面的页面影响，外面的样式也不会随便跑到组件内部去。把Bootstrap的组件用Web Components包起来，既能保留Bootstrap的现成样式，又能避免和外部的样式冲突，一举两得。

不过这里有个小问题：有时候我们又想让组件内部的某些样式能被外部控制，比如用户想改改按钮的颜色、大小，或者想给组件加个自定义的类名来调整样式。但Web Components里用了Shadow DOM的话，默认外面的样式是穿不进去的，这时候就需要一个“样式穿透的白名单”，也就是只允许特定的样式能进组件内部，其他的还是保持隔离。

二、核心技术拆解：先搞懂Web Components和Shadow DOM

要理解后面的内容，得先把两个核心技术弄明白，不用记复杂概念，用大白话讲清楚就行。

2.1 Web Components是什么

Web Components是浏览器原生的组件规范，主要由三部分组成：Custom Elements（自定义元素）、Shadow DOM（影子DOM）、HTML Templates（HTML模板）。

Custom Elements就是允许你自己定义HTML标签，比如不用<div class="btn">，直接用<my-btn>，标签名得带个横杠，这是浏览器的规定，避免和原生标签重名。

HTML Templates是用来写组件内部的HTML结构的，它不会直接显示在页面上，得用JS把它取出来，放到自定义元素里。

Shadow DOM是核心，它会给组件创建一个独立的DOM树，和页面的主DOM树隔离开。比如你写了一个<my-btn>组件，它的内部结构（比如<button class="btn btn-primary">）不会出现在页面的主DOM里，而是藏在Shadow DOM里，这样外面的CSS选择器（比如.btn）默认是找不到它的，也就不会影响它的样式。

2.2 Shadow DOM的样式隔离和穿透限制

默认情况下，Shadow DOM的样式是双向隔离的：

  1. 外部的样式穿不进Shadow DOM：比如页面里写了.btn { color: red; }，<my-btn>内部的.btn不会变红，因为选择器找不到Shadow DOM里的元素。
  2. Shadow DOM内部的样式也不会影响外部：比如<my-btn>内部写了.box { background: blue; }，页面主DOM里的.box也不会变蓝。

这种隔离性很有用，能避免样式冲突，但有时候也太死板了。比如用户想改<my-btn>的颜色，或者想给组件加个自定义的主题类，这时候就需要让特定的样式能穿进Shadow DOM。

三、样式穿透的白名单方案：只让允许的样式进去

要实现样式穿透的白名单，核心思路是：我们在组件内部主动“接收”外部传进来的特定样式，而不是让所有外部样式都能随便进去。具体怎么做呢？主要有两种常用的方法，各有优劣。

3.1 方法一：用CSS变量（Custom Properties）做白名单

CSS变量是CSS里的一种自定义属性，比如你可以定义--btn-color: red;，然后在样式里用color: var(--btn-color);来引用它。它的好处是天然能穿越Shadow DOM的边界，因为浏览器会把CSS变量当成一种“全局”的属性，不管在主DOM还是Shadow DOM里，只要是同一个元素，就能继承到这个变量。

那怎么用它做白名单呢？很简单：我们在组件内部的Bootstrap样式里，把需要允许外部修改的属性，都改成用CSS变量来控制，外部只要修改这些变量的值，就能调整组件的样式，其他没被改成变量的属性，还是保持隔离。

3.1.1 具体实现步骤（含完整示例）

我们以Bootstrap的按钮组件为例，把它封装成一个自定义元素<my-btn>，允许外部修改按钮的颜色、大小，其他样式保持不变。

首先，我们需要引入Bootstrap的CSS，然后把Bootstrap的按钮样式里需要暴露的属性改成CSS变量。

技术栈：原生Web Components + Bootstrap 5

第一步，先写HTML模板和自定义元素的JS代码：

// 先引入Bootstrap的CSS，这里我们用CDN的方式
const bootstrapLink = document.createElement('link');
bootstrapLink.rel = 'stylesheet';
bootstrapLink.href = 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css';
document.head.appendChild(bootstrapLink);

// 定义自定义元素<my-btn>
class MyBtn extends HTMLElement {
  constructor() {
    super();
    // 创建Shadow DOM，开启隔离模式
    this.attachShadow({ mode: 'open' });

    // 把Bootstrap的按钮样式里的可修改属性改成CSS变量
    // 这里我们重写Bootstrap的.btn样式，把需要暴露的属性用变量控制
    const style = document.createElement('style');
    style.textContent = `
      /* 重写Bootstrap的基础按钮样式，把可修改的属性换成CSS变量 */
      .btn {
        /* 允许外部修改的属性：背景色、文字颜色、边框、内边距、圆角 */
        background-color: var(--btn-bg, var(--bs-primary)); /* 默认用Bootstrap的主色 */
        color: var(--btn-color, #fff);
        border: var(--btn-border, 1px solid transparent);
        padding: var(--btn-padding, 0.375rem 0.75rem);
        border-radius: var(--btn-radius, 0.375rem);
        /* 其他Bootstrap的样式保持不变，比如字体、行高、过渡效果等 */
        font-size: 1rem;
        line-height: 1.5;
        transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out;
      }
      /* 重写按钮的hover样式，也允许外部修改 */
      .btn:hover {
        background-color: var(--btn-hover-bg, var(--bs-primary-dark));
        color: var(--btn-hover-color, #fff);
      }
    `;

    // 把样式和按钮结构加到Shadow DOM里
    this.shadowRoot.appendChild(style);
    this.shadowRoot.innerHTML += `<button class="btn">${this.textContent}</button>`;
  }
}

// 注册自定义元素
customElements.define('my-btn', MyBtn);

第二步，在页面里使用<my-btn>，并修改允许的样式：

<!-- 页面主DOM里的样式，只修改我们定义的CSS变量 -->
<style>
  /* 给所有<my-btn>设置自定义样式 */
  my-btn {
    --btn-bg: #ff6b6b; /* 背景色改成红色 */
    --btn-hover-bg: #ff5252; /* hover时的背景色改成更深的红色 */
    --btn-padding: 0.5rem 1rem; /* 内边距调大一点 */
  }
  /* 给特定的<my-btn>单独设置样式 */
  .special-btn {
    --btn-bg: #4ecdc4; /* 背景色改成青绿色 */
    --btn-radius: 0.5rem; /* 圆角更大 */
  }
</style>

<!-- 使用自定义按钮 -->
<my-btn>默认按钮</my-btn>
<my-btn class="special-btn">特殊按钮</my-btn>

这个例子里，只有--btn-bg、--btn-hover-bg、--btn-padding、--btn-radius这些我们主动暴露的CSS变量，才能被外部修改，其他样式（比如按钮的字体大小、过渡效果）还是由组件内部控制，不会被外部影响，完美实现了白名单的效果。

3.2 方法二：用::part()伪元素做白名单

CSS的::part()伪元素是专门为Shadow DOM设计的，用来让组件内部的特定元素能被外部选择器选中。比如你在组件内部的元素上加上part="btn"属性，外部就可以用my-btn::part(btn)来选择这个元素，给它加样式。

这种方法的好处是，你可以直接给组件内部的元素加任何样式，不用提前把属性改成变量，更灵活；但坏处是，如果你暴露的元素太多，可能会导致样式失控，所以得严格控制暴露的part的数量。

3.2.1 具体实现步骤（含完整示例）

还是以Bootstrap的按钮为例，这次用::part()来实现白名单。

技术栈：原生Web Components + Bootstrap 5

第一步，写自定义元素的JS代码：

// 同样先引入Bootstrap的CSS
const bootstrapLink = document.createElement('link');
bootstrapLink.rel = 'stylesheet';
bootstrapLink.href = 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css';
document.head.appendChild(bootstrapLink);

class MyBtn extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // 只需要引入Bootstrap的样式，不用重写
    const style = document.createElement('style');
    style.textContent = `@import url('https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css');`;
    this.shadowRoot.appendChild(style);

    // 给内部的按钮加上part属性，暴露出去
    this.shadowRoot.innerHTML += `<button class="btn btn-primary" part="btn">${this.textContent}</button>`;
  }
}

customElements.define('my-btn', MyBtn);

第二步，在页面里用::part()给按钮加样式：

<style>
  /* 用::part()选择组件内部的按钮，只允许修改暴露的btn部分 */
  my-btn::part(btn) {
    background-color: #ff6b6b;
    border-radius: 0.5rem;
    padding: 0.5rem 1rem;
  }
  /* 给特定的按钮加样式 */
  .special-btn::part(btn) {
    background-color: #4ecdc4;
  }
</style>

<my-btn>默认按钮</my-btn>
<my-btn class="special-btn">特殊按钮</my-btn>

这个例子里，只有内部的按钮（part="btn"）能被外部选中，其他元素（比如如果组件内部还有一个<span>）是选不到的，也实现了白名单的效果。

四、两种方法的对比和适用场景

两种方法各有优劣，适合不同的场景，我们来对比一下：

4.1 CSS变量方案

优点：

  • 更安全：只有你主动暴露的属性才能被修改，不会出现外部随便改组件内部样式的情况，适合做通用组件库，要求组件稳定性高的场景。
  • 更容易维护：所有可修改的属性都集中在组件内部的样式里，外部怎么改都不会影响组件的结构和其他样式。
  • 支持主题化：可以一次性给所有组件设置全局的CSS变量，比如--btn-bg: #ff6b6b，所有用了这个变量的按钮都会自动应用，适合做主题切换。

缺点：

  • 不够灵活：需要提前把所有可能被修改的属性都改成CSS变量，如果你想加一个新的可修改属性，得先改组件内部的样式。
  • 代码量稍大：需要重写Bootstrap的样式，把属性替换成变量。

适用场景：公司内部的通用组件库、需要主题切换的项目、对组件稳定性要求高的场景。

4.2 ::part()方案

优点：

  • 更灵活：不用提前定义变量，外部可以直接给暴露的元素加任何样式，适合快速开发，或者用户需要高度自定义组件的场景。
  • 代码量小：不用重写Bootstrap的样式，只需要加个part属性就行。

缺点：

  • 安全性稍差：如果暴露的元素太多，或者暴露的元素内部有嵌套的结构，外部可能会修改到不该改的样式，导致组件出问题。
  • 维护难度大：如果组件内部的结构变了，比如把按钮换成了<a>标签，外部的::part(btn)选择器可能会失效，需要通知用户修改样式。

适用场景：快速开发的项目、对组件自定义要求高的场景、内部使用的临时组件。

五、注意事项和坑点

在实际开发中，有几个地方需要特别注意，不然很容易踩坑：

5.1 Shadow DOM的mode要设为open

创建Shadow DOM的时候，要写成this.attachShadow({ mode: 'open' })，如果设成closed，外部的JS都访问不到Shadow DOM，样式穿透也会出问题，一般只有做特别隐私的组件才会用closed模式，大部分情况用open就行。

5.2 Bootstrap的样式要正确引入

如果是用CSS变量方案，重写Bootstrap样式的时候，要确保你重写的选择器优先级和Bootstrap的一致，不然可能会出现样式不生效的情况。比如Bootstrap的.btn样式优先级是10（类选择器），你重写的样式也要用.btn，优先级一样，才能覆盖；如果你的样式写的是.btn-primary，优先级也是10，也能覆盖。

5.3 part属性的命名要规范

用::part()方案的时候，part属性的名字要见名知意，比如按钮叫btn，输入框叫input，不要叫part1、part2，不然用户不知道怎么选。另外，part属性的名字不能带横杠以外的特殊字符，比如btn-primary是可以的，btn!就不行。

5.4 避免过度暴露

不管用哪种方法，都不要暴露太多的属性或者part。比如按钮组件，只暴露和外观相关的属性（颜色、大小、圆角），不要暴露内部的布局样式，比如display: flex这种，不然用户改了之后，组件的布局可能会乱。

六、实际应用场景举例

这个方案在很多场景下都很有用，举几个实际的例子：

  1. 公司内部组件库：比如公司要做一个统一的UI组件库，基于Bootstrap，每个项目拿过去就能用，不用再自己写样式。同时允许各个项目根据自己的品牌色修改按钮、表格的颜色，用CSS变量方案就能完美实现，既保证了组件的统一性，又有一定的自定义空间。

  2. 可复用的业务组件：比如做一个支付按钮组件，内部是Bootstrap的按钮样式，同时允许不同的业务线根据自己的需求调整按钮的大小、颜色，用::part()方案就能快速实现，不用提前定义太多变量。

  3. 主题切换功能：比如网站有白天模式和黑夜模式，只要修改全局的CSS变量，所有用了这个变量的组件（按钮、卡片、表格）都会自动切换样式，非常方便。

七、总结

把Bootstrap组件用Web Components封装，再加上样式穿透的白名单方案，本质上是解决了两个问题：一是避免样式冲突，让组件更稳定；二是保留一定的自定义能力，让组件更灵活。

CSS变量方案适合对稳定性要求高的场景，::part()方案适合对灵活性要求高的场景，你可以根据自己的项目需求选择合适的方法。只要掌握了核心思路，再结合具体的实现步骤，就能快速封装出符合自己需求的组件。