x-next 1.10.1 → 1.11.1

package/AI_USAGE/components/steps.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Steps AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`Steps`；模型：v-model:current；已核对事件：change。
+
+按需样式：`x-next/style/steps`（包含 base.css、steps.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
+
+`change(step, event)` 返回步骤号和 `Event`。Step 支持 `title`、`description`、`disabled`、`status`；`node` / `icon` 插槽提供步骤与状态，默认 / `description` 插槽可替换文案。业务完成状态由业务自身维护。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Steps, Step } from 'x-next';
+import 'x-next/dist/style.css';
+const current = ref(1);
+const feedback = ref('正在填写');
+function changed(step: number, _event: Event) { feedback.value = `已切换到第 ${step} 步`; }
+</script>
+<template>
+  <Steps v-model:current="current" changeable @change="changed">
+    <Step title="填写" description="准备安排" />
+    <Step title="核对" description="检查内容" />
+    <Step title="完成" description="提交结果" />
+  </Steps>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/switch.md

@@ -0,0 +1,32 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Switch AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`Switch`；模型：v-model；已核对事件：change。
+
+按需样式：`x-next/style/form-switch`（包含 base.css、form-switch.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
+
+`change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案；`type='line'` 或有效尺寸为 `'mini'`（含继承尺寸）时均不显示文案。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Switch } from 'x-next';
+import 'x-next/dist/style.css';
+const enabled = ref(false);
+const controlAttrs = { 'aria-label': '通知开关' };
+const feedback = ref('通知关闭');
+function changed(value: boolean | string | number, _event: Event) {
+  feedback.value = value === true ? '通知开启' : '通知关闭';
+}
+</script>
+<template>
+  <Switch v-model="enabled" checked-text="开" unchecked-text="关" v-bind="controlAttrs" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/tabs.md

@@ -0,0 +1,33 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tabs AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`Tabs`；模型：v-model:active-key；已核对事件：change。
+
+按需样式：`x-next/style/tabs`（包含 base.css、tabs.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/tabs)。使用 `v-model:active-key`，类型为 `string | number`；TabPane 用 Vue 的 `key` 标识页签，键类型须与模型一致。默认 `type='line'`、`position='top'`、`trigger='click'`、`lazyLoad=false`、`destroyOnHide=false`。
+
+`change(key)` 返回键值，`tab-click(key, event)` 还返回 `Event`。禁用配置放在 TabPane；TabPane 默认插槽放正文，`title` 插槽自定义标题，Tabs 的 `extra` 放额外内容。可编辑模式的 `add` / `delete` 事件需要业务维护页签数据。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Tabs, TabPane } from 'x-next';
+import 'x-next/dist/style.css';
+const active = ref<string | number>('overview');
+const feedback = ref('当前概览');
+function changed(key: string | number) { feedback.value = `当前页签：${key}`; }
+</script>
+<template>
+  <Tabs v-model:active-key="active" @change="changed">
+    <TabPane key="overview" title="概览">查看当前安排。</TabPane>
+    <TabPane key="history" title="历史">查看已完成记录。</TabPane>
+    <TabPane key="restricted" title="未开放" disabled>此内容暂不可选。</TabPane>
+  </Tabs>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/textarea.md

@@ -0,0 +1,31 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Textarea AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`Textarea`；模型：v-model；已核对事件：input、change、clear。
+
+按需样式：`x-next/style/form-textarea`（包含 base.css、form-textarea.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/textarea)。`v-model` 为字符串，`input/change/clear` 与输入生命周期联动。原生 id、name、aria、rows、readonly 用 `textareaAttrs`，不支持组件层的 readonly prop；autoSize 控制自动高度。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Textarea } from 'x-next';
+import 'x-next/style/form-textarea';
+const summary = ref('');
+const log = ref('等待输入');
+const nativeAttrs = { id: 'article-summary', name: 'summary', 'aria-label': '文章摘要', rows: 3 };
+const readonlyAttrs = { id: 'saved-summary', name: 'savedSummary', 'aria-label': '只读摘要', readonly: true };
+</script>
+<template>
+  <label for="article-summary">文章摘要</label>
+  <Textarea v-model="summary" :textarea-attrs="nativeAttrs" :auto-size="{ minRows: 3, maxRows: 6 }"
+    @input="value => log = `input: ${value}`" />
+  <Textarea model-value="已保存的摘要" :textarea-attrs="readonlyAttrs" />
+  <p role="status">{{ log }}；当前值：{{ summary }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/time-picker.md

@@ -0,0 +1,34 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# TimePicker AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`TimePicker`；模型：v-model、v-model:popup-visible；已核对事件：change。
+
+按需样式：`x-next/style/time-picker`（包含 base.css、button.css、scrollbar-v2.css、time-picker.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/time-picker)。默认 `type='time'`、`allowClear=true`、`disableConfirm=false`，默认格式为 `'HH:mm:ss'`。`format` 同时决定显示与输出；`step` 用 `{ hour, minute, second }`，各步长默认 `1`。
+
+`change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空发出 `update:modelValue(undefined)` 和 `change(undefined, undefined)`；本例的业务 `update()` 才归一化为 `''` 保持单值字符串受控。支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimePicker } from 'x-next';
+import 'x-next/dist/style.css';
+const time = ref('');
+const feedback = ref('尚未选择时间');
+function update(value: unknown) { time.value = typeof value === 'string' ? value : ''; }
+function changed(value: string | (string | undefined)[] | undefined, _time: unknown) {
+  update(value);
+  feedback.value = time.value ? `时间：${time.value}` : '已清空时间';
+}
+</script>
+<template>
+  <TimePicker :model-value="time" format="HH:mm" :step="{ minute: 15 }" placeholder="选择时间"
+    @update:model-value="update" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/components/upload.md

