x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/config-provider-api.md

@@ -0,0 +1,38 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# ConfigProvider 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## ConfigProvider API
+
+公开声明：`dist/components/config-provider/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| size | 全局组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | undefined |
+| locale | 语言包，省略或清空时继承父级，再回退全局 | undefined &#124; Locale | 否 | undefined |
+| themeColor | 主题色种子，派生整条色阶并写入边界元素 | undefined &#124; string | 否 | undefined |
+| dark | 是否使用暗色色阶 | undefined &#124; false &#124; true | 否 | false |
+| tag | 包裹元素标签；传 null 不产生额外 DOM | undefined &#124; null &#124; string | 否 | "div" |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 配置生效的内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| empty | 子树内组件的空态内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [ConfigProvider 用法](./config-provider.md)。

package/AI_USAGE/components/config-provider.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ConfigProvider AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`ConfigProvider`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+先读 [通用接入](../core.md)。公开导出：`ConfigProvider`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./config-provider-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/base.css`（包含 base.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 局部品牌色用 `themeColor`，它一次生成色阶并重绑定组件别名；不必逐个覆盖 Button、Switch 的颜色。默认 body 浮层也会同步当前配置；更换 popupContainer 只用于业务定位和裁剪需要。Select 默认跟随祖先滚动；要滚动关闭可传 `triggerProps.scrollToClose`。
 
 ```vue
@@ -55,4 +57,249 @@ const options = [
 
 已有主题容器时，也可调用公开 `applyThemeColor(seed, { target, dark })`；切换暗色后需重新调用。只改后代的几条 semantic CSS 变量不会重算祖先 alias；`:tag="null"` 的 ConfigProvider 不创建本级主题边界，仍继承父级配置。
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/config-provider.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./config-provider-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+为子树内的组件提供统一的全局配置：尺寸、主题色与语言。
+
+
+### 何时使用
+
+- 需要统一调整一批组件的默认尺寸，而不想逐个传 `size`
+- 需要运行时切换品牌主题色
+- 需要切换组件内置文案的语言
+- 需要统一替换空态展示内容
+
+
+### 基础用法
+
+包裹需要生效的区域即可，默认渲染一个 `div` 作为配置边界。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Input, Button } from 'x-next';
+import { ref } from 'vue';
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('small');
+</script>
+<template>
+<ConfigProvider size="small">
+    <Input placeholder="输入框" />
+    <Button type="primary">按钮</Button>
+  </ConfigProvider>
+</template>
+```
+
+### 尺寸继承
+
+`size` 的优先级为：组件自身 props > 父级（如 FormItem）> ConfigProvider > 组件默认值。
+
+切换下面的尺寸，观察内部组件统一变化：
+
+Table 的默认尺寸为 `large`，未配置全局尺寸时保持该默认值：
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Button } from 'x-next';
+import { ref } from 'vue';
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('small');
+</script>
+<template>
+<!-- 内部按钮与输入框统一使用 small -->
+  <ConfigProvider size="small">
+    <Button>继承全局</Button>
+    <!-- 显式指定优先于全局配置 -->
+    <Button size="large">显式 large</Button>
+  </ConfigProvider>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Table } from 'x-next';
+import { ref } from 'vue';
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('small');
+
+const columns = [{ title: '名称', dataIndex: 'name' }];
+const data = [{ key: '1', name: '继承 small' }];
+</script>
+<template>
+<ConfigProvider size="small">
+    <Table :columns="columns" :data="data" :pagination="false" />
+  </ConfigProvider>
+</template>
+```
+
+### 主题色
+
+传入 `themeColor` 会派生整条色阶（基色 + 9 档）并写入配置边界元素，因此可以只对局部区域换色，不影响页面其余部分。
+
+需要暗色色阶时传 `dark`：
+
+默认通过 Trigger 渲染的浮层及组件形态的 Dialog / Drawer 会把当前局部主题带到 Teleport 根节点；打开中切换主题会同步更新。嵌套配置继承父级种子色和暗色边界。`dark=false` 不会取消父级暗色边界。
+
+### 显式 token 覆盖
+
+本级 `style` 中显式设置的 CSS token 优先于 `themeColor` 派生值。没有自行指定种子色或改变有效暗色模式的子配置，会继承这些覆盖；浮层保持相同配置。切换覆盖后，聚焦输入框检查边框；系统高对比度下焦点仍使用系统色。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Button, Switch } from 'x-next';
+
+</script>
+<template>
+<!-- 只影响这个边界内的组件 -->
+  <ConfigProvider theme-color="#0f766e">
+    <Button type="primary">主色按钮</Button>
+    <Switch :model-value="true" />
+  </ConfigProvider>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, ConfigProvider, Select, Popover, Button } from 'x-next';
+import { ref } from 'vue';
+const dark = ref(true);
+const color = ref('#0f766e');
+const options = [{ label: '主题内的选项', value: 'a' }];
+</script>
+<template>
+<Checkbox v-model="dark">局部暗色</Checkbox>
+  <ConfigProvider :theme-color="color" :dark="dark">
+    <Select :options="options" placeholder="打开查看浮层主题" />
+    <Popover title="主题同步" content="body 浮层也继承当前配置">
+      <Button>打开卡片</Button>
+    </Popover>
+  </ConfigProvider>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, ConfigProvider, Input, Select } from 'x-next';
+import { ref } from 'vue';
+const override = ref(false);
+const color = ref('#0f766e');
+const options = [{ label: '主题内的选项', value: 'a' }];
+</script>
+<template>
+<Checkbox v-model="override">使用危险色焦点边框</Checkbox>
+  <ConfigProvider :theme-color="color"
+    :style="override ? { '--x-color-border-focus': 'var(--x-color-danger-solid)' } : {}">
+    <ConfigProvider>
+      <Input placeholder="聚焦检查显式 token" />
+      <Select :options="options" placeholder="查看浮层" />
+    </ConfigProvider>
+  </ConfigProvider>
+</template>
+```
+
+### 语言
+
+传入 `locale` 切换组件内置文案。语言包从 `x-next` 导入：
+
+### 动态设置与嵌套回退
+
+初始省略 `locale` 也可以随后设置；清空子级配置后回退父级，顶层未配置时使用全局语言。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Empty, Pagination } from 'x-next';
+const total = 128;
+
+import { ref } from 'vue';
+import { zhCN, enUS } from 'x-next';
+
+const locale = ref(zhCN);
+// 切换为英文
+// locale.value = enUS;
+</script>
+<template>
+<ConfigProvider :locale="locale">
+    <Empty />
+    <Pagination :total="128" />
+  </ConfigProvider>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, ConfigProvider, Empty } from 'x-next';
+import { ref } from 'vue';
+import { enUS, zhCN } from 'x-next';
+const locale = ref<typeof zhCN | undefined>();
+</script>
+<template>
+<Button @click="locale = zhCN">子级中文</Button>
+  <Button @click="locale = undefined">继承父级英文</Button>
+  <ConfigProvider :locale="enUS">
+    <ConfigProvider :locale="locale">
+      <Empty />
+    </ConfigProvider>
+  </ConfigProvider>
+</template>
+```
+
+### 空态插槽
+
+`empty` 插槽会接管子树内组件的空态渲染，回调参数 `component` 标明请求来源，便于按组件区分样式。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Select, Table } from 'x-next';
+const columns = [{ title: '名称', dataIndex: 'name' }];
+</script>
+<template>
+<ConfigProvider>
+    <!-- component 标明来源：empty / select / table / dropdown -->
+    <template #empty="{ component }">
+      <div>暂无内容（来源：{{ component }}）</div>
+    </template>
+    <Select :options="[]" style="width: 200px" />
+    <Table :columns="columns" :data="[]" :pagination="false" />
+  </ConfigProvider>
+</template>
+```
+
+### 不产生额外 DOM
+
+默认会渲染一个包裹元素作为配置边界。若不想引入额外节点（例如在表格单元格内），可传 `:tag="null"`：
+
+注意：`:tag="null"` 时本级 `themeColor` / `dark` 不创建主题边界；仍继承父级主题、尺寸、语言和空态插槽。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Button } from 'x-next';
+import { ref } from 'vue';
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('small');
+</script>
+<template>
+<!-- 不产生包裹元素，仅向子树注入配置 -->
+  <ConfigProvider :tag="null" size="small">
+    <Button>按钮</Button>
+  </ConfigProvider>
+</template>
+```
+
+### 已知限制
+
+- `themeColor` 只派生 primary 色阶。`success` / `warning` / `danger` / `strong` 等状态色不受影响，需要改种子色请用构建期方式（见「样式与主题」）。
+- 不支持 `prefixCls` 自定义类名前缀，组件类名固定使用 `x` 前缀。
+- 语言包当前覆盖分页、表格、弹窗、空态、网络状态、图片预览、表单校验提示、日期 / 时间选择器，以及 Tabs、Dropdown、Menu、Message、Notification、Spin、Tag、InputPassword 等组件内置文案。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./config-provider-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。