如何在Stencil组件中添加全局主题包装器实现全组件深色模式？

1. 定义全局CSS主题变量 #

在Stencil项目的全局样式文件（通常是src/global/app.css）中，用CSS变量定义浅色/深色主题的样式值，通过根元素的data-theme属性切换：

/* 浅色主题默认值 */
:root {
  --bg-color: #ffffff;
  --text-color: #1a1a1a;
  --border-color: #e0e0e0;
  /* 可根据需求添加更多变量 */
}

/* 深色主题 */
:root[data-theme="dark"] {
  --bg-color: #1a1a1a;
  --text-color: #ffffff;
  --border-color: #333333;
}

之后所有组件的样式都使用这些变量，比如：

.my-component {
  background-color: var(--bg-color);
  color: var(--text-color);
  border: 1px solid var(--border-color);
}

2. 编写全局主题管理工具 #

创建一个工具类来统一处理主题的设置、切换和持久化，比如src/utils/theme-utils.ts：

export const ThemeUtils = {
  getCurrentTheme(): 'light' | 'dark' {
    return (document.documentElement.getAttribute('data-theme') as 'light' | 'dark') || 'light';
  },

  setTheme(theme: 'light' | 'dark') {
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('app-theme', theme);
  },

  toggleTheme() {
    const current = this.getCurrentTheme();
    this.setTheme(current === 'light' ? 'dark' : 'light');
  },

  initTheme() {
    // 优先取本地存储的主题，否则跟随系统设置
    const savedTheme = localStorage.getItem('app-theme') as 'light' | 'dark';
    const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    this.setTheme(savedTheme || systemTheme);

    // 监听系统主题变化（仅在用户未手动设置时同步）
    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
      if (!localStorage.getItem('app-theme')) {
        this.setTheme(e.matches ? 'dark' : 'light');
      }
    });
  }
};

3. 初始化主题 #

在Stencil应用的入口文件src/index.ts的bootstrap函数中调用初始化方法，确保应用启动时就加载正确的主题：

import { ThemeUtils } from './utils/theme-utils';

export async function bootstrap() {
  ThemeUtils.initTheme();
}

4. 创建主题切换组件（供React使用） #

开发一个可复用的切换组件，让React项目能直接调用：

import { Component, h } from '@stencil/core';
import { ThemeUtils } from '../../utils/theme-utils';

@Component({
  tag: 'theme-toggle',
  styleUrl: 'theme-toggle.css',
  shadow: true
})
export class ThemeToggle {
  handleToggle() {
    ThemeUtils.toggleTheme();
  }

  render() {
    const currentTheme = ThemeUtils.getCurrentTheme();
    return (
      <button onClick={this.handleToggle.bind(this)}>
        {currentTheme === 'light' ? '切换到深色模式' : '切换到浅色模式'}
      </button>
    );
  }
}

React项目中只需引入并使用<theme-toggle>标签，就能触发主题切换。

注意事项 #

• 所有组件必须使用全局CSS变量，避免硬写固定颜色值
• 本地存储的主题设置会优先于系统主题，确保用户手动切换的偏好被保留
• 如果需要支持更多主题（如高对比度），只需扩展data-theme的取值和对应的CSS变量即可

内容的提问来源于stack exchange，提问作者Shrestha