x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/skeleton-api.md

@@ -0,0 +1,85 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Skeleton 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Skeleton API
+
+公开声明：`dist/components/skeleton/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| loading | 是否展示骨架屏 | undefined &#124; false &#124; true | 否 | true |
+| animation | 是否开启动画 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 加载中展示的骨架内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 加载完成后展示的真实内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## SkeletonLine API
+
+公开声明：`dist/components/skeleton/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| rows | 行数 | undefined &#124; number | 否 | 1 |
+| widths | 每一行宽度 | undefined &#124; (string &#124; number)[] | 否 | [] |
+| lineHeight | 行高 | undefined &#124; number | 否 | 20 |
+| lineSpacing | 行间距 | undefined &#124; number | 否 | 15 |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## SkeletonShape API
+
+公开声明：`dist/components/skeleton/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| shape | 图形形状 | undefined &#124; "circle" &#124; "square" | 否 | "square" |
+| size | 图形尺寸 | undefined &#124; "small" &#124; "medium" &#124; "large" | 否 | "medium" |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Skeleton 用法](./skeleton.md)。

package/AI_USAGE/components/skeleton.md

@@ -0,0 +1,150 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Skeleton AI 使用
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。公开导出：`Skeleton, SkeletonLine, SkeletonShape`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./skeleton-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/skeleton`（包含 base.css、skeleton.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/skeleton.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./skeleton-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于数据加载前占位，降低页面空白感。
+
+
+### 何时使用
+
+- 页面局部内容正在加载，需要保留版式位置。
+- 图文列表、详情卡片或表单区域预计很快返回真实内容。
+- 首屏加载需要比 Spin 更接近最终结构的反馈。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Skeleton, Space, SkeletonShape, SkeletonLine } from 'x-next';
+import { computed, ref } from 'vue';
+const rows = ref(3);
+</script>
+<template>
+<Skeleton>
+    <Space size="large">
+      <SkeletonShape />
+      <SkeletonLine :rows="3" :widths="['56%', '100%', '72%']" />
+    </Space>
+  </Skeleton>
+</template>
+```
+
+### 加载完成
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Skeleton, SkeletonLine } from 'x-next';
+const animation = ref(true);
+const rows = ref(3);
+
+import { ref } from 'vue';
+
+const loading = ref(true);
+</script>
+<template>
+<Button @click="loading = !loading">切换加载状态</Button>
+  <Skeleton :loading="loading" animation>
+    <SkeletonLine :rows="3" />
+    <template #content>
+      <div>真实内容</div>
+    </template>
+  </Skeleton>
+</template>
+```
+
+### 动画
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch, Skeleton, SkeletonLine } from 'x-next';
+const rows = ref(3);
+
+import { ref } from 'vue';
+
+const animation = ref(true);
+</script>
+<template>
+<Switch v-model="animation" checked-text="动画" unchecked-text="静态" />
+  <Skeleton :animation="animation">
+    <SkeletonLine :rows="4" />
+  </Skeleton>
+</template>
+```
+
+### 图形骨架
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Skeleton, SkeletonShape } from 'x-next';
+
+</script>
+<template>
+<Skeleton>
+    <div class="demo-inline-group">
+      <SkeletonShape size="small" />
+      <SkeletonShape />
+      <SkeletonShape size="large" />
+      <SkeletonShape shape="circle" size="small" />
+      <SkeletonShape shape="circle" />
+      <SkeletonShape shape="circle" size="large" />
+    </div>
+  </Skeleton>
+</template>
+```
+
+### 行数与宽度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Skeleton, SkeletonLine } from 'x-next';
+const animation = ref(true);
+
+import { ref } from 'vue';
+
+const rows = ref(3);
+const widths = ref(['72%', '100%', 180]);
+</script>
+<template>
+<Skeleton animation>
+    <SkeletonLine
+      :rows="rows"
+      :widths="widths"
+      :line-height="20"
+      :line-spacing="15"
+    />
+  </Skeleton>
+</template>
+```
+
+### 无障碍
+
+- `loading` 时根节点带 `aria-busy="true"`，屏幕阅读器据此知道该区域正在加载。
+- `SkeletonLine` 与 `SkeletonShape` 是纯装饰占位，内部带 `aria-hidden="true"`，避免空列表项被读出来。
+- 开启系统「减弱动态效果」后，`animation` 的流光动画自动停止；占位轮廓与渐变保持不变，加载区域不会消失。
+
+
+### 已知限制
+
+- 当前保持 Arco 风格的 `SkeletonLine` / `SkeletonShape` 组合式 API，不提供 AntDV 风格的 `avatar`、`title`、`paragraph` 快捷 props。
+- 只有「流光」一种动画形态，没有 AntDV 的 `fade` 变体。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./skeleton-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/slider-api.md

@@ -0,0 +1,51 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Slider 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Slider API
+
+公开声明：`dist/components/form-slider/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; number &#124; number[] &#124; [number, number] | 否 | undefined |
+| defaultValue | 默认值，非受控模式 | undefined &#124; number &#124; [number, number] | 否 | 0 |
+| step | 步长 | undefined &#124; number | 否 | 1 |
+| min | 最小值 | undefined &#124; number | 否 | 0 |
+| marks | 刻度标签 | undefined &#124; { [x: number]: string; } | 否 | 未声明 |
+| max | 最大值 | undefined &#124; number | 否 | 100 |
+| direction | 滑动方向 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| size | 组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| showTicks | 是否显示刻度线 | undefined &#124; false &#124; true | 否 | false |
+| showInput | 是否显示输入框 | undefined &#124; false &#124; true | 否 | false |
+| range | 是否开启范围选择 | undefined &#124; false &#124; true | 否 | false |
+| formatTooltip | 格式化 tooltip 内容 | undefined &#124; (value: string &#124; number &#124; undefined) => string | 否 | 未声明 |
+| showTooltip | 是否显示 tooltip | undefined &#124; false &#124; true | 否 | true |
+| tooltipPosition | tooltip 展示位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" &#124; "lt" &#124; "rt" &#124; "lb" &#124; "rb" | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: number &#124; [number, number]) => any |
+| change | 值变化时触发，拖动过程中会连续触发 | undefined &#124; (value: number &#124; [number, number]) => any |
+| changeEnd | 点击、输入、键盘调整或拖拽结束后触发 | undefined &#124; (value: number &#124; [number, number]) => any |
+| focus | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Slider 用法](./slider.md)。

