代码演示
如何引入
<script lang="ts">
import { Image, ImagePreview } from '@fibrae/semi-ui-svelte';
</script>
基本用法
通过 src 指定图片路径即可获取一个具有预览功能的图片,通过 width,height 指定图片的宽高
代码
<script lang="ts">
import { Image } from '@fibrae/semi-ui-svelte';
</script>
<Image alt="Abstract colorful artwork" height={200} src="/assets/root-web-sites/abstract.jpg" width={360} />加载失败的占位图
fallback 接收字符串或 snippet:字符串是加载失败时显示的图片地址,snippet 渲染自定义内容;未设置时显示默认的加载失败图标
自定义加载失败占位图
代码
<script lang="ts">
import { IconUploadError } from '@fibrae/semi-icons-svelte';
import { Image } from '@fibrae/semi-ui-svelte';
</script>
<div style="display: flex; align-items: center; flex-direction: column">
<span>加载失败默认样式</span>
<Image alt="加载失败的图片" height={200} src="https://load-error.jpeg" width={200} />
<br />
<span>自定义加载失败占位图</span>
<Image alt="加载失败的图片" height={200} src="https://load-error.jpeg" width={200}>
{#snippet fallback()}
<IconUploadError style="font-size: 50px" />
{/snippet}
</Image>
</div>渐进加载
大图可通过 placeholder snippet 实现渐进加载,snippet 渲染的内容在图片加载成功前显示
代码
<script lang="ts">
import { Button, Image } from '@fibrae/semi-ui-svelte';
let timestamp = $state('');
</script>
<Image alt="Abstract colorful artwork" height={200} src="/assets/root-web-sites/abstract-big.png?{timestamp}" width={300}>
{#snippet placeholder()}
<Image alt="" height={200} preview={false} src="/assets/root-web-sites/abstract-small.jpeg" width={300} />
{/snippet}
</Image>
<br />
<Button style="margin-top: 10px" theme="solid" onclick={() => (timestamp = String(Date.now()))}>Reload</Button>自定义预览图片
可以通过设置 Image 组件的 src 和 preview 参数中的 src 不同来自定义预览图片
代码
<script lang="ts">
import { Image } from '@fibrae/semi-ui-svelte';
const preview = {
src: '/assets/root-web-sites/abstract-big.png',
};
</script>
<Image alt="Abstract colorful artwork" height={200} {preview} src="/assets/root-web-sites/abstract-small.jpeg" width={300} />多图预览
使用 ImagePreview 包裹 Image 即可实现多图片预览
ImagePreview 的 src 数组决定组内有哪些图片及其顺序,Image 不会向 ImagePreview 登记自己。Image 按自己的 src(或 preview.src)在列表中的位置打开预览,src 不在列表中的 Image 单独预览。逐张的标题与替代文本用 titles、alts 设置,与 src 逐项对应。
代码
<script lang="ts">
import { Image, ImagePreview } from '@fibrae/semi-ui-svelte';
const srcList = ['/assets/root-web-sites/abstract.jpg', '/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg', '/assets/root-web-sites/colorful.jpg'];
</script>
<ImagePreview src={srcList}>
{#each srcList as src, index (src)}
<Image alt="lamp{index + 1}" {src} style="margin-right: 5px" width={200} />
{/each}
</ImagePreview>单独使用预览组件
预览组件 ImagePreview 可以单独使用,通过 bind:visible(或 visible 加 onVisibleChange)控制是否预览,通过 src 传入可以预览的图片,通过 previewTitle(string)设置预览顶部的标题
代码
<script lang="ts">
import { Button, ImagePreview } from '@fibrae/semi-ui-svelte';
const srcList = ['/assets/root-web-sites/abstract.jpg', '/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg', '/assets/root-web-sites/colorful.jpg'];
let visible1 = $state(false);
let visible2 = $state(false);
</script>
<Button onclick={() => (visible1 = true)}>Preview single Image</Button>
<ImagePreview bind:visible={visible1} src="/assets/root-web-sites/sky.jpg" />
<br />
<Button style="margin-top: 20px" onclick={() => (visible2 = true)}>Preview multiple Images</Button>
<ImagePreview bind:visible={visible2} previewTitle="Scenery" src={srcList} />渲染在指定容器
可以通过 getPopupContainer 指定预览组件的父级 DOM(需要指定 position: relative),图片预览将会渲染至该 DOM 中。这会改变浮层 DOM 树位置,但不会改变视图渲染位置。
容器不是 document.body 时(包括只在 ConfigProvider 上设置 getPopupContainer),预览为非模态:不输出 aria-modal,不锁定 Tab,也不锁定页面滚动。getPopupContainer 返回 document.body 与不传相同。
代码
<script lang="ts">
import { Image, ImagePreview } from '@fibrae/semi-ui-svelte';
const srcList = ['/assets/root-web-sites/abstract.jpg', '/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg'];
let container = $state<HTMLDivElement>();
// called when the preview opens, after the container is mounted
const getPopupContainer = () => container as HTMLElement;
</script>
<div bind:this={container} style="height: 400px; position: relative">
<ImagePreview {getPopupContainer} src={srcList} style="height: 100%; display: flex; align-items: center; justify-content: center">
{#each srcList as src, index (src)}
<Image alt="lamp{index + 1}" {src} style="margin-right: 5px" width={200} />
{/each}
</ImagePreview>
</div>自定义预览底部操作区
可以使用 previewMenu snippet 自定义预览底部操作区域,参数为 MenuProps。ImagePreview 包裹的 Image 使用 ImagePreview 的 snippet,单独使用的 Image 使用自己的同名 snippet
如果想基于默认底部操作区域自定义预览底部操作区域,可以渲染 MenuProps 中的 menuItems snippet:它一次渲染全部默认项,顺序依次为上一张、页码、下一张、缩小、缩放滑块、放大、原始尺寸 / 适应页面、旋转、下载,自定义内容只能放在它之前或之后,不能插到默认项之间。只有未传 previewMenu 时,默认各项之间才有分隔线。
自定义预览顶部展示区
通过 title snippet(参数为 { title, index })替换预览顶部标题区的内容。有标题时预览对话框经 aria-labelledby 以标题区命名,名称即 snippet 渲染出的文字;没有标题时名称为语言包的「预览」。顶部的关闭按钮可用 closeIcon snippet 替换图标,切换箭头可用 leftIcon、rightIcon snippet(参数为 { index })替换图标
代码
<script lang="ts">
import { Image, ImagePreview } from '@fibrae/semi-ui-svelte';
const srcList = ['/assets/root-web-sites/abstract.jpg', '/assets/root-web-sites/sky.jpg'];
const titles = srcList.map((_, index) => `lamp${index + 1}`);
</script>
<ImagePreview src={srcList} {titles}>
{#snippet title({ title })}
<div style="width: 100%; height: 100%; display: flex; align-items: center; justify-content: center">
<span style="background: black; padding: 0 10px">自定义标题:{title}</span>
</div>
{/snippet}
<div>
{#each srcList as src, index (src)}
<Image alt={titles[index]} {src} style="margin-right: 5px" width={200} />
{/each}
</div>
</ImagePreview>API 参考
Image
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| alt | 图像描述,同时作为可预览缩略图的读屏名称。 | string | - |
| closeIcon | 自定义关闭图标;仅作用于该 Image 自己的预览,位于 ImagePreview 内时无效。 | Snippet | - |
| crossOrigin | 透传给原生 img 标签的 crossorigin。 | 'anonymous' | 'use-credentials' | - |
| fallback | 加载失败时显示的容错图片地址,或自定义内容的 snippet。 | string | Snippet | - |
| height | 图片显示高度,数值按 px 处理。 | string | number | - |
| imgCls | 自定义样式类名,透传给 img 节点。 | string | - |
| imgStyle | 自定义样式,透传给 img 节点。 | string | - |
| leftIcon | 自定义向左切换图标;仅作用于该 Image 自己的预览,位于 ImagePreview 内时无效。 | TypeSnippet<[ImagePreviewIconSnippetProps]> | - |
| onError | 图片加载失败时触发。 | Type(event: Event) => void | - |
| onLoad | 图片加载成功时触发。 | Type(event: Event) => void | - |
| placeholder | 图片未加载成功时的占位内容的 snippet。 | Snippet | - |
| preview | 预览配置,为 false 时禁用预览;对象只放数据与回调,自定义内容使用 Image 的 snippet。 | boolean | ImagePreviewProps | true |
| previewMenu | 自定义预览底部操作区;仅作用于该 Image 自己的预览,位于 ImagePreview 内时无效。 | TypeSnippet<[MenuProps]> | - |
| rightIcon | 自定义向右切换图标;仅作用于该 Image 自己的预览,位于 ImagePreview 内时无效。 | TypeSnippet<[ImagePreviewIconSnippetProps]> | - |
| setDownloadName | 设置图片下载名称。 | Type(src: string) => string | - |
| src | 图片获取地址。 | string | - |
| title | 替换预览顶部标题区的内容,有标题时对话框以 snippet 渲染出的文字命名;仅作用于该 Image 自己的预览,位于 ImagePreview 内时无效。 | TypeSnippet<[ImagePreviewTitleSnippetProps]> | - |
| width | 图片显示宽度,数值按 px 处理。 | string | number | - |
width、height 的数值按 px 处理。class、style 落在根元素上,其余未声明的原生属性与事件处理落在内部的 img 上。preview 对象接受 ImagePreview 的 props 与回调(onVisibleChange、onChange、onClose、onZoomIn、onZoomOut、onPrev、onNext、onRatioChange、onRotateLeft、onDownload、onDownloadError),但不含 lazyLoad、lazyLoadMargin、class、style(预览样式请用 previewCls、previewStyle);自定义节点不放在 preview 里,使用 Image 的 snippet。preview.src 为数组时,切换图片后回到「适应页面」。处于 ImagePreview 内的 Image 不使用 title、previewMenu、leftIcon、rightIcon、closeIcon snippet,以 ImagePreview 的 snippet 为准。
ImagePreview
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| adaptiveTip | 适应页面操作按钮提示。 | string | - |
| alts | 与 src 逐项对应的预览图片替代文本数组。 | (string | undefined)[] | - |
| children | 要预览的 Image 组件的 snippet。 | Snippet | - |
| closable | 是否显示关闭按钮。 | boolean | true |
| closeIcon | 自定义关闭图标的 snippet。 | Snippet | - |
| closeOnEsc | 按 Esc 是否关闭预览。 | boolean | true |
| crossOrigin | 透传给预览图片的原生 img 标签的 crossorigin。 | 'anonymous' | 'use-credentials' | - |
| currentIndex | 当前预览图片下标,可 bind:currentIndex;未绑定时由组件自行管理,初始为 0。 | number | - |
| disableDownload | 是否禁用下载。 | boolean | false |
| downloadTip | 下载操作按钮提示。 | string | - |
| getPopupContainer | 指定预览渲染的父级 DOM。容器不是 document.body 时预览为非模态,自定义容器需要 position: relative。 | Type() => HTMLElement | - |
| infinite | 是否无限循环。 | boolean | false |
| initialZoom | 预览图片初始缩放倍数,仅在首次打开或切换到该图片时生效一次,会被 minZoom 与 maxZoom 限制。 | number | - |
| lazyLoad | 是否开启懒加载。 | boolean | true |
| lazyLoadMargin | 懒加载的 rootMargin,相对视口计算;滚动祖先仍会裁剪。 | string | "0px 100px 100px 0px" |
| leftIcon | 自定义向左切换图标的 snippet,参数为 { index }。 | TypeSnippet<[ImagePreviewIconSnippetProps]> | - |
| maskClosable | 点击遮罩是否可关闭。 | boolean | true |
| maxZoom | 预览图片最大缩放倍数。 | number | 5 |
| minZoom | 预览图片最小缩放倍数。 | number | 0.1 |
| nextTip | 下一步操作按钮提示。 | string | - |
| onChange | 切换图片时触发。 | Type(index: number) => void | - |
| onClose | 点击关闭按钮或按 Esc 关闭时触发;点击遮罩关闭只触发 onVisibleChange。 | Type() => void | - |
| onDownload | 下载图片时触发。 | Type(src: string, index: number) => void | - |
| onDownloadError | 图片下载失败时触发。 | Type(src: string) => void | - |
| onNext | 向后切换图片时触发。 | Type(index: number) => void | - |
| onPrev | 向前切换图片时触发。 | Type(index: number) => void | - |
| onRatioChange | 切换原始尺寸与适应页面时触发。 | Type(type: RatioType) => void | - |
| onRotateLeft | 逆时针旋转图片时触发。 | Type(angle: number) => void | - |
| onVisibleChange | 可见状态变化时触发。 | Type(visible: boolean) => void | - |
| onZoomIn | 图片放大时触发。 | Type(zoom: number) => void | - |
| onZoomOut | 图片缩小时触发。 | Type(zoom: number) => void | - |
| originTip | 原始尺寸操作按钮提示。 | string | - |
| preLoad | 是否开启预加载。 | boolean | true |
| preLoadGap | 预加载的步长。 | number | 2 |
| previewCls | 自定义预览样式类名。 | string | - |
| previewMenu | 自定义预览底部操作区的 snippet,参数为 MenuProps,menuItems 是默认各项的 snippet,渲染时一次输出全部默认项。 | TypeSnippet<[MenuProps]> | - |
| previewStyle | 自定义预览样式。 | string | - |
| previewTitle | 预览顶部标题,同时作为预览对话框的读屏名称;titles 中当前图片的标题优先。 | string | - |
| prevTip | 上一步操作按钮提示。 | string | - |
| rightIcon | 自定义向右切换图标的 snippet,参数为 { index }。 | TypeSnippet<[ImagePreviewIconSnippetProps]> | - |
| rotateTip | 旋转操作按钮提示。 | string | - |
| setDownloadName | 设置图片下载名称。 | Type(src: string) => string | - |
| showTooltip | 是否展示底部操作区提示。 | boolean | false |
| src | 要预览的图片地址列表,决定组内图片及其顺序;包裹的 Image 按自己的 src(或 preview.src)在列表中的位置打开预览,不在列表中的 Image 单独预览。 | string | string[] | [] |
| title | 替换预览顶部标题区的内容的 snippet,参数为 { title, index }。有标题时对话框经 aria-labelledby 以标题区命名,名称即 snippet 渲染出的文字;没有标题时名称来自语言包。 | TypeSnippet<[ImagePreviewTitleSnippetProps]> | - |
| titles | 与 src 逐项对应的预览标题数组。 | (string | undefined)[] | - |
| viewerVisibleDelay | 隐藏预览操作按钮前的无操作时长,单位毫秒。 | number | 10000 |
| visible | 是否预览,可 bind:visible;未绑定时由组件自行管理,初始关闭。 | boolean | - |
| zIndex | 预览层层级。 | number | 1070 |
| zoomInTip | 放大操作按钮提示。 | string | - |
| zoomOutTip | 缩小操作按钮提示。 | string | - |
| zoomStep | 每次缩小或放大的比例。 | number | 0.1 |
class、style 与原生属性(如 aria-label、aria-labelledby)落在分组的根 div 上;传入 aria-label 或 aria-labelledby 且未传 role 时根元素带 role="group"。预览对话框渲染到 getPopupContainer(默认 document.body)中,名称来自 previewTitle,没有标题时来自语言包。
MenuProps
min、max、step、zoom 是百分比数值(如 min 为 10 表示 10%,step 为 10 表示每次 10%),与 ImagePreview 的 minZoom、maxZoom、zoomStep、initialZoom(倍数,如 0.1、5)单位不同。
| 属性 | 说明 | 类型 |
|---|---|---|
| curPage | 当前图片页下标 | number |
| disabledPrev | 是否禁用向左切换按钮 | boolean |
| disabledNext | 是否禁用向右切换按钮 | boolean |
| disabledZoomIn | 是否已放大到最大比例(放大按钮禁用) | boolean |
| disabledZoomOut | 是否已缩小到最小比例(缩小按钮禁用) | boolean |
| disableDownload | 是否禁用下载按钮 | boolean |
| max | 图片缩放最大比例(百分比) | number |
| min | 图片缩放最小比例(百分比) | number |
| onDownload | 图片下载的调用函数 | () => void |
| onZoomIn | 图片放大时的调用函数 | () => void |
| onZoomOut | 图片缩小时的调用函数 | () => void |
| onRatioClick | 切换原始尺寸与适应页面的调用函数 | () => void |
| onPrev | 向前切换图片的调用函数 | () => void |
| onNext | 向后切换图片的调用函数 | () => void |
| onRotateLeft | 逆时针旋转图片的调用函数 | () => void |
| onRotateRight | 顺时针旋转图片的调用函数 | () => void |
| ratio | 原始尺寸或适应页面按钮状态 | "adaptation" | "realSize" |
| step | 缩放的比例步长(百分比) | number |
| totalNum | 可预览的总图片数 | number |
| zoom | 当前图片缩放比例(百分比) | number |
| menuItems | 一次渲染全部默认底部预览操作区域各项的 snippet | Snippet |
Accessibility
ARIA
- 预览渲染在
document.body(默认)时是role="dialog"、aria-modal="true"的模态对话框;渲染到自定义容器(getPopupContainer返回其他元素,含 ConfigProvider 设置的容器)时是非模态对话框,不输出aria-modal。有标题(previewTitle,或组内图片的preview.previewTitle)时由标题命名,否则以语言包的「预览」作为名称 - 关闭、左右切换箭头,以及底部的上一张、下一张、缩小、放大、原始尺寸 / 适应页面、旋转、下载都是原生
button,读屏名称取自对应的prevTip、nextTip等属性,未设置时取自语言包;缩放滑块的名称是语言包的「缩放」,aria-valuetext为当前百分比 - 到达首张、末张或缩放上下限时,底部对应按钮带
aria-disabled="true",仍可聚焦,焦点不会丢失。没有当前图片(src为空列表)时下载按钮同样禁用 - 底部页码带
aria-live="polite",切换图片时读屏会读出新的位置 - 开启预览且图片加载成功后,Image 缩略图的根元素是
role="button"、tabindex="0"、aria-haspopup="dialog"的可聚焦按钮,名称取自图片的alt;preview为 false 或图片未加载成功时不可聚焦。关闭预览后焦点回到缩略图。ImagePreview 分组内的缩略图鼠标可点开,键盘同样可以:加载中或加载失败时也带按钮角色、可聚焦,Enter 或空格打开分组预览 - 预览图的
alt取自对应缩略图的alt(ImagePreview的src数组没有 alt,为空字符串)
键盘交互
- 焦点在缩略图上时,Enter 或空格打开预览
- 打开预览后焦点移入预览层。模态预览中 Tab 与 Shift + Tab 在预览层内的控件间循环,关闭后焦点回到打开前聚焦的元素;渲染到自定义容器的非模态预览不锁定 Tab,关闭时只有焦点仍在预览内或落在 body 上才回到打开前聚焦的元素,焦点已移到页面其他位置时保持不变
- Enter 或空格触发聚焦的按钮
- ← 与 → 切换上一张、下一张,RTL(ConfigProvider
direction="rtl")下左右互换。到首张或末张时与按钮一致:infinite为 true 时循环,否则不切换 - 焦点在输入框、文本域、下拉框或可编辑元素中(例如自定义页脚里的输入框),或同时按下 Alt、Ctrl、Meta、Shift 时,← 与 → 不切换图片;缩放滑块聚焦时 ← 与 → 调整缩放比例
- Esc 关闭预览(
closeOnEsc为 false 时不关闭) - 操作区因
viewerVisibleDelay隐藏后,按键或焦点移到操作区上会重新显示;焦点停在操作区时不再自动隐藏
设计变量
| Sass 变量 | 值 | 用法 |
|---|---|---|
| $transform_rotate-image_preview_spinner | var(--semi-transform_rotate-clockwise360deg) | 预览图像加载spin旋转角度 |
| $transform_scale3d-image_preview_image_img | 1, 1, 1 | 预览图片放大 |
| $transform_rotate-image_preview_image_img | var(--semi-transform_rotate-none) | 预览图片旋转角度 |
| $transition_duration-image_preview | 500ms | 预览图片透明度变化动画时间 |
| $transform_rotate-image_preview_icon_rtl | var(--semi-transform_rotate-clockwise180deg) | rtl模式下向前/向后切换图片按钮旋转角度 |
| $spacing-image_preview_icon-x | 24px | 图像预览中部左右调节icon与页面距离 |
| $spacing-image_preview_header-paddingY | 0 | 图像预览header部分上下内边距 |
| $spacing-image_preview_header-paddingX | 24px | 图像预览header部分左右内边距 |
| $spacing-image_preview_footer-paddingY | 0 | 图像预览footer操作区部分上下内边距 |
| $spacing-image_preview_footer-paddingX | 16px | 图像预览footer操作区部分左右内边距 |
| $spacing-image_preview_footer_page-marginY | 0 | 图像预览footer操作区图像页数据上下内边距 |
| $spacing-image_preview_footer_page-marginX | 12px | 图像预览footer操作区图像页数据左右内边距 |
| $spacing-image_preview_footer_slider-paddingY | 0 | 图像预览footer操作区slider上下内边距 |
| $spacing-image_preview_footer_slider-paddingX | 16px | 图像预览footer操作区slider左右内边距 |
| $spacing-image_preview_footer_slider_handle-marginTop | 8px | 图像预览footer操作区slider的滑块上外边距 |
| $spacing-image_preview_footer_divider-marginY | 0 | 图像预览footer操作区slider的分割线上下外边距 |
| $spacing-image_preview_footer_divider-marginX | 16px | 图像预览footer操作区slider的分割线左右外边距 |
| $spacing-image_preview_footer_gap-marginLeft | 16px | 图像预览footer操作区icon的左外边距 |
| $width-image_preview_footer_slider | 132px | 图像预览footer操作区slider宽度 |
| $width-image_preview_footer_slider_handle | 16px | 图像预览footer操作区滑块宽度 |
| $width-image_preview_icon | 40px | 图像预览footer操作区icon宽度 |
| $width-image_preview_header_close | 30px | 图像预览header部分的关闭热区宽度 |
| $height-image_preview_header | 60px | 图像预览header部分高度 |
| $height-image_preview_footer | 48px | 图像预览footer部分高度 |
| $height-image_preview_footer_slider | 2px | 图像预览footer中slider高度 |
| $height-image_preview_footer_slider_handle | 16px | 图像预览footer中slider的滑块高度 |
| $height-image_preview_icon | 40px | 图像预览footer操作区icon高度 |
| $height-image_preview_header_close | 30px | 图像预览header部分的关闭热区高度 |
| $radius-image | var(--semi-border-radius-small) | 图像圆角 |
| $radius-image_preview_footer | var(--semi-border-radius-medium) | 图像预览footer操作区圆角 |
| $color-image_status-bg | var(--semi-color-fill-0) | 图像加载失败背景颜色 |
| $color-image_status | var(--semi-color-disabled-text) | 图像状态加载失败 icon 颜色 |
| $color-image_preview_icon | var(--semi-color-white) | 图像预览中部左右icon背景色 |
| $color-image_preview_header | var(--semi-color-white) | 图像预览header文字颜色 |
| $color-image_preview_footer_icon | var(--semi-color-white) | 图像预览footer中icon颜色 |
| $color-image_preview_footer_slider_rail | var(--semi-color-white) | 图像预览footer中slider滑轨颜色 |
| $color-image_preview_disabled | rgba(249, 249, 249, 0.35) | 图像预览禁用颜色 |
| $color-image_preview_icon-bg | rgba(0, 0, 0, 0.75) | 图像预览中部icon背景色 |
| $color-image_header_close-bg | rgba(0, 0, 0, 0.75) | 图像预览header的关闭icon的hover背景色 |
| $color-image_preview_footer-bg | rgba(0, 0, 0, 0.75) | 图像预览footer部分背景色 |
| $color-image-preview_divider-bg | rgba(255, 255, 255, 0.5) | 图像预览footer中的分割线背景色 |
| $color-image_preview_image_spin | #ccc | 图像预览的加载状态颜色 |