xtf-config-provider

组件说明

xtf-config-provider 是全局配置组件，用于在组件树中统一设置主题、尺寸、国际化、方向和禁用状态。支持嵌套覆盖、主题变量注入和运行时主题切换，是整个组件库的配置中枢。

---

基础用法

1. 最简示例

在根节点包裹 xtf-config-provider，设置主题和尺寸：

<template>
  <xtf-config-provider theme="light" size="md">
    <view>
      <xtf-button label="按钮" />
      <xtf-input placeholder="请输入" />
    </view>
  </xtf-config-provider>
</template>

2. 主题变量覆盖

通过 themeVars 覆盖 CSS 变量实现自定义主题：

<template>
  <xtf-config-provider theme="light" :theme-vars="customVars">
    <view>
      <xtf-button label="自定义主题" />
    </view>
  </xtf-config-provider>
</template>

<script>
export default {
  data() {
    return {
      customVars: {
        '--xtf-color-primary': '#6366F1',
        '--xtf-color-primary-soft': 'rgba(99, 102, 241, 0.1)',
        '--xtf-radius-lg': '24rpx'
      }
    }
  }
}
</script>

3. 国际化与方向

通过 locale 设置语言，通过 direction 设置文本方向：

<template>
  <xtf-config-provider locale="en-US" direction="ltr">
    <view>
      <xtf-calendar v-model="date" />
    </view>
  </xtf-config-provider>
</template>

<script>
export default {
  data() {
    return {
      date: ''
    }
  }
}
</script>

4. 嵌套配置

xtf-config-provider 支持嵌套，内层覆盖外层：

<template>
  <xtf-config-provider theme="light" size="md">
    <view>
      <xtf-button label="中等按钮" />
      <xtf-config-provider size="sm">
        <xtf-button label="小按钮" />
      </xtf-config-provider>
    </view>
  </xtf-config-provider>
</template>

---

全部属性

属性	类型	默认值	作用描述	适用范围
theme	String	''	主题名称	切换主题
themeVars	Object	{}	主题变量覆盖	自定义主题
size	String	''	全局尺寸	统一尺寸
zIndex	String | Number	''	全局层级	层级控制
duration	String | Number	''	全局动画时长（ms）	动画速度
safeArea	Boolean | String	null	是否启用安全区	安全区
ripple	Boolean | String	null	是否启用水波纹	水波纹
locale	String	''	国际化语言	多语言
direction	String	''	文本方向：'ltr' / 'rtl' / 'auto'	文本方向
componentSize	String	''	统一组件尺寸：'xs' / 'sm' / 'md' / 'lg' / 'xl'	统一大小
disabled	Boolean | String	null	全局禁用态	禁用交互
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

无自定义事件。

---

方法

通过组件 ref 可修改当前 provider 的局部配置；主题名与主题变量修改不会影响同级 provider。

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | | setLocalTheme | (name: String, overrides?: Object) | - | 设置局部主题及变量覆盖 | | clearLocalTheme | - | - | 清除局部主题覆盖 | | updateLocalThemeVars | (patch: Object) | - | 合并局部主题变量 | | updateLocalConfig | (patch: Object) | - | 合并局部配置 | | resetLocalConfig | - | - | 清除局部配置 |

使用示例：

<template>
  <xtf-config-provider ref="provider">
    <xtf-button label="切换主题" @click="changeTheme"
  /></xtf-config-provider>
</template>

<script>
export default {
  methods: {
    changeTheme() {
      this.$refs.provider.setLocalTheme('light', { '--xtf-color-primary': '#0f766e' })
      console.log('局部主题已更新')
    }
  }
}
</script>

主题说明

• xtf-config-provider 通过 provide/inject 向后代组件注入配置
• 主题变量通过 CSS 变量注入到 DOM 节点
• 嵌套时内层配置优先级高于外层
• 支持运行时切换主题，所有后代组件自动响应

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。