TaroifyReact UI

    ConfigProvider 全局配置

    介绍

    用于配置 Taroify 组件的主题样式。

    引入

    import { ConfigProvider } from "@taroify/core";

    定制主题

    介绍

    Taroify 组件通过丰富的 CSS 变量 来组织样式，通过覆盖这些 CSS 变量，可以实现定制主题、动态切换主题等效果。

    示例

    以 Button 组件为例，查看组件的样式，可以看到 .taroify-button--primary 类名上存在以下变量：

    .taroify-button--primary {
  color: var(--button-primary-color);
  background-color: var(--button-primary-background-color);
}

    自定义 CSS 变量

    通过 CSS 覆盖

    你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：

    /* 添加这段样式后，Primary Button 会变成红色 */
:root {
    --button-primary-background-color: red;
}

    注意：小程序不存在 :root 元素，只能在 page 根元素里覆盖 CSS 变量。

    通过 ConfigProvider 覆盖

    ConfigProvider 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 ConfigProvider 组件，并通过 theme 属性来配置一些主题变量。

    function CustomThemeVars() {
  const [rate, setRate] = useState(4)
  const [slider, setSlider] = useState(50)

  return (
    <ConfigProvider
      theme={{
        rateIconFullColor: "#07c160",
        sliderTrackHeight: "4px",
        sliderButtonWidth: "20px",
        sliderButtonHeight: "20px",
        sliderActiveBackgroundColor: "#07c160",
        buttonPrimaryBorderColor: "#07c160",
        buttonPrimaryBackgroundColor: "#07c160",
      }}
    >
      <Field label="评分">
        <Rate allowHalf value={rate} onChange={setRate} />
      </Field>
      <Field label="滑块">
        <Slider value={slider} onChange={setSlider} />
      </Field>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary">
          提交
        </Button>
      </View>
    </ConfigProvider>
  )
}

    注意：ConfigProvider 仅影响它的子组件的样式，不影响全局 root 节点。在小程序中 ConfigProvider 不能放置在 app.ts 文件里，因为 app.ts 文件不能渲染任何内容。

    暗色模式

    将 themeMode 设置为 dark，可以启用内置的暗色主题。theme 中的自定义变量会覆盖暗色主题的默认变量。

    <ConfigProvider
  themeMode="dark"
  theme={{
    primaryColor: "#4d9fff",
  }}
>
  <App />
</ConfigProvider>

    如果需要跟随微信系统主题，应在应用配置中启用 darkmode 和 themeLocation，然后通过 Taro.onThemeChange 更新 themeMode：

    const [themeMode, setThemeMode] = useState<ConfigProviderTheme>("light")

useEffect(() => {
  const listener = ({ theme }) => setThemeMode(theme)
  Taro.onThemeChange(listener)
  return () => Taro.offThemeChange(listener)
}, [])

return <ConfigProvider themeMode={themeMode}>{children}</ConfigProvider>

    在 TypeScript 中使用

    在 TypeScript 中定义 themeVars 时，建议使用 Taroify 提供的 ConfigProviderThemeVars 类型，可以提供完善的类型提示：

    import type { ConfigProviderThemeVars } from '@taroify/core';

const themeVars: ConfigProviderThemeVars = {
  rateIconFullColor: "#07c160",
  sliderTrackHeight: "4px",
  sliderActiveBackgroundColor: "#07c160",
  buttonPrimaryBorderColor: "#07c160",
  buttonPrimaryBackgroundColor: "#07c160",
};

    基础变量

    Taroify 中的 CSS 变量分为 基础变量 和 组件变量。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。

    变量列表

    下面是所有的基础变量：

    // Color Palette
--black: #000;
--white: #fff;
--gray-1: #f7f8fa;
--gray-2: #f2f3f5;
--gray-3: #ebedf0;
--gray-4: #dcdee0;
--gray-5: #c8c9cc;
--gray-6: #969799;
--gray-7: #646566;
--gray-8: #323233;
--red: #ee0a24;
--blue: #1989fa;
--orange: #ff976a;
--orange-dark: #ed6a0c;
--orange-light: #fffbe8;
--green: #07c160;

// Gradient Colors
--gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
--gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);

// Component Colors
--primary-color: var(--blue);
--success-color: var(--green);
--danger-color: var(--red);
--warning-color: var(--orange);
--text-color: var(--gray-8);
--text-color-2: var(--gray-6);
--text-color-3: var(--gray-5);
--active-color: var(--gray-2);
--active-opacity: 0.7;
--disabled-opacity: 0.5;
--background-color: var(--gray-1);
--background-color-2: var(--white);
--background-color-light: var(--background-color-2);
--text-link-color: #576b95;

// Padding
--padding-base: 4px;
--padding-xs: 8px;
--padding-sm: 12px;
--padding-md: 16px;
--padding-lg: 24px;
--padding-xl: 32px;

// Font
--font-size-xs: 10px;
--font-size-sm: 12px;
--font-size-md: 14px;
--font-size-lg: 16px;
--font-weight-bold: 500;
--line-height-xs: 14px;
--line-height-sm: 18px;
--line-height-md: 20px;
--line-height-lg: 22px;
--base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue',
  Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB',
  'Microsoft Yahei', sans-serif;
--price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue,
  Arial, sans-serif;

// Animation
--animation-duration-base: 0.3s;
--animation-duration-fast: 0.2s;
--animation-timing-function-enter: ease-out;
--animation-timing-function-leave: ease-in;

// Border
--border-color: var(--gray-3);
--border-width-base: 1px;
--border-radius-sm: 2px;
--border-radius-md: 4px;
--border-radius-lg: 8px;
--border-radius-max: 999px;

    你可以在各个组件文档底部的表格中查看组件变量。

    API

    Props

    参数说明类型默认值
    theme自定义主题变量，优先级高于内置主题ConfigProviderThemeVars-
    themeMode v1.0.0主题模式light | darklight