Image 图片

渲染图片，并在图片源加载失败时展示内置的兜底占位图。

适用场景：需要一张在图片源加载失败时能优雅降级为占位图的图片——<r-img> 会自动切换到内置的裂图图形，或者切换到你自己传入的 fallback。

快速开始

基础用法

<r-img src="https://picsum.photos/id/1015/240/160"></r-img>

API 参考

属性

属性	类型	默认值	说明
src	string	''	图片地址。响应式——挂载后修改会重新加载图片。
alt	string	''	转发给内部 <img> 的替代文本。留空表示这是一张装饰性图片。
fallback	string	内置的裂图 data URI	src 加载失败时展示的图片。
sheet	string	''	注入到组件 Shadow DOM 中的 CSS。

src、alt、fallback、sheet 均为受监听属性，会响应式更新——在已挂载的元素上修改任意一个都会立即生效。

图片地址 src

<r-img src="https://picsum.photos/id/1025/240/160"></r-img>

替代文本 alt

alt 会转发给内部的 <img>。对于装饰性图片，留空（默认值）即可让屏幕阅读器跳过它；对于有实际含义的图片，请提供描述文本。

<r-img src="https://picsum.photos/id/1035/240/160" alt="黄昏时分的山间湖泊"></r-img>

图片加载失败 fallback

当 src 加载失败时，组件会切换到 fallback。如果未设置 fallback，则会使用内置的裂图占位图。下面示例中的 src 是一个无效地址，因此展示的是兜底图片。

<r-img
  src="https://example.invalid/does-not-exist.png"
  fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...(裂图占位图)..."
></r-img>

外部样式 sheet

sheet 会把原始 CSS 注入组件的 Shadow DOM。可以用它来定制内部的 .ran-image 容器或内部的 <img>。

<r-img
  src="https://picsum.photos/id/1043/240/160"
  sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"
></r-img>

事件

无。r-img 不会派发任何自定义事件。

最佳实践

• 随时修改 src：src 是响应式的，在已挂载的元素上更新它会重新加载图片；如果新地址加载失败，兜底图片依然会生效。
• 为有实际含义的图片提供 alt：为屏幕阅读器描述图片内容；只有纯装饰性图片才应该把 alt 留空。
• 善用内置兜底图：默认会自动使用内置的裂图占位图，但如果想要品牌化或更贴合场景的占位图，可以传入自己的 fallback。
• 用 sheet 定制样式：由于图片位于 Shadow DOM 内，需要用 sheet 属性（或组件的 CSS 变量）来设置边框、圆角或尺寸。