x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/image.md

@@ -0,0 +1,465 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Image AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Image, ImagePreview, ImagePreviewAction, ImagePreviewGroup`；主要模型：v-model:preview-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./image-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/image`（包含 base.css、image.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/image.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./image-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于展示图片，并支持加载态、错误态、底部信息和预览。
+
+
+### 何时使用
+
+- 展示图片缩略图、封面、附件预览或带标题说明的图片内容。
+- 需要提供单图预览、预览组切换、缩放、旋转或自定义预览操作时。
+- 需要在图片加载中、加载失败时提供明确反馈时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image } from 'x-next';
+const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+</script>
+<template>
+<Image :src="imageSrc" width="160" height="120" fit="cover" alt="示例图片" />
+</template>
+```
+
+### 适应方式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image } from 'x-next';
+const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+</script>
+<template>
+<Image
+    :src="imageSrc"
+    width="120"
+    height="90"
+    fit="cover"
+    title="cover"
+    footer-position="outer"
+  />
+  <Image
+    :src="imageSrc"
+    width="120"
+    height="90"
+    fit="contain"
+    title="contain"
+    footer-position="outer"
+  />
+  <Image
+    :src="imageSrc"
+    width="120"
+    height="90"
+    fit="fill"
+    title="fill"
+    footer-position="outer"
+  />
+</template>
+```
+
+### 底部信息
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image, Button } from 'x-next';
+import { ref } from 'vue';
+
+  const footerActionCount = ref(0);
+  const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+</script>
+<template>
+<Image
+    :src="imageSrc"
+    width="180"
+    height="120"
+    title="组件封面"
+    description="底部信息覆盖在图片内部"
+    fit="cover"
+  />
+  <Image
+    :src="imageSrc"
+    width="180"
+    height="120"
+    title="外置说明"
+    description="footerPosition 设置为 outer"
+    footer-position="outer"
+    fit="cover"
+  />
+  <Image :src="imageSrc" width="240" height="140" title="底部操作" fit="cover">
+    <template #extra>
+      <Button size="mini" @click="footerActionCount++">收藏 {{ footerActionCount }}</Button>
+    </template>
+  </Image>
+</template>
+```
+
+### 加载和错误
+
+失败占位使用中性色背景，并保留图片圆角。可通过 `error` / `error-icon` 自定义内容；修改 `src` 后会重新进入加载流程，支持从失败地址恢复。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image } from 'x-next';
+const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+</script>
+<template>
+<Image :src="imageSrc" width="160" height="110" show-loader fit="cover" />
+  <Image src="data:image/png;base64,broken-image" width="160" height="110" alt="图片加载失败" />
+  <Image src="data:image/png;base64,broken-image" width="160" height="110">
+    <template #error-icon><span aria-hidden="true">◇</span></template>
+  </Image>
+  <Image src="data:image/png;base64,broken-image" width="160" height="110">
+    <template #error>
+      <div class="image-error">无法加载图片</div>
+    </template>
+  </Image>
+</template>
+<style scoped>
+.image-error {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    color: var(--x-color-text-secondary);
+    background: var(--x-color-fill-2);
+  }
+</style>
+```
+
+### 更换图片与错误恢复
+
+直接更新 `src`。组件会重置加载状态和旧图片节点；加载失败后可通过插槽中的按钮改回有效地址。下面的图片均是离线可用的低饱和风景插画，加载通常很快。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Image } from 'x-next';
+import { ref } from 'vue';
+  const landscape = (sky: string, hills: string) =>
+    'data:image/svg+xml,' +
+    encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="480" height="300"><rect width="480" height="300" fill="${sky}"/><path d="M0 230Q120 110 240 220T480 180V300H0Z" fill="${hills}"/></svg>`,
+    );
+  const landscapes = [landscape('#e8efec', '#a6bdb1'), landscape('#f0ebe4', '#bca996')];
+  const src = ref(landscapes[0]);
+  const state = ref('图片已选择');
+</script>
+<template>
+<Button @click="src = landscapes[0]">湖畔</Button>
+  <Button @click="src = landscapes[1]">山丘</Button>
+  <Button @click="src = 'data:image/png;base64,broken-image'">模拟失败</Button>
+  <Image
+    :src="src"
+    width="240"
+    height="150"
+    fit="cover"
+    show-loader
+    alt="可替换风景"
+    @load="state = '图片已加载'"
+    @error="state = '加载失败'"
+  >
+    <template #loader><div class="placeholder">正在准备图片…</div></template>
+    <template #error>
+      <div class="placeholder">
+        <span>图片暂时无法加载</span>
+        <Button size="mini" @click="src = landscapes[0]">恢复图片</Button>
+      </div>
+    </template>
+  </Image>
+  <span aria-live="polite">{{ state }}</span>
+</template>
+<style scoped>
+.placeholder {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    width: 100%;
+    height: 100%;
+    color: var(--x-color-text-secondary);
+    background: var(--x-color-fill-2);
+  }
+</style>
+```
+
+### 受控预览
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Image } from 'x-next';
+import { ref } from 'vue';
+
+  const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+  const previewVisible = ref(false);
+  const logs = ref<string[]>([]);
+  const onPreviewVisibleChange = (visible: boolean) => {
+    logs.value = [visible ? '已打开' : '已关闭', ...logs.value].slice(0, 4);
+  };
+</script>
+<template>
+<Button @click="previewVisible = true">打开预览</Button>
+  <Image
+    v-model:preview-visible="previewVisible"
+    :src="imageSrc"
+    width="180"
+    height="120"
+    fit="cover"
+    @preview-visible-change="onPreviewVisibleChange"
+  />
+  <p>当前：{{ previewVisible ? '已打开' : '已关闭' }}</p>
+  <p v-for="(log, index) in logs" :key="index">{{ log }}</p>
+</template>
+```
+
+### 预览组
+
+设置 `srcList` 时，预览内容以该列表为准，子图片作为打开对应下标的缩略图；缩略图与列表应保持相同顺序，也可以使用不同的缩略图与高清图片地址。不传 `srcList` 时，预览组自动收集子图片。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ImagePreviewGroup, Image } from 'x-next';
+import { ref } from 'vue';
+
+  const visible = ref(false);
+  const current = ref(0);
+  const images = [
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E',
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23f0ebe4%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23fcf5e6%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23d7cbbd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23bca996%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%23998571%22%2F%3E%3C%2Fsvg%3E',
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e9edf2%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23f7f5ef%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c7d1df%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a7b7ca%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%238098b2%22%2F%3E%3C%2Fsvg%3E',
+  ];
+  const onChange = (index: number) => {
+    console.log('current image:', index);
+  };
+</script>
+<template>
+<ImagePreviewGroup
+    v-model:visible="visible"
+    v-model:current="current"
+    :src-list="images"
+    infinite
+    @change="onChange"
+  >
+    <Image
+      v-for="(item, index) in images"
+      :key="item"
+      :src="item"
+      width="120"
+      height="84"
+      fit="cover"
+      :title="`风景 ${index + 1}`"
+      footer-position="outer"
+    />
+  </ImagePreviewGroup>
+  <p>当前图片：{{ current + 1 }} / {{ images.length }}</p>
+</template>
+```
+
+### 自定义预览操作
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image, ImagePreviewAction } from 'x-next';
+import { ref } from 'vue';
+
+  const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+  const logs = ref<string[]>([]);
+  const record = () => {
+    logs.value = ['点击了自定义预览操作', ...logs.value].slice(0, 4);
+  };
+</script>
+<template>
+<Image :src="imageSrc" width="180" height="120" fit="cover">
+    <template #preview-actions>
+      <ImagePreviewAction name="记录" @click="record">
+        <span>记</span>
+      </ImagePreviewAction>
+    </template>
+  </Image>
+  <p v-for="(log, index) in logs" :key="index">{{ log }}</p>
+</template>
+```
+
+### 关闭缩略图预览
+
+`preview=false` 时点击缩略图不会打开预览；在自动收集的预览组中，方向键和箭头切换会跳过该图片。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Image } from 'x-next';
+const imageSrc =
+    'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22300%22%20viewBox%3D%220%200%20480%20300%22%3E%3Crect%20width%3D%22480%22%20height%3D%22300%22%20fill%3D%22%23e8efec%22%2F%3E%3Ccircle%20cx%3D%22356%22%20cy%3D%2276%22%20r%3D%2230%22%20fill%3D%22%23faf6e9%22%2F%3E%3Cpath%20d%3D%22M0%20186Q94%2098%20196%20174T480%20150V300H0Z%22%20fill%3D%22%23c8d6cd%22%2F%3E%3Cpath%20d%3D%22M0%20216Q120%20160%20230%20202T480%20190V300H0Z%22%20fill%3D%22%23a6bdb1%22%2F%3E%3Cpath%20d%3D%22M0%20264Q124%20210%20260%20250T480%20242V300H0Z%22%20fill%3D%22%237f9e90%22%2F%3E%3C%2Fsvg%3E';
+</script>
+<template>
+<Image
+    :src="imageSrc"
+    width="180"
+    height="120"
+    fit="cover"
+    :preview="false"
+    title="仅展示图片"
+  />
+</template>
+```
+
+### 动态图片列表
+
+不传 `srcList` 时，修改子图片地址会更新当前预览，并保留注册顺序；移除图片后下标会调整，清空列表会关闭预览。使用稳定的 `key` 标识每张图片。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, ImagePreviewGroup, Image } from 'x-next';
+import { ref } from 'vue';
+
+  const makeImage = (color: string) =>
+    'data:image/svg+xml,' +
+    encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="${color}"/></svg>`,
+    );
+  const createImages = () =>
+    ['#a6bdb1', '#bca996', '#a7b7ca'].map((color, index) => ({
+      id: index + 1,
+      src: makeImage(color),
+    }));
+  const images = ref(createImages());
+  const visible = ref(false);
+  const current = ref(0);
+  const replaceFirst = () => {
+    if (images.value[0]) images.value[0].src = makeImage('#b8c9ba');
+  };
+  const restore = () => {
+    visible.value = false;
+    current.value = 0;
+    images.value = createImages();
+  };
+</script>
+<template>
+<Button :disabled="!images.length" @click="replaceFirst">替换第一张</Button>
+  <Button :disabled="!images.length" @click="images.shift()">移除第一张</Button>
+  <Button @click="images = []">清空图片</Button>
+  <Button @click="restore">恢复图片</Button>
+  <ImagePreviewGroup v-model:visible="visible" v-model:current="current">
+    <Image
+      v-for="item in images"
+      :key="item.id"
+      :src="item.src"
+      width="120"
+      height="84"
+      fit="cover"
+      :title="`风景 ${item.id}`"
+      footer-position="outer"
+    />
+  </ImagePreviewGroup>
+  <p>{{ images.length ? `当前图片：${current + 1} / ${images.length}` : '图片列表为空' }}</p>
+</template>
+```
+
+### 独立预览与自定义工具条
+
+预览工具条使用深色半透明背景，亮暗主题保持一致。将 `actionsLayout` 设为空数组可仅保留自定义操作；关闭后焦点返回打开预览的按钮。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, ImagePreview, ImagePreviewAction } from 'x-next';
+import { ref } from 'vue';
+  const visible = ref(false);
+  const count = ref(0);
+  const src =
+    'data:image/svg+xml,' +
+    encodeURIComponent(
+      '<svg xmlns="http://www.w3.org/2000/svg" width="480" height="300"><rect width="480" height="300" fill="#c8d6cd"/></svg>',
+    );
+</script>
+<template>
+<Button @click="visible = true">打开独立预览</Button>
+  <span>已记录 {{ count }} 次</span>
+  <ImagePreview v-model:visible="visible" :src="src" :actions-layout="[]">
+    <template #actions>
+      <ImagePreviewAction name="记录" @click="count++"><span>记</span></ImagePreviewAction>
+    </template>
+  </ImagePreview>
+</template>
+```
+
+### 容器内预览
+
+通过 `popupContainer` 指定宿主，可将预览限制在局部容器内；设置宽高并保留定位上下文。`defaultScale` 会限制在 0.25～5 倍，滚轮速率需大于 1，非法值会使用默认值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, ImagePreview } from 'x-next';
+import { ref } from 'vue';
+  const host = ref<HTMLElement>();
+  const visible = ref(false);
+  const src =
+    'data:image/svg+xml,' +
+    encodeURIComponent(
+      '<svg xmlns="http://www.w3.org/2000/svg" width="480" height="300"><rect width="480" height="300" fill="#a7b7ca"/></svg>',
+    );
+</script>
+<template>
+<Button @click="visible = true">在容器内预览</Button>
+  <div ref="host" class="preview-host">
+    <ImagePreview
+      v-model:visible="visible"
+      :src="src"
+      :popup-container="host"
+      :default-scale="0.75"
+    />
+  </div>
+</template>
+<style scoped>
+.preview-host {
+    position: relative;
+    width: 100%;
+    height: 300px;
+    overflow: hidden;
+  }
+</style>
+```
+
+### 交互说明
+
+- 预览打开后支持鼠标拖拽图片、滚轮缩放图片。
+- 图片加载成功后可聚焦缩略图，通过 Enter / Space 打开预览；加载中、错误或 `preview=false` 时不会打开。
+- Tab 在预览内循环，关闭或卸载时恢复打开前的焦点；快捷键仅作用于最上层弹层。
+- 工具条默认深色半透明，悬浮和焦点使用浅色透明高亮。可覆盖 `--x-image-preview-color-toolbar-bg` 等 token 定制。
+- 满屏按容器较小轴缩放以保留完整图片，并遵守 0.25～5 倍范围。预览失败显示明确反馈，组内可继续切换下一张。
+- `keyboard` 为 `true` 时，Esc 关闭预览，左右方向键切换预览组，上下方向键缩放，Space 还原到原始大小。
+- 使用受控的 `current` / `visible` 时，请接收对应更新事件或使用 `v-model`；列表为空时预览不会显示。
+- `srcList` 初始下标超界时会发送 `update:current` 请求修正，受控模式等待父组件更新下标后显示有效图片。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./image-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/input-api.md

