Image 图片
在原生 <img> 的基础上加了加载中占位、加载失败提示、懒加载和大图预览。预览也可以单独用 NsImageViewer 打开。
引入
import { NsImage, NsImageViewer } from '@ns/ui'
基础用法
src 传图片地址,width、height 设置尺寸:数字按像素,字符串原样使用(例如 '50%')。只设宽度时高度按图片比例。
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start">
<NsImage src="/images/cat.jpg" alt="一只猫" :width="200" :height="150" />
<NsImage src="/images/cat.jpg" alt="只设宽度" width="120px" />
</NsSpace>
</template>
填充方式
fit 决定图片在容器里怎么摆,取值和 CSS 的 object-fit 一样,默认 'fill'。下面把一张 4:3 的图片放进 100×100 的方框(灰底是容器):
fill:拉伸铺满,图片变形。contain:完整显示、保持比例,上下留空。cover:铺满、保持比例,左右裁掉。none:按原始尺寸显示,只能看到中间一块。scale-down:取none和contain里较小的一个,这张图比方框大,所以和contain一样。
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
import type { ImageProps } from '@ns/ui'
const fits: NonNullable<ImageProps['fit']>[] = ['fill', 'contain', 'cover', 'none', 'scale-down']
</script>
<template>
<NsSpace wrap size="large">
<NsSpace v-for="fit in fits" :key="fit" direction="vertical" align="center">
<NsImage src="/images/cat.jpg" :fit="fit" :width="100" :height="100" class="box" />
<span class="caption">{{ fit }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.box {
background-color: var(--ns-fill-color);
}
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
圆形
round 把图片裁成圆形(border-radius: 50%),宽高相等时是正圆,不相等时是椭圆。
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="center">
<NsImage src="/images/avatar.jpg" round :width="80" :height="80" />
<NsImage src="/images/avatar.jpg" round :width="48" :height="48" />
<NsImage src="/images/cat.jpg" round fit="cover" :width="120" :height="80" />
</NsSpace>
</template>
加载中和加载失败
加载中默认显示一个转圈,加载失败默认显示“加载失败”。placeholder、error 可以分别换成一张图片(传的是图片地址,不是插槽)。
<script setup lang="ts">
import { NsImage } from '@ns/ui'
</script>
<template>
<NsImage
src="/images/big.jpg"
placeholder="/images/loading.png"
error="/images/broken.png"
:width="200"
:height="150"
/>
</template>
下面第一张地址是错的,显示默认的“加载失败”;第二张地址也是错的,失败后显示 error 指定的图片:
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsImage src="/broken.png" :width="160" :height="120" />
<NsImage src="/broken.png" error="/images/empty.png" fit="contain" :width="160" :height="120" />
</NsSpace>
</template>
换了 src 之后会重新显示加载中,直到新图片加载完成或失败。加载成功触发 load,失败触发 error。点按钮切换地址看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsImage, NsSpace } from '@ns/ui'
const list = ['/images/1.jpg', '/images/2.jpg', '/broken.png']
const index = ref(0)
const status = ref('加载中')
const next = () => {
index.value = (index.value + 1) % list.length
status.value = '加载中'
}
</script>
<template>
<NsSpace wrap align="center">
<NsImage
:src="list[index]"
fit="cover"
:width="200"
:height="120"
@load="status = '触发了 load'"
@error="status = '触发了 error'"
/>
<NsButton @click="next">换一张</NsButton>
</NsSpace>
<p style="margin-top: 12px">当前地址:{{ list[index] }},{{ status }}</p>
</template>
懒加载
lazy 开启后,图片进入视口(提前 50px)才开始加载,之前一直显示加载中的占位。不支持 IntersectionObserver 的环境里直接加载。在下面的框里往下滚动,图片依次加载:
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
// 地址后面加上序号,每张都单独请求,方便看出是滚动到了才加载
const images = Array.from({ length: 12 }, (_, i) => `/images/${(i % 3) + 1}.jpg?n=${i + 1}`)
</script>
<template>
<div style="height: 320px; overflow-y: auto">
<NsSpace wrap>
<NsImage
v-for="src in images"
:key="src"
:src="src"
fit="cover"
:width="300"
:height="120"
lazy
/>
</NsSpace>
</div>
</template>
图片预览
传了 preview-src-list 后,点击图片(或用 Tab 聚焦后按回车、空格)打开预览。预览默认从 src 在列表里的位置开始,initial-index 可以指定从第几张开始。
预览里可以:
- 点左右箭头或按 ←、→ 切换图片(到头后从另一头接着走)。
- 点工具栏缩小、放大、向左旋转、向右旋转、还原,或按 ↑、↓ 放大、缩小。
- 放大后按住图片拖动。
- 点右上角的关闭按钮、点图片外的区域或按 Esc 关闭。
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
const list = ['/images/1.jpg', '/images/2.jpg', '/images/3.jpg']
</script>
<template>
<NsSpace wrap>
<NsImage
v-for="(src, index) in list"
:key="src"
:src="src"
:width="100"
:height="75"
:preview-src-list="list"
:initial-index="index"
/>
</NsSpace>
</template>
不传 initial-index 时从 src 在列表里的位置开始;src 不在列表里时从第一张开始。下面第一张图打开后先看到 3.jpg,第二张的 src 不在列表里,打开后先看到 1.jpg:
<script setup lang="ts">
import { NsImage, NsSpace } from '@ns/ui'
const list = ['/images/1.jpg', '/images/2.jpg', '/images/3.jpg']
</script>
<template>
<NsSpace wrap>
<NsImage src="/images/3.jpg" fit="cover" :width="120" :height="80" :preview-src-list="list" />
<NsImage src="/images/cat.jpg" fit="cover" :width="120" :height="80" :preview-src-list="list" />
</NsSpace>
</template>
单独使用预览
NsImageViewer 挂载即打开,关闭(离场动画结束)后发出 close,由使用者用 v-if 卸载它。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsImageViewer } from '@ns/ui'
const show = ref(false)
const list = ['/images/1.jpg', '/images/2.jpg']
</script>
<template>
<NsButton @click="show = true">查看大图</NsButton>
<NsImageViewer v-if="show" :url-list="list" hide-on-click-modal @close="show = false" />
</template>
infinite 默认开启,最后一张往后是第一张;关掉以后到头时箭头变灰、不能再切换。initial-index 指定打开时显示第几张,切换图片时触发 switch。hide-on-click-modal 默认关闭,这时点图片外的区域不会关闭预览:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsImageViewer } from '@ns/ui'
const list = ['/images/1.jpg', '/images/2.jpg', '/images/3.jpg']
const show = ref(false)
const current = ref<number>()
const open = () => {
current.value = undefined
show.value = true
}
</script>
<template>
<NsButton @click="open">从第 2 张打开,不循环</NsButton>
<p style="margin-top: 12px">
{{ current === undefined ? '还没有切换' : `switch 触发,切到了第 ${current + 1} 张` }}
</p>
<NsImageViewer
v-if="show"
:url-list="list"
:initial-index="1"
:infinite="false"
@switch="current = $event"
@close="show = false"
/>
</template>
NsImage Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| src | string | - | 图片地址,必填 |
| alt | string | '' | 替代文本 |
| fit | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | 'fill' | 图片在容器里的适应方式,同 CSS 的 object-fit |
| lazy | boolean | false | 是否懒加载,进入视口(提前 50px)后才加载 |
| previewSrcList | string[] | - | 预览图片列表。传了(并且不为空)才能点击预览 |
| initialIndex | number | - | 打开预览时显示第几张(从 0 开始,超出范围时取最近的一张);不传时从 src 所在位置开始 |
| zIndex | number | 2000 | 预览层的 z-index |
| width | string | number | - | 宽度,数字按像素,字符串原样使用 |
| height | string | number | - | 高度,数字按像素,字符串原样使用 |
| round | boolean | false | 是否显示成圆形(border-radius: 50%) |
| placeholder | string | - | 加载中显示的占位图地址;不传时显示转圈 |
| error | string | - | 加载失败时显示的图片地址;不传时显示“加载失败” |
NsImage Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| load | (event: Event) | 图片加载成功时触发 |
| error | (event: Event) | 图片加载失败时触发 |
NsImageViewer Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| urlList | string[] | [] | 预览的图片列表 |
| initialIndex | number | 0 | 打开时显示第几张 |
| zIndex | number | 2000 | 预览层的 z-index |
| infinite | boolean | true | 是否循环切换:第一张往前是最后一张,反之亦然 |
| hideOnClickModal | boolean | false | 点图片外的区域是否关闭预览(NsImage 里总是开启) |
NsImageViewer Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| close | - | 预览关闭、离场动画结束后触发,这时可以用 v-if 卸载它 |
| switch | (index: number) | 切换图片后触发,参数是新的下标 |
类型
import type { ImageProps, ImageViewerProps, ImageViewerEmits } from '@ns/ui'
interface ImageProps {
src: string
alt?: string
fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
lazy?: boolean
previewSrcList?: string[]
initialIndex?: number
zIndex?: number
width?: string | number
height?: string | number
round?: boolean
placeholder?: string
error?: string
}
interface ImageViewerProps {
urlList: string[]
initialIndex?: number
zIndex?: number
infinite?: boolean
hideOnClickModal?: boolean
}
interface ImageViewerEmits {
close: []
switch: [index: number]
}
注意事项
width、height作用在外层容器上,里面的<img>铺满容器;只设宽度时高度按图片比例。加载中和加载失败的占位也按容器大小显示,所以想让占位可见时要给出高度。placeholder、error是图片地址,不是插槽;组件没有插槽。- 预览层挂在
body下,和NsModal、NsDrawer共用一个弹层栈:在对话框里打开预览后按 Esc 只关闭预览;打开时锁定页面滚动、焦点移进预览,关闭后焦点还给原来的元素。 NsImageViewer的close在离场动画结束后才触发,触发前不要卸载它,否则看不到淡出效果。- 可预览的图片带
role="button"和tabindex="0",预览里的按钮都有aria-label(关闭、上一张、下一张、缩小、放大、向左旋转、向右旋转、还原)。
优化点
- [ ] 支持
placeholder、error插槽(和同名的图片地址属性并存) - [ ] 预览支持下载、全屏
- [ ] 预览支持鼠标滚轮缩放
- [ ] 预览支持触摸手势