Image 图片
图片容器，在保留原生 img 的特性下，支持懒加载，自定义占位、加载失败、图片预览等。
基础用法
可通过 fit 确定图片如何适应到容器框，同原生 object-fit。
fill
加载中...
contain
加载中...
cover
加载中...
none
加载中...
scale-down
加载中...
基础用法
占位内容与加载失败
可通过 placeholder 和 error 插槽自定义占位内容。
默认错误
加载中...
自定义错误
加载中...
占位内容与加载失败
懒加载
TIP
浏览器原生支持的 loading 属性。您可以尝试使用 loading="lazy" 替换之前的 lazy="true"。
如果当前浏览器支持原生图片延迟加载，则先使用原生能力，否则将使用滚动监听实现相同效果。
可通过 lazy 开启懒加载功能，当图片滚动到可视范围内才会加载。可通过 scroll-container 来设置滚动容器，若未定义，则为最近一个 overflow 值为 auto 或 scroll 的父元素。
加载中...
加载中...
加载中...
加载中...
加载中...
加载中...
懒加载
图片预览
可通过 preview-src-list 开启预览功能。
加载中...
图片预览
手动调用预览
可通过 yh-image-viewer 组件手动调用预览功能，这在某些不需要显示缩略图，只需在点击某个元素（如按钮或文字链接）时唤起预览的场景中非常有用。同时也支持手动调用 viewerjs 模式。
手动调用预览
Viewer.js 预览（扩展）
当内置预览器无法满足需求时，可以切换为功能更强大的 viewerjs 模式。它支持幻灯片播放、全屏、翻转、缩略图导航等高级特性。
加载中...
Viewer.js 高级预览
在 Nuxt 中使用
YhImage 与 YhImageViewer 可直接在 Nuxt 项目中使用。SSR 阶段会先输出稳定的图片结构，懒加载监听与预览挂载会在客户端激活后继续接管。
Nuxt SSR Loading...
支持自动导入与 SSR 占位内容渲染
Nuxt 中使用
SSR 注意事项：
- 支持在服务端渲染占位插槽内容。
lazy会在客户端激活后开始侦测可视区域。- 预览器打开时会在客户端挂载到
body。 - 注册 YH-UI Nuxt 模块后可直接使用自动导入。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| src | 图片源地址 | string | '' |
| fit | 图片适应容器的方式，对应原生 object-fit | '' | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | '' |
| lazy | 是否启用懒加载 | boolean | false |
| preview-src-list | 内置预览器使用的图片列表 | string[] | [] |
| z-index | 预览层级 | number | undefined |
| initial-index | 打开预览时的起始索引 | number | 0 |
| close-on-press-escape | 按下 Esc 是否关闭预览 | boolean | true |
| hide-on-click-modal | 点击遮罩层是否关闭预览 | boolean | false |
| infinite | 预览时是否循环切换 | boolean | true |
| zoom-rate | 预览缩放步进倍率 | number | 1.2 |
| show-progress | 是否显示预览控制区 | boolean | true |
| preview-teleported | 预览容器是否传送到 body | boolean | true |
| scroll-container | 懒加载监听的滚动容器 | string | HTMLElement | undefined | undefined |
| viewer-mode | 预览模式，viewerjs 需要宿主自行提供对应依赖 | 'default' | 'viewerjs' | 'default' |
| viewer-options | 传递给 Viewer.js 的配置项 | Record<string, unknown> | {} |
| alt | 原生 img 的 alt 属性 | string | undefined |
| crossorigin | 原生 img 的 crossorigin 属性 | '' | 'anonymous' | 'use-credentials' | undefined |
| loading | 原生 img 的 loading 属性 | 'eager' | 'lazy' | undefined |
| theme-overrides | 组件级主题覆盖 | ComponentThemeVars | undefined |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| load | 图片加载成功触发 | (event: Event) => void |
| error | 图片加载失败时触发 | (event: Event | string) => void |
| switch | 预览图片轮播切换时触发 | (index: number) => void |
| show | 预览显示时触发 | () => void |
| close | 预览关闭时触发 | () => void |
Slots
| 插槽名 | 说明 |
|---|---|
| placeholder | 图片未完成加载时的占位内容 |
| error | 图片加载失败时的内容 |
Expose
当前组件未暴露公开实例方法或属性。
ImageViewer API
需要独立使用预览器时，可直接使用 yh-image-viewer。
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| url-list | 预览图片列表 | string[] | [] |
| z-index | 预览层级 | number | 2000 |
| initial-index | 打开预览时的起始索引 | number | 0 |
| infinite | 是否循环切换 | boolean | true |
| hide-on-click-modal | 点击遮罩层是否关闭预览 | boolean | false |
| close-on-press-escape | 按下 Esc 是否关闭预览 | boolean | true |
| zoom-rate | 缩放步进倍率 | number | 1.2 |
| show-progress | 是否显示预览控制区 | boolean | true |
| teleported | 预览容器是否传送到 body | boolean | true |
| viewer-mode | 预览模式 | 'default' | 'viewerjs' | 'default' |
| viewer-options | 传递给 Viewer.js 的配置项 | Record<string, unknown> | {} |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| switch | 图片切换时触发 | (index: number) => void |
| close | 预览关闭时触发 | () => void |
Slots
当前组件未暴露组件插槽。
Expose
| 名称 | 说明 | 类型 |
|---|---|---|
| prev | 切换到上一张图片 | () => void |
| next | 切换到下一张图片 | () => void |
| zoomIn | 放大图片 | () => void |
| zoomOut | 缩小图片 | () => void |
| rotateLeft | 逆时针旋转 | () => void |
| rotateRight | 顺时针旋转 | () => void |
| reset | 重置缩放与旋转状态 | () => void |
主题变量
YhImage 支持 themeOverrides，同时提供以下组件级 CSS 变量：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-image-placeholder-bg-color | 占位区域背景颜色 | var(--yh-fill-color-light) |
--yh-image-placeholder-text-color | 占位区域文字颜色 | var(--yh-text-color-placeholder) |
--yh-image-error-bg-color | 错误状态背景色 | var(--yh-fill-color-extra-light) |
--yh-image-error-text-color | 错误区域文字颜色 | var(--yh-text-color-placeholder) |
--yh-image-viewer-mask-bg-color | 预览遮罩背景颜色 | var(--yh-mask-color) |
--yh-image-viewer-btn-bg-color | 预览控制器按钮背景颜色 | var(--yh-text-color-regular) |
--yh-image-viewer-btn-color | 预览控制器按钮图标颜色 | var(--yh-color-white) |
--yh-image-viewer-btn-hover-bg-color | 预览控制器按钮悬停颜色 | var(--yh-color-primary) |
类型导出
| 名称 | 说明 |
|---|---|
YhImageProps | YhImage 的 props 类型 |
YhImageEmits | YhImage 的 emits 类型 |
YhImageSlots | YhImage 的 slots 类型 |
YhImageInstance | YhImage 的实例类型 |
YhImageViewerProps | YhImageViewer 的 props 类型 |
YhImageViewerEmits | YhImageViewer 的 emits 类型 |
YhImageViewerSlots | YhImageViewer 的 slots 类型 |
YhImageViewerExpose | YhImageViewer 的 expose 类型 |
YhImageViewerInstance | YhImageViewer 的实例类型 |