package/AI_USAGE/components/slider.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Slider AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Slider`；模型：v-model；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Slider`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./slider-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-slider`（包含 base.css、button.css、form-input.css、form-input-number.css、form-slider.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/slider)。普通模型为 `number`，`range` 模式为 `[number, number]`。默认 `min=0`、`max=100`、`step=1`、`range=false`、`disabled=false`、`showTooltip=true`；范围端点按大小排序并按步长归一化。
 
 `change(value)` 表示值变化，`change-end(value)` 表示一次拖拽、点击、键盘或输入提交结束，载荷均为 `number | [number, number]`。`marks` 是数值键到文字的映射，`formatTooltip` 可格式化提示。
@@ -31,4 +33,232 @@ function finish(value: number | [number, number]) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/slider.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./slider-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在连续区间内选择数值，适合音量、比例、进度等场景。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(30);
+</script>
+<template>
+<Slider v-model="value" :min="0" :max="100" />
+</template>
+```
+
+### 禁用状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(50);
+</script>
+<template>
+<Slider v-model="value" disabled show-ticks :step="10" />
+</template>
+```
+
+### 步长和刻度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(20);
+const marks = {
+  0: '0%',
+  50: '50%',
+  100: '100%',
+};
+</script>
+<template>
+<Slider v-model="value" :step="10" show-ticks :marks="marks" />
+</template>
+```
+
+### 尺寸
+
+尺寸会影响轨道厚度、滑块直径与刻度文字字号。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(40);
+</script>
+<template>
+<Slider v-model="value" size="mini" />
+  <Slider v-model="value" size="small" />
+  <Slider v-model="value" size="medium" />
+  <Slider v-model="value" size="large" />
+</template>
+```
+
+### 范围选择
+
+独立使用时可给手柄设置 `aria-label`。`id` 和 ARIA 属性会传到真实滑块，范围第二端使用 `ID-end`；放入 Form 后会自动关联字段标签和帮助说明。禁用手柄退出 Tab 序列。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const range = ref<[number, number]>([20, 80]);
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "价格范围" } satisfies HTMLAttributes;
+</script>
+<template>
+<Slider v-bind="nativeAttrs1" v-model="range" range :min="0" :max="100"  />
+</template>
+```
+
+### 显示输入框
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(36);
+const range = ref<[number, number]>([15, 65]);
+</script>
+<template>
+<Slider v-model="value" show-input />
+  <Slider v-model="range" range show-input />
+</template>
+```
+
+### 垂直方向
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+const marks = {
+  0: '0%',
+  50: '50%',
+  100: '100%',
+};
+
+import { ref } from 'vue';
+
+const value = ref(45);
+const range = ref<[number, number]>([20, 70]);
+</script>
+<template>
+<Slider
+    v-model="value"
+    direction="vertical"
+    :marks="{ 0: '0', 50: '50', 100: '100' }"
+  />
+  <Slider v-model="range" direction="vertical" range show-input />
+</template>
+```
+
+### Tooltip
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(25);
+const formatTooltip = (val?: string | number) => `${val}%`;
+</script>
+<template>
+<Slider v-model="value" :format-tooltip="formatTooltip" tooltip-position="top" />
+  <Slider v-model="value" :show-tooltip="false" />
+</template>
+```
+
+### 事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Slider } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(40);
+const log = ref('等待操作');
+</script>
+<template>
+<Slider
+    v-model="value"
+    @change="(val) => log = `change: ${JSON.stringify(val)}`"
+    @change-end="(val) => log = `change-end: ${JSON.stringify(val)}`"
+  />
+  <p>{{ log }}</p>
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Slider, Space, Button } from 'x-next';
+const value = ref(30);
+
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ threshold: 0 });
+const formRules: Record<string, FieldRule[]> = {
+  threshold: [{ required: true, type: 'number', min: 1, message: '请设置阈值' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="threshold" label="阈值">
+      <Slider v-model="formState.threshold" :min="0" :max="100" show-input />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./slider-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/space-api.md

@@ -0,0 +1,38 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Space 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Space API
+
+公开声明：`dist/components/space/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| direction | 排列方向 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| size | 间距大小 | undefined &#124; number &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | "small" |
+| align | 对齐方式。space-between 用于主轴两端分布，通常配合 block 或宽度使用 | undefined &#124; "center" &#124; "start" &#124; "end" &#124; "space-between" &#124; "baseline" | 否 | "center" |
+| block | 是否让根节点以 flex 撑满父容器布局 | undefined &#124; false &#124; true | 否 | false |
+| fill | 是否撑满父容器并让每个间距项等分可用空间 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 间距项 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| split | 分隔内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Space 用法](./space.md)。