# 图片 Image

- 页面: https://jiguang132.com/zh/resources/ant-design-mobile/docs/image
- 资源: Ant Design Mobile (https://jiguang132.com/zh/resources/ant-design-mobile.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design-mobile/docs.md

可预览的图片。

## 安装

```bash
npm install antd-mobile@5.43.0
```

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 `unstableSetRender` 注册 `createRoot`，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 `<html data-prefers-color-scheme="dark">` 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 `DemoBlock` 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

可预览的图片。

## 何时使用

- 需要展示图片时使用。
- 加载大图时显示 loading 或加载失败时容错处理。

## 示例

## Image

### 属性

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| alt | 图片描述 | `string` | - |
| draggable | 是否允许用户拖拽图片 | `boolean` | `false` |
| fallback | 加载失败的占位 | `ReactNode` | 默认占位 |
| fit | 图片填充模式 | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'` | `'fill'` |
| height | 图片高度，如果传入数字则单位为 `px` | `string \| number` | - |
| lazy | 是否懒加载图片 | `boolean` | `false` |
| onClick | 图片点击事件 | `(event: React.MouseEvent<HTMLImageElement, Event>) => void` | - |
| onContainerClick | 容器点击事件 | `(event: React.MouseEvent<HTMLDivElement, Event>) => void` | - |
| onError | 加载失败时触发 | `(event: React.SyntheticEvent<HTMLImageElement, Event>) => void` | - |
| onLoad | 图片加载完时触发 | `(event: React.SyntheticEvent<HTMLImageElement, Event>) => void` | - |
| placeholder | 加载时的占位 | `ReactNode` | 默认占位 |
| src | 图片地址 | `string` | - |
| width | 图片宽度，如果传入数字则单位为 `px` | `string \| number` | - |

此外，还支持以下 HTML 原生属性：`crossOrigin`、`decoding`、`loading`、`referrerPolicy`、`sizes`、`srcSet`、`useMap`

`width` `height` 属性其实和 CSS 变量 `--width` `--height` 并不冲突，这些组件属性其实就是基于 CSS 变量实现的，只是 CSS 变量的一种快捷设置方式。

### CSS 变量

| 属性     | 说明     | 默认值 | 全局变量             |
| -------- | -------- | ------ | -------------------- |
| --height | 图片高度 | `auto` | `--adm-image-height` |
| --width  | 图片宽度 | `auto` | `--adm-image-width`  |

## FAQ

### 如何让 Image 从 block 元素变为 inline-block 元素？

Image 默认是渲染为 block 元素的，如果你需要让它变为 inline-block 元素的话，可以在外层嵌套一层 inline-block 的容器，例如：

```jsx
<div style={{ display: 'inline-block' }}>
  <Image />
</div>
```

### `onContainerClick` 和 `onClick` 有什么区别？

`onContainerClick` 是容器点击事件，而 `onClick` 是图片点击事件。在图片加载成功之前或图片加载失败后，`onClick` 是不会触发的，但 `onContainerClick` 是可以正常触发的。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt