x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/icon.md

@@ -0,0 +1,257 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Icon AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Icon`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./icon-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/base.css`（包含 base.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/icon.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./icon-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+通过统一的 `name` 调用内置图标，适合按钮、输入框、反馈提示和业务自定义图标。
+
+
+### 何时使用
+
+- 需要在组件中展示装饰性图形、状态图形或操作图形。
+- 希望通过统一的尺寸、颜色、旋转和加载动画控制图标。
+- 业务侧需要注册少量自定义 SVG，并以同一种方式调用。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+</script>
+<template>
+<Icon name="x" />
+  <Icon name="check" />
+  <Icon name="search" />
+  <Icon name="loading" />
+</template>
+```
+
+### 图标清单
+
+只展示每种图形的推荐名称，旧名仍可搜索和使用。点击复制推荐写法，避免在同一图形的多个名字间反复选择。
+
+### 推荐名称与旧名
+
+| 推荐名称 | 兼容旧名 |
+| --- | --- |
+| `x` | `close` |
+| `chevron-left / right / up / down` | `left / right / up / down` |
+| `circle-check / circle-x / circle-alert / circle-minus` | `check-circle / close-circle / alert-circle / minus-circle` |
+| `info` | `info-circle` |
+| `loader-circle` | `loading-circle` |
+| `pencil / lock-open / ellipsis` | `edit / unlock / more-horizontal` |
+| `chevrons-left / chevrons-right` | `double-left / double-right` |
+| `circle-question-mark` | `question-circle / circle-question` |
+| `eye-off / clock` | `eye-invisible / clock-circle` |
+| `rotate-ccw / rotate-cw` | `rotate-left / rotate-right` |
+
+`arrow-*` 是带箭杆的方向箭头，`chevron-*` 是单折角，`chevrons-*` 是双折角。三个系列用途不同，分别保留。
+
+`publicIconNames` 保留历史清单；新建图标选择器可使用 `canonicalIconNames`，需要兼容搜索时使用 `searchPublicIcons(keyword)`。旧名和推荐名始终引用同一份 SVG。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+import { computed, ref } from 'vue';
+  import { Message, searchPublicIcons } from 'x-next';
+
+  const keyword = ref('');
+  const iconColor = ref('#000000');
+  const iconSize = ref(24);
+  const iconStrokeWidth = ref(2);
+
+  const filteredIcons = computed(() => searchPublicIcons(keyword.value));
+
+  const getIconCode = (name: string) =>
+    name === 'loader-circle' ? `<x-icon name="${name}" spin />` : `<x-icon name="${name}" />`;
+
+  const copyIconName = async (name: string) => {
+    const code = getIconCode(name);
+
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error('Clipboard unavailable');
+      await navigator.clipboard.writeText(code);
+      Message.success(`已复制 ${code}`);
+    } catch {
+      Message.warning(`复制失败，请手动复制：${code}`);
+    }
+  };
+</script>
+<template>
+<div
+    class="icon-browser"
+    :style="{
+      '--icon-color': iconColor,
+      '--icon-size': `${iconSize}px`,
+    }"
+  >
+    <section class="icon-customizer">
+      <label>
+        <span>Color</span>
+        <span>
+          <input v-model="iconColor" type="color" />
+          <code>{{ iconColor }}</code>
+        </span>
+      </label>
+      <label>
+        <span>Size</span>
+        <em>{{ iconSize }}px</em>
+        <input v-model.number="iconSize" type="range" min="16" max="44" step="2" />
+      </label>
+      <label>
+        <span>Stroke</span>
+        <em>{{ iconStrokeWidth }}</em>
+        <input v-model.number="iconStrokeWidth" type="range" min="1" max="3" step="0.25" />
+      </label>
+    </section>
+
+    <input v-model="keyword" placeholder="搜索图标名称" />
+
+    <div class="icon-grid">
+      <button
+        v-for="name in filteredIcons"
+        :key="name"
+        :title="getIconCode(name)"
+        @click="copyIconName(name)"
+      >
+        <Icon
+          :name="name"
+          :size="iconSize"
+          :stroke-width="iconStrokeWidth"
+          :spin="name === 'loader-circle'"
+        />
+        <span>{{ name }}</span>
+      </button>
+    </div>
+  </div>
+</template>
+```
+
+### 尺寸和颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+</script>
+<template>
+<Icon name="search" :size="14" />
+  <Icon name="search" :size="20" />
+  <Icon name="search" size="1.75em" />
+  <Icon name="circle-check" :size="22" color="var(--x-color-success-6)" />
+  <Icon name="circle-x" :size="22" color="var(--x-color-danger-6)" />
+</template>
+```
+
+### 描边宽度
+
+Lucide 线性图标默认描边为 2，可通过 `stroke-width` 调整。动态图标 `loading` 使用自身动画规格；实心图形和品牌图标不会因描边参数变粗。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+</script>
+<template>
+<Icon name="search" :size="28" :stroke-width="1" />
+  <Icon name="search" :size="28" :stroke-width="2" />
+  <Icon name="search" :size="28" :stroke-width="3" />
+  <Icon name="circle-question-mark" :size="28" :stroke-width="1.5" />
+</template>
+```
+
+### 旋转和加载
+
+`loading` 是 X-Next 自带的变长圆弧，自动播放动画；`loader-circle` 是固定开口圆环，配合 `spin` 旋转。两种加载效果分别保留；系统减少动效时均显示静态图形。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+
+</script>
+<template>
+<Icon name="chevron-right" :rotate="90" />
+  <Icon name="chevron-right" :rotate="180" />
+  <Icon name="loading" />
+  <Icon name="loader-circle" spin />
+  <Icon name="loading" :size="22" color="var(--x-color-primary-6)" />
+</template>
+```
+
+### 图标按钮
+
+可点击图标应由按钮或其他可交互控件承载，并提供可访问名称。纯装饰性图标默认会设置 `aria-hidden="true"`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Icon } from 'x-next';
+
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "搜索", "title": "搜索" } satisfies HTMLAttributes;
+const nativeAttrs2 = { "aria-label": "下载", "title": "下载" } satisfies HTMLAttributes;
+const nativeAttrs3 = { "aria-label": "删除" } satisfies HTMLAttributes;
+const nativeAttrs4 = { "aria-label": "关闭", "title": "关闭" } satisfies HTMLAttributes;
+</script>
+<template>
+<Button v-bind="nativeAttrs1" shape="circle"  >
+    <Icon name="search" />
+  </Button>
+  <Button v-bind="nativeAttrs2" type="outline" shape="circle"  >
+    <Icon name="download" />
+  </Button>
+  <Button type="primary">
+    <template #icon>
+      <Icon name="plus" />
+    </template>
+    新建
+  </Button>
+  <Button v-bind="nativeAttrs3" type="text" status="danger" >
+    <template #icon>
+      <Icon name="trash" />
+    </template>
+    删除
+  </Button>
+  <Button v-bind="nativeAttrs4" type="text" shape="circle"  >
+    <Icon name="x" />
+  </Button>
+</template>
+```
+
+### 自定义图标
+
+`addIcon` 支持本地可信 SVG 字符串。`?raw` 是 Vite 的文件导入语法，表示把 `diamond.svg` 的文件内容作为字符串导入；如果不加 `?raw`，通常拿到的是打包后的图片 URL，不能直接注册成图标。不要把用户输入或远程接口返回的 SVG 直接传入 `addIcon`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Icon } from 'x-next';
+import { addIcon } from 'x-next';
+  const diamondSvg = '<svg viewBox="0 0 48 48"><path d="M24 4 44 24 24 44 4 24 4Z" fill="currentColor"/></svg>';
+
+  addIcon('demo-diamond', diamondSvg);
+</script>
+<template>
+<Icon name="demo-diamond" :size="22" color="var(--x-color-primary-6)" />
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./icon-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/image-api.md

