x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/input.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Input AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Input`；模型：v-model；已核对事件：input、change、clear。
+先读 [通用接入](../core.md)。公开导出：`Input, InputGroup, InputPassword, InputSearch`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./input-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-input`（包含 base.css、button.css、form-input.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/input)。`v-model` 为字符串，`input` 随输入触发；失焦、回车或清空时，值相对聚焦时/上次 change 的记录发生变化才触发 `change(value, event)`。`clear(event)` 通知清空按钮操作；readonly 是组件 prop。原生 id、name、aria、required 用 `inputAttrs`，外部 class / style 落在容器。内部装饰用 prefix / suffix，外侧标签用 prepend / append。
 
 ```vue
@@ -29,4 +31,292 @@ const nativeAttrs = { id: 'article-title', name: 'title', 'aria-label': '文章
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/input.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./input-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于单行文本输入，并提供搜索、密码和组合输入等扩展形态。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+</script>
+<template>
+<Input v-model="value" placeholder="请输入" allow-clear />
+</template>
+```
+
+### 前缀与后缀
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+</script>
+<template>
+<Input v-model="value" placeholder="请输入">
+    <template #prefix>https://</template>
+    <template #suffix>.com</template>
+  </Input>
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+const value = ref('当前内容');
+</script>
+<template>
+<Input v-model="value" size="mini" />
+  <Input v-model="value" size="small" />
+  <Input v-model="value" size="medium" />
+  <Input v-model="value" size="large" />
+</template>
+```
+
+### 禁用、只读和错误
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+const value = ref('当前内容');
+import type { InputHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "禁用输入" } satisfies InputHTMLAttributes;
+const nativeAttrs2 = { "aria-label": "只读输入" } satisfies InputHTMLAttributes;
+const nativeAttrs3 = { "aria-label": "错误输入" } satisfies InputHTMLAttributes;
+</script>
+<template>
+<Input :input-attrs="nativeAttrs1" v-model="value" disabled allow-clear  />
+  <Input :input-attrs="nativeAttrs2" v-model="value" readonly allow-clear  />
+  <Input :input-attrs="nativeAttrs3" v-model="value" error allow-clear  />
+</template>
+```
+
+### 字数限制
+
+`errorOnly` 允许输入超过限制，并展示错误状态。Input 默认按 JavaScript 字符串长度计数；需要自定义计数时，同时提供 `wordLength` 和 `wordSlice`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+const value = ref('');
+const overflow = ref('超长内容只提示错误，不会被截断');
+</script>
+<template>
+<Input v-model="value" :max-length="12" show-word-limit allow-clear />
+  <Input v-model="overflow" :max-length="{ length: 12, errorOnly: true }" show-word-limit allow-clear />
+</template>
+```
+
+### 搜索、加载和禁用
+
+`search` 在点击搜索按钮时触发。需要回车搜索时，可监听继承自 Input 的 `press-enter`，用当前 `v-model` 值执行搜索。禁用状态同时约束输入和搜索按钮，并可继承 Form 的禁用状态与尺寸。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, InputSearch } from 'x-next';
+import { ref } from 'vue';
+const value = ref('');
+const disabled = ref(false);
+const loading = ref(false);
+const result = ref('等待搜索');
+const handleSearch = (value: string) => { result.value = `搜索：${value || '空内容'}`; };
+</script>
+<template>
+<Checkbox v-model="disabled">禁用搜索</Checkbox>
+  <Checkbox v-model="loading">加载中</Checkbox>
+  <InputSearch v-model="value" :disabled="disabled" :loading="loading" allow-clear @search="handleSearch" />
+  <InputSearch v-model="value" :disabled="disabled" :loading="loading" search-button button-text="搜索" @search="handleSearch" />
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+### 输入和提交事件
+
+`input` 表示键入，`change` 在值有变化时由失焦、回车或清空触发。清空会通知 Form 的 `input` 校验通道，公开事件仍通过 `clear` 表示按钮操作。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+const value = ref('');
+const result = ref('等待输入');
+</script>
+<template>
+<Input v-model="value" allow-clear
+    @input="(next) => result = `input：${next}`"
+    @change="(next) => result = `change：${next || '空内容'}`"
+    @press-enter="result = `press-enter：${value}`"
+    @clear="result = 'clear：已清空'"
+  />
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+### 前置与后置标签
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Input } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+</script>
+<template>
+<Input v-model="value" placeholder="请输入域名">
+    <template #prepend>https://</template>
+    <template #append>.com</template>
+  </Input>
+</template>
+```
+
+### 在 Form 中校验
+
+`x-input` 接入 `x-form` 后会自动继承尺寸与禁用状态，并按 `validateTrigger` 触发校验。默认 `change` 表示文本输入在失焦时校验；需要每次输入即校验时设置 `validateTrigger="input"`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const form = reactive({ email: '', code: '' });
+const formRules: Record<string, FieldRule[]> = {
+  email: [
+    { required: true, message: '请输入邮箱' },
+    { type: 'email', message: '邮箱格式不正确' },
+  ],
+  code: [{ required: true, message: '请输入验证码' }],
+};
+const formRef = ref<FormInstance>();
+const formResult = ref('');
+
+const onSubmit = async () => {
+  const errors = await formRef.value!.validate();
+  formResult.value = errors ? '校验失败，请检查表单' : '校验通过，已提交';
+};
+</script>
+<template>
+<Form ref="formRef" :model="form" :rules="formRules">
+    <FormItem field="email" label="邮箱">
+      <Input v-model="form.email" placeholder="请输入邮箱" allow-clear />
+    </FormItem>
+    <!-- validate-trigger 是 FormItem 的 prop：每次输入即触发校验 -->
+    <FormItem field="code" label="验证码" validate-trigger="input">
+      <Input v-model="form.code" placeholder="请输入验证码" />
+    </FormItem>
+    <FormItem>
+      <Button type="primary" @click="onSubmit">提交</Button>
+    </FormItem>
+  </Form>
+  <p role="status">{{ formResult }}</p>
+</template>
+```
+
+### 关联组件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputSearch, InputPassword, InputGroup, Input } from 'x-next';
+import { reactive, ref } from 'vue';
+const password = ref('x-next-password');
+</script>
+<template>
+<InputSearch placeholder="搜索" />
+  <InputPassword placeholder="密码" />
+  <InputGroup>
+    <Input placeholder="省" />
+    <Input placeholder="市" />
+  </InputGroup>
+</template>
+```
+
+### Select 组合与尺寸
+
+Select 可以位于组合的首项或末项。相邻项共享边框，仅组合两端保留圆角；切换尺寸、禁用后，聚焦可检查拼接边框和圆角。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Radio, Checkbox, InputGroup, Select, Input, Button } from 'x-next';
+import { ref } from 'vue';
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('medium');
+const disabled = ref(false);
+const value = ref('');
+const type = ref('name');
+const options = [{ label: '名称', value: 'name' }, { label: '编号', value: 'id' }];
+</script>
+<template>
+<RadioGroup v-model="size" type="button">
+    <Radio value="mini">mini</Radio>
+    <Radio value="small">small</Radio>
+    <Radio value="medium">medium</Radio>
+    <Radio value="large">large</Radio>
+  </RadioGroup>
+  <Checkbox v-model="disabled">禁用</Checkbox>
+  <InputGroup>
+    <Select v-model="type" :options="options" :size="size" :disabled="disabled" style="width: 120px" />
+    <Input v-model="value" :size="size" :disabled="disabled" placeholder="选择后输入" />
+    <Button :size="size" :disabled="disabled">搜索</Button>
+  </InputGroup>
+  <InputGroup>
+    <Input v-model="value" :size="size" :disabled="disabled" error placeholder="错误态组合" />
+    <Select v-model="type" :options="options" :size="size" :disabled="disabled" style="width: 120px" />
+  </InputGroup>
+</template>
+```
+
+### 密码可见性
+
+`visibility=true` 表示显示明文，`false` 表示使用密码遮蔽。显隐按钮会触发 `visibility-change` 和 `update:visibility`。
+
+非受控密码默认 `defaultVisibility=true`。需要默认遮蔽时设置 `:default-visibility="false"`；禁用时显隐按钮也不可操作。
+
+`id`、`name`、`aria-label`、`aria-labelledby`、`aria-describedby`、`inputmode` 等原生属性会传给内部 input；`class` / `style` 保留在组件根节点。也可以通过 `inputAttrs` 集中传入原生属性。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputPassword } from 'x-next';
+import { ref } from 'vue';
+
+const password = ref('x-next-password');
+const visible = ref(false);
+</script>
+<template>
+<InputPassword
+    v-model="password"
+    v-model:visibility="visible"
+    placeholder="请输入密码"
+  />
+  <span>{{ visible ? '明文可见' : '密码已隐藏' }}</span>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./input-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/layout-api.md

@@ -0,0 +1,147 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Layout 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Layout API
+
+公开声明：`dist/components/layout/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| hasSidebar | 是否包含侧边栏，SSR 场景可用于避免样式闪动 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| 组件 | 插槽名 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| Layout | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| LayoutHeader | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| LayoutContent | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| LayoutFooter | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| LayoutSidebar | default | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## LayoutContent API
+
+公开声明：`dist/components/layout/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+未声明自身 props；包装透传能力见本页用法。
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## LayoutFooter API
+
+公开声明：`dist/components/layout/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+未声明自身 props；包装透传能力见本页用法。
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## LayoutHeader API
+
+公开声明：`dist/components/layout/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+未声明自身 props；包装透传能力见本页用法。
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## LayoutSidebar API
+
+公开声明：`dist/components/layout/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| theme | 侧边栏主题 | undefined &#124; "dark" &#124; "light" | 否 | "light" |
+| collapsed | 当前收起状态，可配合 v-model:collapsed 使用 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultCollapsed | 默认收起状态，非受控用法 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| collapsible | 是否可收起 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| width | 展开宽度 | undefined &#124; string &#124; number | 否 | 200 |
+| collapsedWidth | 收起宽度 | undefined &#124; number | 否 | 48 |
+| reverseArrow | 是否反转折叠箭头方向，右侧侧边栏可使用 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| breakpoint | 响应式断点 | undefined &#124; "xs" &#124; "sm" &#124; "md" &#124; "lg" &#124; "xl" &#124; "xxl" | 否 | 未声明 |
+| resizeDirections | 使用 ResizeBox 作为根组件后允许拖拽的方向 | undefined &#124; ("top" &#124; "bottom" &#124; "right" &#124; "left")[] | 否 | undefined |
+| hideTrigger | 是否隐藏折叠触发器 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| height | 见场景用法与类型 | undefined &#124; number | 否 | 透传内层组件；默认值见对应组件 |
+| minWidth | 见场景用法与类型 | undefined &#124; number | 否 | 透传内层组件；默认值见对应组件 |
+| minHeight | 见场景用法与类型 | undefined &#124; number | 否 | 透传内层组件；默认值见对应组件 |
+| maxHeight | 见场景用法与类型 | undefined &#124; number | 否 | 透传内层组件；默认值见对应组件 |
+| maxWidth | 见场景用法与类型 | undefined &#124; number | 否 | 透传内层组件；默认值见对应组件 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| collapse | 展开/收起时触发 | undefined &#124; ((...args: any[]) => any) & ((...args: any[]) => any) |
+| update:collapsed | 收起状态变化时触发 | undefined &#124; ((...args: any[]) => any) & ((...args: any[]) => any) |
+| breakpoint | 响应式断点触发时触发 | undefined &#124; ((...args: any[]) => any) & ((...args: any[]) => any) |
+| moving | 见场景用法与类型 | undefined &#124; (size: { width: number; height: number; }, ev: MouseEvent &#124; KeyboardEvent) => any |
+| update:width | 见场景用法与类型 | undefined &#124; (width: number) => any |
+| update:height | 见场景用法与类型 | undefined &#124; (height: number) => any |
+| movingStart | 见场景用法与类型 | undefined &#124; (ev: MouseEvent) => any |
+| movingEnd | 见场景用法与类型 | undefined &#124; (ev: MouseEvent) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Layout 用法](./layout.md)。