@@ -0,0 +1,184 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Input 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Input API
+
+公开声明：`dist/components/form-input/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; string | 否 | 未声明 |
+| defaultValue | 默认值，非受控模式 | undefined &#124; string | 否 | "" |
+| size | 输入框尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| readonly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否为错误状态 | undefined &#124; false &#124; true | 否 | false |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| maxLength | 最大长度，支持仅提示错误 | undefined &#124; number &#124; { length: number; errorOnly?: boolean; } | 否 | 0 |
+| showWordLimit | 是否显示字数统计 | undefined &#124; false &#124; true | 否 | false |
+| wordLength | 字符长度计算方法 | undefined &#124; (value: string) => number | 否 | 未声明 |
+| wordSlice | 超长时的截取方法 | undefined &#124; (value: string, maxLength: number) => string | 否 | 未声明 |
+| inputAttrs | 内部 input 元素属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| type | 见场景用法与类型 | undefined &#124; "text" &#124; "password" | 否 | "text" |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: string) => any |
+| input | 用户输入时触发 | undefined &#124; (value: string, ev: Event) => any |
+| change | 失焦或按下回车且值变化时触发 | undefined &#124; (value: string, ev: Event) => any |
+| pressEnter | 按下回车时触发 | undefined &#124; (ev: KeyboardEvent) => any |
+| clear | 点击清除按钮时触发 | undefined &#124; (ev: MouseEvent) => any |
+| focus | 获取焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| prefix | 前缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 后缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| prepend | 前置标签 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| append | 后置标签 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | () => void |
+| blur | () => void |
+
+
+## InputGroup API
+
+公开声明：`dist/components/form-input/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+未声明自身 props；包装透传能力见本页用法。
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+## InputPassword API
+
+公开声明：`dist/components/form-input/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| disabled | 禁用输入和显隐按钮，继承 Form | undefined &#124; false &#124; true | 否 | false |
+| visibility | 密码是否以明文显示，受控属性 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultVisibility | 非受控模式下默认是否显示明文 | undefined &#124; false &#124; true | 否 | true |
+| invisibleButton | 是否显示密码显隐按钮 | undefined &#124; false &#124; true | 否 | true |
+| modelValue | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| error | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| size | 见场景用法与类型 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 透传内层组件；默认值见对应组件 |
+| defaultValue | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| placeholder | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| readonly | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| allowClear | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| inputAttrs | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
+| maxLength | 见场景用法与类型 | undefined &#124; number &#124; { length: number; errorOnly?: boolean; } | 否 | 透传内层组件；默认值见对应组件 |
+| showWordLimit | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| wordLength | 见场景用法与类型 | undefined &#124; (value: string) => number | 否 | 透传内层组件；默认值见对应组件 |
+| wordSlice | 见场景用法与类型 | undefined &#124; (value: string, maxLength: number) => string | 否 | 透传内层组件；默认值见对应组件 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| visibility-change | 见场景用法与类型 | undefined &#124; ((...args: any[]) => any) & ((...args: any[]) => any) |
+| update:visibility | 用于 v-model:visibility 同步 | undefined &#124; ((...args: any[]) => any) & ((...args: any[]) => any) |
+| update:modelValue | 见场景用法与类型 | undefined &#124; (value: string) => any |
+| focus | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+| clear | 见场景用法与类型 | undefined &#124; (ev: MouseEvent) => any |
+| blur | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+| change | 见场景用法与类型 | undefined &#124; (value: string, ev: Event) => any |
+| input | 见场景用法与类型 | undefined &#124; (value: string, ev: Event) => any |
+| pressEnter | 见场景用法与类型 | undefined &#124; (ev: KeyboardEvent) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
+
+
+## InputSearch API
+
+公开声明：`dist/components/form-input/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| searchButton | 使用后置搜索按钮 | undefined &#124; false &#124; true | 否 | false |
+| loading | 搜索加载状态 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 禁用输入和搜索按钮 | undefined &#124; false &#124; true | 否 | false |
+| size | 尺寸，继承 Form / 全局配置 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| buttonText | 搜索按钮文字 | undefined &#124; string | 否 | 未声明 |
+| buttonProps | 搜索按钮属性 | undefined &#124; { disabled?: boolean; block?: boolean; loading?: boolean; loadingFill?: boolean; debounce?: number; shape?: ButtonShape; link?: boolean; type?: ButtonTypes; htmlType?: ButtonHtmlType; status?: ButtonStatus; plain?: boolean; size?: ButtonSize; border?: boolean; narrow?: boolean; } | 否 | 未声明 |
+| modelValue | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| type | 见场景用法与类型 | undefined &#124; "text" &#124; "password" | 否 | 透传内层组件；默认值见对应组件 |
+| error | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| defaultValue | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| placeholder | 见场景用法与类型 | undefined &#124; string | 否 | 透传内层组件；默认值见对应组件 |
+| readonly | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| allowClear | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| inputAttrs | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
+| maxLength | 见场景用法与类型 | undefined &#124; number &#124; { length: number; errorOnly?: boolean; } | 否 | 透传内层组件；默认值见对应组件 |
+| showWordLimit | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
+| wordLength | 见场景用法与类型 | undefined &#124; (value: string) => number | 否 | 透传内层组件；默认值见对应组件 |
+| wordSlice | 见场景用法与类型 | undefined &#124; (value: string, maxLength: number) => string | 否 | 透传内层组件；默认值见对应组件 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| search | 点击可用搜索按钮时触发 | undefined &#124; ((value: string, ev: MouseEvent) => any) & ((value: string, ev: MouseEvent) => any) |
+| update:modelValue | 见场景用法与类型 | undefined &#124; (value: string) => any |
+| focus | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+| clear | 见场景用法与类型 | undefined &#124; (ev: MouseEvent) => any |
+| blur | 见场景用法与类型 | undefined &#124; (ev: FocusEvent) => any |
+| change | 见场景用法与类型 | undefined &#124; (value: string, ev: Event) => any |
+| input | 见场景用法与类型 | undefined &#124; (value: string, ev: Event) => any |
+| pressEnter | 见场景用法与类型 | undefined &#124; (ev: KeyboardEvent) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
+
+
+返回 [Input 用法](./input.md)。