跳到主要内容

Image 图片

放图的框:固定比例、裁切方式、圆角一次给齐。加载中先扫一道骨架微光,加载完淡入,失败了回退成一块中性色。没有图片地址时,也可以直接把 svg 插画放进去当图。

基本用法

alt 必填。ratio 固定宽高比,图片按 cover 裁切铺满;宽度跟着容器走。

清晨粉色的山丘绿色草坡和太阳紫色黄昏

裁切方式

fit="cover"(默认)裁掉多出来的部分把框铺满;fit="contain" 把整张图放进框里,空出来的地方露出凹槽底色。竖图放进横框时差别最明显。

陶土花盆里的绿植cover
陶土花盆里的绿植contain

圆角

radius 取圆角档位 0–6(对应 --ok-r-1..6,配超椭圆曲线)或 full(正圆)。默认 3,也就是 16px。

0
1
2
3
4
5
6
full

不用图片地址

不传 src 时,children 就是“图”:内联 svg、插画、canvas 都行,照样按 ratio、radius 裁好,alt 用来给它起名字。下面这张插画的颜色取自 --ok-accent,换强调色或深浅色时跟着变。

加载与回退

加载中显示骨架微光(placeholder="none" 时只有底色),加载完用 --ok-dur-3 淡入。加载失败、或者 src 和 children 都没有时,显示 fallback:默认是凹槽色块加一个图片图标,可以换成任何内容。

蓝色湖边的山丘加载完淡入
封面图加载失败:默认回退
封面图自定义 fallback

叠在图上的内容

有 src 时,children 叠在图片上面,适合放角标、标签。图片本身没有悬停效果,可点击时交给外层的卡片或链接处理。

珊瑚色马克杯新品紫色台灯
库存 3

规格

底色
--ok-well;不描边、不加阴影
圆角
默认 --ok-r-3(16),配 corner-shape
加载中
骨架微光,与 Skeleton 相同;减弱动效时不扫光
加载完
透明度 0 → 1 · --ok-dur-3
回退
凹槽色块 + 图片图标(--ok-text-3)

接口

Image

属性类型默认值说明
alt*string—图片说明。纯装饰的图传 alt="",整块对读屏隐藏。
srcstring—图片地址。不传时显示 children;children 也没有时显示 fallback。
rationumber | string—固定宽高比:16 / 9 或 '4 / 3'。不传时按图片本身的比例。
fit'cover' | 'contain''cover'裁切铺满,或完整显示。
radius0 | 1 | 2 | 3 | 4 | 5 | 6 | 'full'3圆角档位。
fallbackReactNode色块 + 图标加载失败或没有内容时显示。
placeholder'skeleton' | 'none''skeleton'加载中的占位。
loading'lazy' | 'eager''lazy'原生懒加载。首屏的大图可改成 eager。
childrenReactNode—没有 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),需要时可以据此写样式。