package/AI_USAGE/components/layout.md

@@ -0,0 +1,230 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Layout AI 使用
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。公开导出：`Layout, LayoutContent, LayoutFooter, LayoutHeader, LayoutSidebar`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./layout-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/layout`（包含 base.css、layout.css、resize-box.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/layout.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./layout-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+提供页头、侧边栏、内容区和页脚组合，适合搭建后台系统页面框架。
+
+
+### 何时使用
+
+- 页面需要稳定组织 Header、Sidebar、Content、Footer 等区域。
+- 后台系统需要侧边导航和主内容区联动。
+- 侧边栏需要支持折叠、响应式收起或拖拽调整宽度。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutHeader, LayoutSidebar, LayoutContent, LayoutFooter } from 'x-next';
+
+</script>
+<template>
+<Layout class="demo-layout">
+    <LayoutHeader>Header</LayoutHeader>
+    <Layout has-sidebar>
+      <LayoutSidebar :width="120">Sidebar</LayoutSidebar>
+      <LayoutContent>Content</LayoutContent>
+    </Layout>
+    <LayoutFooter>Footer</LayoutFooter>
+  </Layout>
+</template>
+```
+
+### 常见结构
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutHeader, LayoutContent, LayoutFooter, LayoutSidebar } from 'x-next';
+
+</script>
+<template>
+<Layout class="layout-doc-demo">
+    <LayoutHeader>Header</LayoutHeader>
+    <LayoutContent>Content</LayoutContent>
+    <LayoutFooter>Footer</LayoutFooter>
+  </Layout>
+
+  <Layout class="layout-doc-demo">
+    <LayoutHeader>Header</LayoutHeader>
+    <Layout has-sidebar>
+      <LayoutSidebar :width="128">Left</LayoutSidebar>
+      <LayoutContent>Content</LayoutContent>
+      <LayoutSidebar :width="128" reverse-arrow>Right</LayoutSidebar>
+    </Layout>
+    <LayoutFooter>Footer</LayoutFooter>
+  </Layout>
+</template>
+```
+
+### 可折叠侧边栏
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, LayoutContent, Space, Button } from 'x-next';
+import { ref } from 'vue';
+
+const collapsed = ref(false);
+</script>
+<template>
+<Layout class="layout-doc-demo" has-sidebar>
+    <LayoutSidebar
+      v-model:collapsed="collapsed"
+      collapsible
+      theme="dark"
+      :width="180"
+      :collapsed-width="56"
+    >
+      {{ collapsed ? '已收起' : '已展开' }}
+    </LayoutSidebar>
+    <LayoutContent>Content</LayoutContent>
+  </Layout>
+  <Space>
+    <Button @click="collapsed = false">展开</Button>
+    <Button @click="collapsed = true">收起</Button>
+  </Space>
+</template>
+```
+
+### 自定义触发器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, LayoutContent } from 'x-next';
+import { ref } from 'vue';
+
+const collapsed = ref(false);
+</script>
+<template>
+<Layout class="layout-doc-demo" has-sidebar>
+    <LayoutSidebar
+      v-model:collapsed="collapsed"
+      collapsible
+      :width="180"
+      :collapsed-width="64"
+    >
+      {{ collapsed ? 'Mini' : 'Custom Trigger' }}
+      <template #trigger="{ collapsed: slotCollapsed }">
+        {{ slotCollapsed ? '展开' : '收起' }}
+      </template>
+    </LayoutSidebar>
+    <LayoutContent>Content</LayoutContent>
+  </Layout>
+</template>
+```
+
+### 响应式与事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, LayoutContent } from 'x-next';
+import { ref } from 'vue';
+
+const collapsed = ref(false);
+
+const handleCollapse = (nextCollapsed: boolean, type: 'clickTrigger' | 'responsive') => {
+  console.log(nextCollapsed, type);
+};
+
+const handleBreakpoint = (nextCollapsed: boolean) => {
+  console.log(nextCollapsed);
+};
+</script>
+<template>
+<Layout class="layout-doc-demo" has-sidebar>
+    <LayoutSidebar
+      v-model:collapsed="collapsed"
+      collapsible
+      breakpoint="lg"
+      :width="190"
+      :collapsed-width="72"
+      @collapse="handleCollapse"
+      @breakpoint="handleBreakpoint"
+    >
+      {{ collapsed ? 'lg' : 'breakpoint="lg"' }}
+    </LayoutSidebar>
+    <LayoutContent>Content</LayoutContent>
+  </Layout>
+</template>
+```
+
+### 可拖拽侧边栏
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, LayoutContent } from 'x-next';
+import { ref } from 'vue';
+
+const sidebarWidth = ref(240);
+</script>
+<template>
+<Layout class="layout-doc-demo" has-sidebar>
+    <LayoutSidebar
+      :width="sidebarWidth"
+      :min-width="160"
+      :max-width="520"
+      :resize-directions="['right']"
+      @moving="(size) => {
+        sidebarWidth = size.width;
+      }"
+    >
+      拖动右侧边缘
+    </LayoutSidebar>
+    <LayoutContent>当前宽度：{{ sidebarWidth }}px</LayoutContent>
+  </Layout>
+</template>
+```
+
+### 与 Menu 组合
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, Menu, MenuItem, MenuSubMenu, LayoutContent } from 'x-next';
+const collapsed = ref(false);
+
+import { ref } from 'vue';
+
+const selectedKeys = ref(['overview']);
+</script>
+<template>
+<Layout class="layout-doc-demo" has-sidebar>
+    <LayoutSidebar collapsible theme="dark" :width="210" :collapsed-width="64">
+      <Menu v-model:selected-keys="selectedKeys" theme="dark">
+        <MenuItem key="overview">概览</MenuItem>
+        <MenuSubMenu key="workspace" title="工作台">
+          <MenuItem key="components">组件</MenuItem>
+          <MenuItem key="docs">文档</MenuItem>
+        </MenuSubMenu>
+      </Menu>
+    </LayoutSidebar>
+    <LayoutContent>Content</LayoutContent>
+  </Layout>
+</template>
+```
+
+### 已知限制
+
+- `collapsedWidth` 可以设为 `0`，但当前不会生成侧边栏外部的零宽特殊触发器；需要重新展开时请提供外部按钮或自定义布局。
+- `resizeDirections` 会让 Sidebar 复用 ResizeBox 作为根组件，拖拽事件请参考 ResizeBox 文档。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./layout-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。