Image 图片

用于展示图片，并支持加载态、错误态、底部信息和预览。

何时使用

展示图片缩略图、封面、附件预览或带标题说明的图片内容。
需要提供单图预览、预览组切换、缩放、旋转或自定义预览操作时。
需要在图片加载中、加载失败时提供明确反馈时。

基础用法

vue

<template>
  <x-image :src="imageSrc" width="160" height="120" fit="cover" alt="示例图片" />
</template>

<script setup lang="ts">
const imageSrc = '...';
</script>

适应方式

vue

<template>
  <x-image :src="imageSrc" width="120" height="90" fit="cover" title="cover" />
  <x-image :src="imageSrc" width="120" height="90" fit="contain" title="contain" />
  <x-image :src="imageSrc" width="120" height="90" fit="fill" title="fill" />
</template>

底部信息

vue

<template>
  <x-image
    :src="imageSrc"
    width="180"
    height="120"
    title="组件封面"
    description="底部信息覆盖在图片内部"
    fit="cover"
  />
  <x-image
    :src="imageSrc"
    width="180"
    height="120"
    title="外置说明"
    description="footerPosition 设置为 outer"
    footer-position="outer"
    fit="cover"
  />
</template>

加载和错误

vue

<template>
  <x-image :src="imageSrc" width="160" height="110" show-loader fit="cover" />
  <x-image src="/missing-image-demo.png" width="160" height="110" alt="图片加载失败" />
  <x-image src="/missing-image-demo.png" width="160" height="110">
    <template #error>
      <div class="image-error">无法加载图片</div>
    </template>
  </x-image>
</template>

受控预览

当前：已关闭

vue

<template>
  <x-button @click="previewVisible = true">打开预览</x-button>
  <x-image
    v-model:preview-visible="previewVisible"
    :src="imageSrc"
    width="180"
    height="120"
    fit="cover"
    @preview-visible-change="onPreviewVisibleChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const imageSrc = '...';
const previewVisible = ref(false);
const onPreviewVisibleChange = (visible: boolean) => {
  console.log('preview visible:', visible);
};
</script>

预览组

当前图片：1 / 3

vue

<template>
  <x-image-preview-group
    v-model:visible="visible"
    v-model:current="current"
    :src-list="images"
    infinite
    @change="onChange"
  >
    <x-image
      v-for="(item, index) in images"
      :key="item"
      :src="item"
      width="120"
      height="84"
      fit="cover"
      :title="`图片 ${index + 1}`"
    />
  </x-image-preview-group>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(false);
const current = ref(0);
const images = ['...', '...', '...'];
const onChange = (index: number) => {
  console.log('current image:', index);
};
</script>

自定义预览操作

vue

<template>
  <x-image :src="imageSrc" width="180" height="120" fit="cover">
    <template #preview-actions>
      <x-image-preview-action name="记录" @click="record">
        <span>记</span>
      </x-image-preview-action>
    </template>
  </x-image>
</template>

<script setup lang="ts">
const record = () => {
  console.log('custom preview action');
};
</script>

按需导入

import { Image, ImagePreview, ImagePreviewGroup, ImagePreviewAction } from 'x-next';

Image Props

参数	说明	类型	默认值
`src`	图片地址	`string`	`-`
`width`	图片宽度	`string \| number`	`-`
`height`	图片高度	`string \| number`	`-`
`title`	标题	`string`	`-`
`description`	描述	`string`	`-`
`fit`	图片适应方式	`'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'`	`-`
`alt`	图片文字描述	`string`	`-`
`hideFooter`	是否隐藏底部信息；传 `'never'` 时加载错误也显示 footer	`boolean \| 'never'`	`false`
`footerPosition`	底部信息位置	`'inner' \| 'outer'`	`'inner'`
`showLoader`	是否显示加载中效果	`boolean`	`false`
`preview`	是否开启预览	`boolean`	`true`
`previewVisible`	预览是否打开	`boolean`	`undefined`
`defaultPreviewVisible`	默认是否打开预览	`boolean`	`false`
`previewProps`	预览配置	`ImagePreviewProps`	`-`
`footerClass`	底部区域类名	`string \| array \| object`	`-`
`renderToBody`	预览是否挂载到 body	`boolean`	`true`