@@ -0,0 +1,60 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Upload AI 使用
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)。公开导出：`Upload`；模型：v-model:file-list；已核对事件：change、success、error、remove、exceed、reject、progress。
+
+按需样式：`x-next/style/upload`（包含 base.css、image.css、progress.css、trigger.css、tooltip.css、upload.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
+
+**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，通常 resolve 成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。fetch `Response` 为非 2xx 时，即使 Promise resolve 也按失败处理，`error.status` 为状态码；成功响应仅对 JSON/text 内容类型解析，二进制等其他类型保留 Response 本体，不自动转为 Blob。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
+
+列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表。`beforeUpload` 返回 `false`、抛错或 Promise reject 都会拒绝入列并触发 `reject`；返回 `File` 替换文件，返回 `Blob` / string 则用原文件名生成新 File。string 是文件内容而非下载 URL；以上返回形式支持 Promise。
+
+`change({ file, fileList })` 覆盖加入、进度、成功、失败和移除；`success` / `error` / `remove` / `progress` 是更细粒度的补充。`autoUpload=false` 时文件先以 `init` 入列，再用组件 `submit()` 上传、`abort()` 取消、`retry()` 重试。图片卡场景可加 `image-preview` 用内置 `ImagePreview` 看图。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Upload, type UploadFile } from 'x-next';
+import 'x-next/dist/style.css';
+const fileList = ref<UploadFile[]>([]);
+const status = ref('尚未选择文件');
+// 项目里已封装好的上传方法：返回 Promise 即可，组件自动显示成功与失败
+function uploadAttachment(params: { file: File; orderId: string }) {
+  const form = new FormData();
+  form.append('file', params.file);
+  form.append('orderId', params.orderId);
+  return fetch('/api/upload', { method: 'POST', body: form }).then((response) => {
+    if (!response.ok) throw new Error(`上传失败：${response.status}`);
+    return response.json() as Promise<{ data: { url: string } }>;
+  });
+}
+function changed(info: { file: UploadFile; fileList: UploadFile[] }) {
+  status.value = `${info.file.name}：${info.file.status ?? 'unknown'}`;
+}
+function beforeUpload(file: File) {
+  // 超过 2MB 直接拦截，文件不会进入列表
+  return file.size <= 2 * 1024 * 1024;
+}
+</script>
+<template>
+  <Upload
+    v-model:file-list="fileList"
+    :custom-request="({ file }) => uploadAttachment({ file, orderId: 'SO-20261003' })"
+    response-url-key="data.url"
+    name="file"
+    multiple
+    list-type="picture"
+    accept="image/*"
+    :limit="5"
+    :before-upload="beforeUpload"
+    @change="changed"
+  />
+  <p role="status">{{ status }}</p>
+</template>
+```
+
+返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。

package/AI_USAGE/core.md

@@ -0,0 +1,37 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# x-next AI 通用接入
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+```sh
+npm install x-next
+```
+
+应用需已有 Vue 3、TypeScript 和 Vue SFC 构建支持。按需具名导入无需安装全局插件；在 `main.ts` 引入一次样式：
+
+```ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import 'x-next/dist/style.css';
+
+createApp(App).mount('#app');
+```
+
+下方各节使用局部具名导入。需要全局注册时可另用 `app.use(XNext)`（默认导出），它会注册全部组件。根入口的 `Dialog` 是命令式服务，模板组件是 `DialogComponent`；MessageBox 使用服务函数。
+
+接入时遵循这些约定：
+
+- **按组件路由传原生属性**：Checkbox / Select 用已核实的 `id/name/aria-*` 属性对象 `v-bind`；Input 用 `inputAttrs`，Textarea 用 `textareaAttrs`。Textarea 的 readonly 也放在 `textareaAttrs` 中。组件 props 和事件直接绑定，不把未知组件 API 塞进 attrs。
+- **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用组件实际支持的 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。DatePicker / TimePicker 清空实际发出 `undefined`，下方单值字符串示例在业务回调中保存 `''` 以保持受控；这不是组件自动归一化，也不能直接套用于范围模型。
+- **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪。ConfigProvider 的主题会同步到 Trigger 浮层及组件形态 Dialog / Drawer；单独调用 applyThemeColor 或独立创建命令式实例时，仍需按实际 DOM 宿主处理主题。
+- **优先用公开主题变量**：参考[样式与主题](https://x-next.yjmf.com/guide/theme)。暗色容器上的 alias 链会重新声明；`themeColor` 写入的内联 primary alias 有覆盖边界，按主题文档设置相关公开 alias。
+- **约束业务全局 CSS**：reset 用 `:where(...)` 降低优先级并限定作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
+- **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自的 `onClose`。
+
+## 按需样式
+
+使用无扩展名的公开 JS 样式入口，例如 `x-next/style/form-select`。它自动引入共享 base、Select 自身及 Trigger、Scrollbar、Empty、Spin、Checkbox 的 CSS；业务不需要逐个维护内部依赖。多个入口由打包器按文件去重。Input / Textarea 的样式路径分别是 `form-input` / `form-textarea`，不要根据组件名猜 `style/input`。
+
+若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
+
+完整组合：[按需表单 SFC](./recipes/form-on-demand.md)。回到 [索引](./index.md) 按需读取组件；已读且仍在上下文、消费内容未变时复用。规则模板在 [AI_CODING.md](../AI_CODING.md)。

package/AI_USAGE/index.md

@@ -0,0 +1,52 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# x-next AI 按需入口
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+AI 专用资料，与文档站独立分发。先读 [core.md](./core.md)，再只读本任务需要的组件页；每页提供真实约束、公共导出、模型/事件/样式和完整 Vue SFC。代码与同版本完整手册同源并严格检查；本索引不塞入完整示例。
+
+用 `require.resolve('x-next/AI_USAGE/index.md')` 定位本页，组件例如 `require.resolve('x-next/AI_USAGE/components/select.md')`。升级或本地 dist 重建后重新核对；文件不会被所有工具自动加载，消费项目须合并 [AI_CODING.md](../AI_CODING.md) 中的 AGENTS 建议。
+
+## 组件检索
+
+| 组件/服务 | 按需内容 | 模型 | 样式入口 |
+| --- | --- | --- | --- |
+| ConfigProvider | [config-provider](./components/config-provider.md) | 无 | `x-next/style/base.css` |
+| ColorPicker | [color-picker](./components/color-picker.md) | v-model、v-model:show | `x-next/style/color-picker` |
+| Button | [button](./components/button.md) | 无 | `x-next/style/button` |
+| Input | [input](./components/input.md) | v-model | `x-next/style/form-input` |
+| Textarea | [textarea](./components/textarea.md) | v-model | `x-next/style/form-textarea` |
+| Checkbox | [checkbox](./components/checkbox.md) | v-model | `x-next/style/form-checkbox` |
+| Radio | [radio](./components/radio.md) | v-model | `x-next/style/form-radio` |
+| Select | [select](./components/select.md) | v-model、v-model:popup-visible | `x-next/style/form-select` |
+| Slider | [slider](./components/slider.md) | v-model | `x-next/style/form-slider` |
+| Rate | [rate](./components/rate.md) | v-model | `x-next/style/rate` |
+| Switch | [switch](./components/switch.md) | v-model | `x-next/style/form-switch` |
+| DatePicker | [date-picker](./components/date-picker.md) | v-model、v-model:popup-visible | `x-next/style/date-picker` |
+| TimePicker | [time-picker](./components/time-picker.md) | v-model、v-model:popup-visible | `x-next/style/time-picker` |
+| Alert | [alert](./components/alert.md) | v-model:visible | `x-next/style/alert` |
+| Dialog | [dialog](./components/dialog.md) | v-model | `x-next/style/dialog` |
+| Message | [message](./components/message.md) | 无 | `x-next/style/message` |
+| MessageBox | [message-box](./components/message-box.md) | 无 | `x-next/style/message-box` |
+| Notification | [notification](./components/notification.md) | 无 | `x-next/style/notification` |
+| Popconfirm | [popconfirm](./components/popconfirm.md) | v-model | `x-next/style/popconfirm` |
+| Popover | [popover](./components/popover.md) | v-model:popup-visible | `x-next/style/popover` |
+| Progress | [progress](./components/progress.md) | 无 | `x-next/style/progress` |
+| Dropdown | [dropdown](./components/dropdown.md) | v-model:popup-visible | `x-next/style/dropdown` |
+| Pagination | [pagination](./components/pagination.md) | v-model:current、v-model:page-size | `x-next/style/pagination` |
+| Steps | [steps](./components/steps.md) | v-model:current | `x-next/style/steps` |
+| Tabs | [tabs](./components/tabs.md) | v-model:active-key | `x-next/style/tabs` |
+| Empty | [empty](./components/empty.md) | 无 | `x-next/style/empty` |
+| Upload | [upload](./components/upload.md) | v-model:file-list | `x-next/style/upload` |
+| BarChart | [bar-chart](./components/bar-chart.md) | 无 | `x-next/style/bar-chart` |
+| LineChart | [line-chart](./components/line-chart.md) | 无 | `x-next/style/line-chart` |
+| PieChart | [pie-chart](./components/pie-chart.md) | 无 | `x-next/style/pie-chart` |
+
+## 组合和未收录能力
+
+- [按需表单完整 SFC](./recipes/form-on-demand.md)：Input + Textarea + Select + Checkbox + ConfigProvider。
+- 编辑弹窗：读 Dialog、Input、Select；需要 Form 时再查 [公开组件导航](./catalog.md) 中的类型与组件文档。不要因手册缺节就判断没有组件。
+- [公开组件/服务导航](./catalog.md)：更多组件、子组件、别名和声明定位；精选覆盖 30 个契约，不代表全部导出。
+- [完整兼容手册](../AI_USAGE.md)：旧用法保留；新任务不默认读取全文。
+
+按需读取不能保证模型绝不读多或 API 绝不出错。保留通用规则和组件完整约束，并用严格类型、构建及真实浏览器验证；不以“读取过”代替验收。

package/AI_USAGE/recipes/form-on-demand.md

@@ -0,0 +1,45 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# 按需样式与表单接入
+
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
+
+先读 [通用接入](../core.md)，相关组件规则：[config-provider](../components/config-provider.md)、[input](../components/input.md)、[textarea](../components/textarea.md)、[select](../components/select.md)、[checkbox](../components/checkbox.md)。
+
+使用无扩展名的公开 JS 样式入口，例如 `x-next/style/form-select`。它自动引入共享 base、Select 自身及 Trigger、Scrollbar、Empty、Spin、Checkbox 的 CSS；业务不需要逐个维护内部依赖。多个入口由打包器按文件去重。Input / Textarea 的样式路径分别是 `form-input` / `form-textarea`，不要根据组件名猜 `style/input`。
+
+若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
+
+下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入。表单控件是行内级元素且宽度 100%，裸放在普通块级容器里会参与行内排版，父级行高会在相邻控件之间留下不均匀间距；示例用 `Space` 纵向堆叠并开启 `fill`，控件撑满父容器且间距一致，业务里也应放进 Space、Form 这类布局容器。
+
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ConfigProvider, Input, Textarea, Select, Checkbox, Space } from 'x-next';
+import 'x-next/style/form-input';
+import 'x-next/style/form-textarea';
+import 'x-next/style/form-select';
+import 'x-next/style/form-checkbox';
+import 'x-next/style/space';
+const title = ref('');
+const summary = ref('只读接入说明');
+const scopes = ref<string[]>(['read']);
+const accepted = ref(false);
+const titleAttrs = { id: 'cms-title', name: 'title', 'aria-label': '标题', required: true };
+const summaryAttrs = { id: 'cms-summary', name: 'summary', 'aria-label': '说明', readonly: true };
+const selectAttrs = { id: 'cms-scopes', 'aria-label': '授权范围' };
+const checkboxAttrs = { name: 'agreement', 'aria-label': '同意条款' };
+const options = [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }];
+</script>
+<template>
+  <ConfigProvider theme-color="#0f766e">
+    <Space direction="vertical" fill size="medium">
+      <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
+      <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
+      <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
+      <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    </Space>
+    <p role="status">标题：{{ title || '空' }}；范围：{{ scopes.join(', ') }}；同意：{{ accepted }}</p>
+  </ConfigProvider>
+</template>
+```