FxImage 图片

在原生 img 基础上，支持自适应缩放、懒加载、加载占位、加载失败态、点击预览。不依赖任何 UI 框架，预览基于 FxImageViewer，样式走 @fx/styles token。

基础用法

fit 控制图片如何适应容器，同原生 object-fit。

<template>
  <div class="demo-image">
    <div v-for="fit in fits" :key="fit" class="block">
      <span class="demonstration">{{ fit }}</span>
      <FxImage style="width: 100px; height: 100px" :src="url" :fit="fit" />
    </div>
  </div>
</template>

<script setup lang="ts">
import type { ImageFitType } from "@fx/components"

const fits: ImageFitType[] = [
  "fill",
  "contain",
  "cover",
  "none",
  "scale-down",
]
const url =
  "https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg"
</script>

<style scoped>
.demo-image .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--fx-border-color);
  display: inline-block;
  width: 20%;
  min-width: 100px;
  box-sizing: border-box;
  vertical-align: top;
}
.demo-image .block:last-child {
  border-right: none;
}
.demo-image .demonstration {
  display: block;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>

占位

placeholder 插槽自定义图片尚未加载时的占位内容。

<template>
  <div class="demo-image__placeholder">
    <div class="block">
      <span class="demonstration">默认</span>
      <FxImage :src="src" />
    </div>
    <div class="block">
      <span class="demonstration">自定义</span>
      <FxImage :src="src">
        <template #placeholder>
          <div class="image-slot">加载中<span class="dot">...</span></div>
        </template>
      </FxImage>
    </div>
  </div>
</template>

<script setup lang="ts">
const src =
  "https://cube.elemecdn.com/6/94/4d3ea53c084bad6931a56d5158a48jpeg.jpeg"
</script>

<style scoped>
.demo-image__placeholder .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--fx-border-color);
  display: inline-block;
  width: 49%;
  box-sizing: border-box;
  vertical-align: top;
}
.demo-image__placeholder .demonstration {
  display: block;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
.demo-image__placeholder .fx-image {
  padding: 0 5px;
  max-width: 300px;
  max-height: 200px;
}
.image-slot {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 100%;
  height: 100%;
  background: var(--fx-color-surface-muted);
  color: var(--fx-text-color-secondary);
  font-size: 14px;
}
.dot {
  animation: dot 2s infinite steps(3, start);
  overflow: hidden;
}
@keyframes dot {
  0% {
    width: 0;
  }
  100% {
    width: 1.5em;
  }
}
</style>

加载失败

error 插槽自定义图片加载失败的占位内容。

<template>
  <div class="demo-image__error">
    <FxImage />
    <FxImage>
      <template #error>
        <div class="image-slot">
          <FxIcon name="ep:picture" size="30" />
        </div>
      </template>
    </FxImage>
  </div>
</template>

<style scoped>
.demo-image__error {
  display: flex;
  gap: 8px;
}
.demo-image__error .fx-image {
  max-width: 300px;
  max-height: 200px;
  width: 100%;
}
.image-slot {
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
  font-size: 30px;
  height: 200px;
  background: var(--fx-bg-color);
}
</style>

懒加载

lazy 开启懒加载，图片进入视口才加载。可用 scroll-container 指定滚动容器（默认最近的 overflow: auto/scroll 父级）。若浏览器支持原生懒加载（loading="lazy"），原生优先。

<template>
  <div class="demo-image__lazy">
    <FxImage v-for="url in urls" :key="url" :src="url" lazy />
  </div>
</template>

<script setup lang="ts">
const urls = [
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg",
  "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
  "https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg",
  "https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg",
  "https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg",
]
</script>

<style scoped>
.demo-image__lazy {
  height: 400px;
  overflow-y: auto;
}
.demo-image__lazy .fx-image {
  display: block;
  min-height: 200px;
  margin-bottom: 10px;
}
.demo-image__lazy .fx-image:last-child {
  margin-bottom: 0;
}
</style>

图片预览

preview-src-list 开启点击预览大图，initial-index 指定初始位置，show-progress 显示页码进度。

<template>
  <div class="demo-image__preview">
    <FxImage
      style="width: 100px; height: 100px"
      :src="url"
      :zoom-rate="1.2"
      :max-scale="7"
      :min-scale="0.2"
      :preview-src-list="srcList"
      show-progress
      :initial-index="4"
      fit="cover"
    />
  </div>
</template>

<script setup lang="ts">
const url =
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg"
const srcList = [
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg",
  "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
  "https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg",
  "https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg",
  "https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg",
  "https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg",
  "https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg",
]
</script>

手动打开预览

通过 ref 调用 showPreview() 手动打开预览。

<template>
  <FxBtn @click="open">手动打开预览</FxBtn>
  <FxImage
    ref="imageRef"
    style="width: 100px; height: 100px; display: block; margin-top: 12px"
    :src="url"
    :preview-src-list="srcList"
    fit="cover"
  />
</template>

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

const imageRef = ref<{ showPreview: () => void }>()
const url =
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg"
const srcList = [
  url,
  "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
]
function open() {
  imageRef.value?.showPreview()
}
</script>

自定义工具栏

toolbar 插槽自定义预览工具栏（作用域参数：actions / prev / next / reset / activeIndex / setActiveItem）。

<template>
  <div class="demo-image__custom">
    <FxImage
      style="width: 100px; height: 100px"
      :src="url"
      :preview-src-list="srcList"
      fit="cover"
    >
      <template #toolbar="{ actions, prev, next, reset }">
        <FxBtn size="small" @click="prev">上一张</FxBtn>
        <FxBtn size="small" @click="next">下一张</FxBtn>
        <FxBtn size="small" @click="actions('zoomIn')">放大</FxBtn>
        <FxBtn size="small" @click="actions('zoomOut')">缩小</FxBtn>
        <FxBtn size="small" @click="reset">还原</FxBtn>
      </template>
    </FxImage>
  </div>
</template>

<script setup lang="ts">
const url =
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg"
const srcList = [
  url,
  "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
]
</script>

自定义页码进度

progress 插槽自定义预览页码进度（作用域参数：activeIndex / total），优先级高于 show-progress。

<template>
  <FxImage
    style="width: 100px; height: 100px"
    :src="url"
    :preview-src-list="srcList"
    fit="cover"
  >
    <template #progress="{ activeIndex, total }">
      第 {{ activeIndex + 1 }} 张 / 共 {{ total }} 张
    </template>
  </FxImage>
</template>

<script setup lang="ts">
const url =
  "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg"
const srcList = [
  url,
  "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
]
</script>

API

Attributes

参数	说明	类型	默认值
src	图片源地址，同原生属性	string	''
fit	图片如何适应容器，同原生 object-fit	'' | 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'	''
hide-on-click-modal	开启预览时，是否可点击遮罩关闭预览	boolean	false
loading	浏览器加载图像策略，同原生	'eager' | 'lazy'	—
lazy	是否懒加载	boolean	false
scroll-container	懒加载时监听 scroll 的容器	string | HTMLElement	—
alt	原生 alt 属性	string	—
referrerpolicy	原生 referrerPolicy 属性	string	—
crossorigin	原生 crossorigin 属性	'' | 'anonymous' | 'use-credentials'	—
preview-src-list	开启图片预览	string[]	[]
z-index	预览 z-index	number	—
initial-index	初始预览索引，小于 url-list 长度	number	0
close-on-press-escape	是否可按 ESC 关闭 Image Viewer	boolean	true
preview-teleported	image-viewer 是否插入至 body 元素（父级属性 transform 时应设为 true）	boolean	false
infinite	是否无限循环预览	boolean	true
zoom-rate	缩放事件的缩放速率	number	1.2
scale	预览图像缩放	number	1
min-scale	缩放事件的最小缩放比例	number	0.2
max-scale	缩放事件的最大缩放比例	number	7
show-progress	是否显示预览图片进度条	boolean	false

Events

名称	说明	类型
load	图片加载完成（同原生）	(e: Event) => void
error	图片加载失败（同原生）	(e: Event) => void
switch	预览切换图片时	(index: number) => void
close	预览关闭时	() => void
show	预览打开时	() => void

Slots

名称	说明	作用域参数
placeholder	加载占位内容	—
error	加载失败占位内容	—
viewer	自定义预览区内容（透传给 FxImageViewer）	—
progress	预览页码进度（透传，优先级高于 show-progress）	{ activeIndex: number, total: number }
toolbar	预览工具栏（透传）	{ actions, prev, next, reset, activeIndex, setActiveItem }
viewer-error	预览图加载失败内容（透传）	{ activeIndex: number, src: string }

Exposes

名称	说明	类型
showPreview	手动打开预览	() => void

FxImageViewer 图片预览

独立于 FxImage 的全功能预览组件，也可被 FxImage 内部调用。支持多图切换、缩放、旋转、contain / original 模式切换、鼠标 / 触摸拖拽、滚轮、键盘、加载 / 错误态、过渡动画；还提供命令式 previewImage() 直接预览。

单图预览

<template>
  <FxBtn type="primary" @click="show = true">预览单张图片</FxBtn>
  <FxImageViewer v-model:show="show" :url-list="[url]" />
</template>

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

const show = ref(false)
const url = "https://picsum.photos/id/1024/1200/800"
</script>

多图预览

v-model:show 控制显隐，url-list 传多张地址，show-progress 显示页码。

<template>
  <FxBtn type="primary" @click="show = true">预览图片（多图）</FxBtn>
  <FxImageViewer v-model:show="show" :url-list="images" show-progress />
</template>

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

const show = ref(false)
const images = [
  "https://picsum.photos/id/1015/1200/800",
  "https://picsum.photos/id/1016/1200/800",
  "https://picsum.photos/id/1018/1200/800",
]
</script>

命令式调用

无需手动维护 show，previewImage(list) 直接预览，关闭时自动卸载 DOM。

<template>
  <div class="demo-viewer-imperative">
    <FxBtn @click="previewImage(images)">previewImage(多图)</FxBtn>
    <FxBtn @click="previewImage(single)">previewImage(单图)</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { previewImage } from "@fx/components"

const images = [
  "https://picsum.photos/id/1015/1200/800",
  "https://picsum.photos/id/1016/1200/800",
]
const single = "https://picsum.photos/id/1024/1200/800"
</script>

<style scoped>
.demo-viewer-imperative {
  display: flex;
  gap: 8px;
}
</style>

自定义工具栏

toolbar 插槽替换默认工具栏，作用域参数：actions / prev / next / reset / activeIndex / setActiveItem。

<template>
  <FxBtn type="primary" @click="show = true">打开自定义工具栏预览</FxBtn>
  <FxImageViewer v-model:show="show" :url-list="images" show-progress>
    <template #toolbar="{ actions, prev, next, reset }">
      <FxBtn size="small" @click="actions('zoomOut')">缩小</FxBtn>
      <FxBtn size="small" @click="actions('zoomIn')">放大</FxBtn>
      <FxBtn size="small" @click="reset">复位</FxBtn>
      <FxBtn size="small" @click="prev">上一张</FxBtn>
      <FxBtn size="small" @click="next">下一张</FxBtn>
    </template>
  </FxImageViewer>
</template>

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

const show = ref(false)
const images = [
  "https://picsum.photos/id/1015/1200/800",
  "https://picsum.photos/id/1016/1200/800",
]
</script>

默认工具栏与交互

不传 toolbar 时显示默认工具栏：放大 / 缩小、模式切换（contain / original）、左转 / 右转、多图时上一张 / 下一张、关闭、页码。

操作	效果
鼠标滚轮	按 zoom-rate 缩放
鼠标 / 触摸拖拽	移动图片
点击遮罩	关闭（hide-on-click-modal 默认开启）
ESC	关闭（close-on-press-escape）
空格	切换 contain / original 模式
← / →	切换上一张 / 下一张
↑ / ↓	放大 / 缩小

FxImageViewer API

Attributes

参数	说明	类型	默认值
url-list	用于预览的图片链接列表	string[]	[]
show（v-model）	是否显示	boolean	false
z-index	预览遮罩层 z-index（不传取递增值）	number	—
initial-index	初始预览索引	number	0
infinite	是否无限循环预览	boolean	true
hide-on-click-modal	是否可点击遮罩关闭	boolean	true
teleported	是否插入至 body	boolean	true
zoom-rate	缩放事件的缩放速率	number	1.2
scale	预览图像缩放	number	1
min-scale	缩放事件的最小缩放比例	number	0.2
max-scale	缩放事件的最大缩放比例	number	7
close-on-press-escape	是否可按 ESC 关闭	boolean	true
show-progress	是否显示进度条	boolean	false
crossorigin	原生 crossorigin 属性	'' | 'anonymous' | 'use-credentials'	—

Events

名称	说明	类型
update:show	显隐变化	(val: boolean) => void
close	关闭时	() => void
switch	切换图片时	(index: number) => void
rotate	旋转时	(deg: number) => void
error	图片加载失败	(evt: Event) => void

Slots

名称	说明	作用域参数
viewer	自定义内容（预览区）	—
progress	自定义进度内容（优先级高于 show-progress）	{ activeIndex: number, total: number }
toolbar	自定义工具栏内容	{ actions, prev, next, reset, activeIndex, setActiveItem }
viewer-error	自定义图像加载失败内容	{ activeIndex: number, src: string }

Exposes

名称	说明	类型
setActiveItem	手动切换到指定索引（支持负数 / 越界自动取模）	(index: number) => void

命令式

import { previewImage } from "@fx/components"

previewImage(["url1", "url2"]) // 多图
previewImage("url") // 单图（直接传字符串）

实现说明

• 懒加载：浏览器支持原生 loading="lazy" 时优先用原生；否则用 IntersectionObserver（节流 200ms，throttle 取自 @fx/utils）观察图片是否进入视口，进入后才设 src。
• 预览：preview-src-list 非空时，点击图片触发 show 事件并打开 FxImageViewer（透传 zoom / scale / progress / toolbar 等参数与插槽）。
• 样式：占位 / 失败背景走 --color-surface-muted，失败文字色走 --color-text-placeholder，不引用第三方 UI 库 CSS 变量。

类型声明

type FxImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'

// toolbar 插槽 actions() 的第二个参数
interface FxImageViewerActionOptions {
  enableTransition?: boolean
  zoomRate?: number
  rotateDeg?: number
}