Image Events

事件名	说明	回调参数
`update:previewVisible`	预览显隐变化时触发	`visible: boolean`
`preview-visible-change`	预览显隐变化时触发	`visible: boolean`

Image Slots

插槽名	说明
`error-icon`	自定义错误图标
`error`	自定义错误内容
`loader`	自定义加载内容
`extra`	底部额外内容
`preview-actions`	预览额外操作项

ImagePreview Props

参数	说明	类型	默认值
`src`	图片地址	`string`	`-`
`visible`	是否显示预览	`boolean`	`undefined`
`defaultVisible`	默认是否显示预览	`boolean`	`false`
`maskClosable`	点击遮罩是否关闭	`boolean`	`true`
`closable`	是否显示关闭按钮	`boolean`	`true`
`actionsLayout`	操作项布局	`string[]`	`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize']`
`popupContainer`	弹出层挂载容器	`string \| HTMLElement`	`document.body`
`escToClose`	是否支持 Esc 关闭	`boolean`	`true`
`wheelZoom`	是否支持滚轮缩放	`boolean`	`true`
`keyboard`	是否支持键盘控制	`boolean`	`true`
`defaultScale`	默认缩放比	`number`	`1`
`zoomRate`	缩放速率	`number`	`1.1`

ImagePreview Events

事件名	说明	回调参数
`update:visible`	预览显隐变化时触发	`visible: boolean`
`close`	点击关闭按钮、遮罩或按 Esc 关闭时触发	`-`

ImagePreview Slots

插槽名	说明
`actions`	自定义额外操作项

ImagePreviewGroup Props

参数	说明	类型	默认值
`srcList`	图片列表；设置后不再收集子 Image 的图片信息	`string[]`	`-`
`current`	当前图片下标	`number`	`undefined`
`defaultCurrent`	默认图片下标	`number`	`0`
`infinite`	是否无限循环	`boolean`	`false`
`visible`	是否显示预览	`boolean`	`undefined`
`defaultVisible`	默认是否显示预览	`boolean`	`false`
`maskClosable`	点击遮罩是否关闭	`boolean`	`true`
`closable`	是否显示关闭按钮	`boolean`	`true`
`actionsLayout`	操作项布局	`string[]`	`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize']`
`popupContainer`	弹出层挂载容器	`string \| HTMLElement`	`-`
`renderToBody`	是否挂载到 body	`boolean`	`true`

ImagePreviewGroup Events

事件名	说明	回调参数
`change`	切换图片时触发	`index: number`
`update:current`	当前图片下标变化时触发	`index: number`
`visible-change`	预览显隐变化时触发	`visible: boolean`
`update:visible`	预览显隐变化时触发	`visible: boolean`

ImagePreviewGroup Slots

插槽名	说明
`default`	图片列表内容
`actions`	自定义额外操作项，插槽参数为 `{ url }`

ImagePreviewAction Props

参数	说明	类型	默认值
`name`	操作项名称，会用于 tooltip 和可访问标签	`string`	`-`
`disabled`	是否禁用	`boolean`	`false`

交互说明

预览打开后支持鼠标拖拽图片、滚轮缩放图片。
keyboard 为 true 时，Esc 关闭预览，左右方向键切换预览组，上下方向键缩放，Space 还原到原始大小。

Image 图片 ​

何时使用 ​

基础用法 ​

适应方式 ​

底部信息 ​

加载和错误 ​

受控预览 ​

预览组 ​

自定义预览操作 ​

按需导入 ​

Image Props ​

Image Events ​

Image Slots ​

ImagePreview Props ​

ImagePreview Events ​

ImagePreview Slots ​

ImagePreviewGroup Props ​

ImagePreviewGroup Events ​

ImagePreviewGroup Slots ​

ImagePreviewAction Props ​

交互说明 ​

Image 图片

何时使用

基础用法

适应方式

底部信息

加载和错误

受控预览

预览组

自定义预览操作

按需导入

Image Props

Image Events

Image Slots

ImagePreview Props

ImagePreview Events

ImagePreview Slots

ImagePreviewGroup Props

ImagePreviewGroup Events

ImagePreviewGroup Slots

ImagePreviewAction Props

交互说明