Image 图片
放图的框:固定比例、裁切方式、圆角一次给齐。加载中先扫一道骨架微光,加载完淡入,失败了回退成一块中性色。没有图片地址时,也可以直接把 svg 插画放进去当图。
基本用法
alt 必填。ratio 固定宽高比,图片按 cover 裁切铺满;宽度跟着容器走。
裁切方式
fit="cover"(默认)裁掉多出来的部分把框铺满;fit="contain" 把整张图放进框里,空出来的地方露出凹槽底色。竖图放进横框时差别最明显。
圆角
radius 取圆角档位 0–6(对应 --ok-r-1..6,配超椭圆曲线)或 full(正圆)。默认 3,也就是 16px。
不用图片地址
不传 src 时,children 就是“图”:内联 svg、插画、canvas 都行,照样按 ratio、radius 裁好,alt 用来给它起名字。下面这张插画的颜色取自 --ok-accent,换强调色或深浅色时跟着变。
加载与回退
加载中显示骨架微光(placeholder="none" 时只有底色),加载完用 --ok-dur-3 淡入。加载失败、或者 src 和 children 都没有时,显示 fallback:默认是凹槽色块加一个图片图标,可以换成任何内容。
叠在图上的内容
有 src 时,children 叠在图片上面,适合放角标、标签。图片本身没有悬停效果,可点击时交给外层的卡片或链接处理。
规格
- 底色
- --ok-well;不描边、不加阴影
- 圆角
- 默认 --ok-r-3(16),配 corner-shape
- 加载中
- 骨架微光,与 Skeleton 相同;减弱动效时不扫光
- 加载完
- 透明度 0 → 1 · --ok-dur-3
- 回退
- 凹槽色块 + 图片图标(--ok-text-3)
接口
Image
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
alt* | string | — | 图片说明。纯装饰的图传 alt="",整块对读屏隐藏。 |
src | string | — | 图片地址。不传时显示 children;children 也没有时显示 fallback。 |
ratio | number | string | — | 固定宽高比:16 / 9 或 '4 / 3'。不传时按图片本身的比例。 |
fit | 'cover' | 'contain' | 'cover' | 裁切铺满,或完整显示。 |
radius | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 'full' | 3 | 圆角档位。 |
fallback | ReactNode | 色块 + 图标 | 加载失败或没有内容时显示。 |
placeholder | 'skeleton' | 'none' | 'skeleton' | 加载中的占位。 |
loading | 'lazy' | 'eager' | 'lazy' | 原生懒加载。首屏的大图可改成 eager。 |
children | ReactNode | — | 没有 src 时当作图;有 src 时叠在图上。 |
…img 属性 | ImgHTMLAttributes | — | srcSet、sizes、onLoad 等透传到 img;className、style、ref 给外框。 |
无障碍
- 有图片时 alt 落在原生
img上;回退或用 children 当图时,外框变成role="img",名字取自 alt。 alt=""表示纯装饰:图片不读,回退和插画对读屏隐藏。- 骨架微光在系统开了“减弱动态效果”时停止。
- 外框上有 data-status(loading / loaded / error / empty / content),需要时可以据此写样式。