@@ -0,0 +1,440 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Image 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Image API
+
+公开声明：`dist/components/image/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| renderToBody | 预览是否挂载到 body | undefined &#124; false &#124; true | 否 | true |
+| src | 图片地址 | undefined &#124; string | 否 | 未声明 |
+| width | 图片宽度 | undefined &#124; string &#124; number | 否 | 未声明 |
+| height | 图片高度 | undefined &#124; string &#124; number | 否 | 未声明 |
+| title | 标题 | undefined &#124; string | 否 | 未声明 |
+| description | 描述 | undefined &#124; string | 否 | 未声明 |
+| fit | 图片适应方式 | undefined &#124; "fill" &#124; "none" &#124; "contain" &#124; "cover" &#124; "scale-down" | 否 | 未声明 |
+| alt | 图片文字描述 | undefined &#124; string | 否 | 未声明 |
+| hideFooter | 是否隐藏底部信息；传 'never' 时加载错误也显示 footer | undefined &#124; false &#124; true &#124; "never" | 否 | false |
+| footerPosition | 底部信息位置 | undefined &#124; "outer" &#124; "inner" | 否 | "inner" |
+| showLoader | 是否显示加载中效果 | undefined &#124; false &#124; true | 否 | false |
+| preview | 是否开启预览 | undefined &#124; false &#124; true | 否 | true |
+| previewVisible | 预览是否打开 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPreviewVisible | 默认是否打开预览 | undefined &#124; false &#124; true | 否 | false |
+| previewProps | 预览配置 | undefined &#124; ImagePreviewProps | 否 | 未声明 |
+| footerClass | 底部区域类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| preview-visible-change | 见场景用法与类型 | undefined &#124; (_visible: boolean) => any |
+| update:previewVisible | 预览显隐变化时触发 | undefined &#124; (_visible: boolean) => any |
+| load | 当前图片加载成功 | undefined &#124; (_event: Event) => any |
+| error | 当前图片加载失败 | undefined &#124; (_event: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| error-icon | 自定义错误图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| error | 自定义错误内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| loader | 自定义加载内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| extra | 底部额外内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| preview-actions | 预览额外操作项 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface ImageProps {
+    src?: string;
+    width?: string | number;
+    height?: string | number;
+    title?: string;
+    description?: string;
+    fit?: '' | 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    hideFooter: boolean | 'never';
+    footerPosition: 'inner' | 'outer';
+    showLoader: boolean;
+    preview: boolean;
+    previewVisible?: boolean;
+    defaultPreviewVisible: boolean;
+    previewProps?: Partial<ImagePreviewProps>;
+    extra?: Slot;
+    error?: Slot;
+    loader?: Slot;
+    onPreviewVisibleChange?: (visible: boolean) => void;
+    onLoad?: (event: Event) => void;
+    onError?: (event: Event) => void;
+    renderToBody?: boolean;
+    footerClass?: string | unknown[] | Record<string, boolean>;
+    'onUpdate:previewVisible'?: (visible: boolean) => void;
+}
+
+interface ImagePreviewProps {
+    src?: string;
+    visible?: boolean;
+    defaultVisible?: boolean;
+    maskClosable?: boolean;
+    closable?: boolean;
+    actionsLayout?: string[];
+    popupContainer?: HTMLElement | string;
+    escToClose?: boolean;
+    keyboard?: boolean;
+    wheelZoom?: boolean;
+    defaultScale?: number;
+    zoomRate?: number;
+    renderToBody?: boolean;
+    'onUpdate:visible'?: (visible: boolean) => void;
+    groupArrowProps?: Record<string, any>;
+    onClose?: () => void;
+}
+
+interface ImagePreviewGroupProps extends Omit<ImagePreviewProps, 'src' | 'onClose'> {
+    srcList?: string[];
+    current?: number;
+    defaultCurrent: number;
+    infinite: boolean;
+    onChange?: (index: number) => void;
+    onVisibleChange?: (visible: boolean) => void;
+    'onUpdate:current'?: (index: number) => void;
+}
+
+interface ActionType {
+    key: string;
+    name: string;
+    content: RenderFunc;
+    onClick: () => void;
+    disabled?: boolean;
+}
+```
+
+
+## ImagePreview API
+
+公开声明：`dist/components/image/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| renderToBody | 是否通过 Teleport 挂载到宿主容器 | undefined &#124; false &#124; true | 否 | true |
+| src | 图片地址 | undefined &#124; string | 否 | 未声明 |
+| visible | 是否显示预览 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultVisible | 默认是否显示预览 | undefined &#124; false &#124; true | 否 | false |
+| maskClosable | 点击遮罩是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| closable | 是否显示关闭按钮 | undefined &#124; false &#124; true | 否 | true |
+| actionsLayout | 操作项布局 | undefined &#124; string[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| inGroup | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| groupArrowProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | {} |
+| escToClose | 是否支持 Esc 关闭 | undefined &#124; false &#124; true | 否 | true |
+| wheelZoom | 是否支持滚轮缩放 | undefined &#124; false &#124; true | 否 | true |
+| keyboard | 是否支持键盘控制 | undefined &#124; false &#124; true | 否 | true |
+| defaultScale | 默认缩放比 | undefined &#124; number | 否 | 1 |
+| zoomRate | 缩放速率 | undefined &#124; number | 否 | 1.1 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| close | 点击关闭按钮、遮罩或按 Esc 关闭时触发 | undefined &#124; (...args: any[]) => any |
+| update:visible | 预览显隐变化时触发 | undefined &#124; (...args: any[]) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| actions | 自定义额外操作项 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface ImageProps {
+    src?: string;
+    width?: string | number;
+    height?: string | number;
+    title?: string;
+    description?: string;
+    fit?: '' | 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    hideFooter: boolean | 'never';
+    footerPosition: 'inner' | 'outer';
+    showLoader: boolean;
+    preview: boolean;
+    previewVisible?: boolean;
+    defaultPreviewVisible: boolean;
+    previewProps?: Partial<ImagePreviewProps>;
+    extra?: Slot;
+    error?: Slot;
+    loader?: Slot;
+    onPreviewVisibleChange?: (visible: boolean) => void;
+    onLoad?: (event: Event) => void;
+    onError?: (event: Event) => void;
+    renderToBody?: boolean;
+    footerClass?: string | unknown[] | Record<string, boolean>;
+    'onUpdate:previewVisible'?: (visible: boolean) => void;
+}
+
+interface ImagePreviewProps {
+    src?: string;
+    visible?: boolean;
+    defaultVisible?: boolean;
+    maskClosable?: boolean;
+    closable?: boolean;
+    actionsLayout?: string[];
+    popupContainer?: HTMLElement | string;
+    escToClose?: boolean;
+    keyboard?: boolean;
+    wheelZoom?: boolean;
+    defaultScale?: number;
+    zoomRate?: number;
+    renderToBody?: boolean;
+    'onUpdate:visible'?: (visible: boolean) => void;
+    groupArrowProps?: Record<string, any>;
+    onClose?: () => void;
+}
+
+interface ImagePreviewGroupProps extends Omit<ImagePreviewProps, 'src' | 'onClose'> {
+    srcList?: string[];
+    current?: number;
+    defaultCurrent: number;
+    infinite: boolean;
+    onChange?: (index: number) => void;
+    onVisibleChange?: (visible: boolean) => void;
+    'onUpdate:current'?: (index: number) => void;
+}
+
+interface ActionType {
+    key: string;
+    name: string;
+    content: RenderFunc;
+    onClick: () => void;
+    disabled?: boolean;
+}
+```
+
+
+## ImagePreviewAction API
+
+公开声明：`dist/components/image/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| name | 操作项名称，会用于 tooltip 和可访问标签 | undefined &#124; string | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface ImageProps {
+    src?: string;
+    width?: string | number;
+    height?: string | number;
+    title?: string;
+    description?: string;
+    fit?: '' | 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    hideFooter: boolean | 'never';
+    footerPosition: 'inner' | 'outer';
+    showLoader: boolean;
+    preview: boolean;
+    previewVisible?: boolean;
+    defaultPreviewVisible: boolean;
+    previewProps?: Partial<ImagePreviewProps>;
+    extra?: Slot;
+    error?: Slot;
+    loader?: Slot;
+    onPreviewVisibleChange?: (visible: boolean) => void;
+    onLoad?: (event: Event) => void;
+    onError?: (event: Event) => void;
+    renderToBody?: boolean;
+    footerClass?: string | unknown[] | Record<string, boolean>;
+    'onUpdate:previewVisible'?: (visible: boolean) => void;
+}
+
+interface ImagePreviewProps {
+    src?: string;
+    visible?: boolean;
+    defaultVisible?: boolean;
+    maskClosable?: boolean;
+    closable?: boolean;
+    actionsLayout?: string[];
+    popupContainer?: HTMLElement | string;
+    escToClose?: boolean;
+    keyboard?: boolean;
+    wheelZoom?: boolean;
+    defaultScale?: number;
+    zoomRate?: number;
+    renderToBody?: boolean;
+    'onUpdate:visible'?: (visible: boolean) => void;
+    groupArrowProps?: Record<string, any>;
+    onClose?: () => void;
+}
+
+interface ImagePreviewGroupProps extends Omit<ImagePreviewProps, 'src' | 'onClose'> {
+    srcList?: string[];
+    current?: number;
+    defaultCurrent: number;
+    infinite: boolean;
+    onChange?: (index: number) => void;
+    onVisibleChange?: (visible: boolean) => void;
+    'onUpdate:current'?: (index: number) => void;
+}
+
+interface ActionType {
+    key: string;
+    name: string;
+    content: RenderFunc;
+    onClick: () => void;
+    disabled?: boolean;
+}
+```
+
+
+## ImagePreviewGroup API
+
+公开声明：`dist/components/image/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| renderToBody | 是否挂载到 body | undefined &#124; false &#124; true | 否 | true |
+| srcList | 图片列表；设置后不再收集子 Image 的图片信息 | undefined &#124; string[] | 否 | 未声明 |
+| current | 当前图片下标 | undefined &#124; number | 否 | 未声明 |
+| defaultCurrent | 默认图片下标 | undefined &#124; number | 否 | 0 |
+| infinite | 是否无限循环 | undefined &#124; false &#124; true | 否 | false |
+| visible | 是否显示预览 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultVisible | 默认是否显示预览 | undefined &#124; false &#124; true | 否 | false |
+| maskClosable | 点击遮罩是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| closable | 是否显示关闭按钮 | undefined &#124; false &#124; true | 否 | true |
+| actionsLayout | 操作项布局 | undefined &#124; string[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| change | 切换图片时触发 | undefined &#124; (...args: any[]) => any |
+| update:current | 当前图片下标变化时触发 | undefined &#124; (...args: any[]) => any |
+| visible-change | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| update:visible | 预览显隐变化时触发 | undefined &#124; (...args: any[]) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 图片列表内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| actions | 自定义额外操作项，插槽参数为 { url } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface ImageProps {
+    src?: string;
+    width?: string | number;
+    height?: string | number;
+    title?: string;
+    description?: string;
+    fit?: '' | 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    hideFooter: boolean | 'never';
+    footerPosition: 'inner' | 'outer';
+    showLoader: boolean;
+    preview: boolean;
+    previewVisible?: boolean;
+    defaultPreviewVisible: boolean;
+    previewProps?: Partial<ImagePreviewProps>;
+    extra?: Slot;
+    error?: Slot;
+    loader?: Slot;
+    onPreviewVisibleChange?: (visible: boolean) => void;
+    onLoad?: (event: Event) => void;
+    onError?: (event: Event) => void;
+    renderToBody?: boolean;
+    footerClass?: string | unknown[] | Record<string, boolean>;
+    'onUpdate:previewVisible'?: (visible: boolean) => void;
+}
+
+interface ImagePreviewProps {
+    src?: string;
+    visible?: boolean;
+    defaultVisible?: boolean;
+    maskClosable?: boolean;
+    closable?: boolean;
+    actionsLayout?: string[];
+    popupContainer?: HTMLElement | string;
+    escToClose?: boolean;
+    keyboard?: boolean;
+    wheelZoom?: boolean;
+    defaultScale?: number;
+    zoomRate?: number;
+    renderToBody?: boolean;
+    'onUpdate:visible'?: (visible: boolean) => void;
+    groupArrowProps?: Record<string, any>;
+    onClose?: () => void;
+}
+
+interface ImagePreviewGroupProps extends Omit<ImagePreviewProps, 'src' | 'onClose'> {
+    srcList?: string[];
+    current?: number;
+    defaultCurrent: number;
+    infinite: boolean;
+    onChange?: (index: number) => void;
+    onVisibleChange?: (visible: boolean) => void;
+    'onUpdate:current'?: (index: number) => void;
+}
+
+interface ActionType {
+    key: string;
+    name: string;
+    content: RenderFunc;
+    onClick: () => void;
+    disabled?: boolean;
+}
+```
+
+
+返回 [Image 用法](./image.md)。