---
name: "snapshot"
mode: "api"
versionRequirements:
  - { name: "基础库", version: "2.23.0" }
title: "snapshot - 页面元素截图"
---

## snapshot

> [VERSION] 基础库 >= 2.23.0

### 描述

对页面中的元素进行截图。

### 参数

| 属性 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `params` | `Object` | 是 | 截图参数 |

##### snapshot.params 的属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `selector` | `string` | 否 | - | 元素选择器，支持 id 选择器或 class 选择器 |
| `backgroundColor` | `string` | 否 | - | 截图背景色；未传时 png 默认 transparent、jpeg 默认 white |
| `format` | `"png" \| "jpeg"` | 否 | - | 图片格式，仅支持 `png` 或 `jpeg` |
| `quality` | `number` | 否 | - | 图片质量，取值范围 `0~1`，仅在 `jpeg` 格式下生效 |
| `foreignObjectRendering` | `boolean` | 否 | - | 是否启用 foreignObjectRendering |
| `success` | `(res: SnapshotSuccessResult) => void` | 否 | - | 截图成功回调，返回图片 Base64、临时路径及尺寸信息 |
| `fail` | `(error: SnapshotFailResult) => void` | 否 | - | 截图失败回调，返回错误信息 errMsg |
| `complete` | `(res: Partial) => void` | 否 | - | 调用完成回调（成功或失败都会触发） |


##### Partial 的属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `imageData` | `string` | 否 | - | 图片 Base64 数据，可用于数据上传 |
| `tempImagePath` | `string` | 否 | - | 临时文件路径，仅在真机下有效，可用于保存到相册 |
| `width` | `number` | 否 | - | 图片宽度 |
| `height` | `number` | 否 | - | 图片高度 |
| `errMsg` | `string` | 否 | - | 错误信息 |


### 返回值

无


### 引用对象

##### `interface` SnapshotSuccessResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `imageData` | `string` | 图片 Base64 数据，可用于数据上传 |
| `tempImagePath` | `string` | 临时文件路径，仅在真机下有效，可用于保存到相册 |
| `width` | `number` | 图片宽度 |
| `height` | `number` | 图片高度 |

##### `interface` SnapshotFailResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errMsg` | `string` | 错误信息 |


### 示例代码

#### 对页面元素截图

```js
Page({
  onCapture() {
    ty.snapshot({
      selector: '#capture-area',
      format: 'png',
      success(res) {
        console.log('截图成功', res.tempImagePath);
        console.log('宽高', res.width, res.height);
      },
      fail(err) {
        console.error('截图失败', err.errMsg);
      },
    });
  },
});
```

#### 指定格式和质量截图

```js
Page({
  onCapture() {
    ty.snapshot({
      selector: '.card',
      format: 'jpeg',
      quality: 0.8,
      backgroundColor: '#ffffff',
      success(res) {
        console.log('JPEG 截图', res.imageData.substring(0, 50));
      },
    });
  },
});
```


## 注意事项

> 可能由于页面样式的复杂度因素，截图结果可能会有所不同，如遇到此类问题，可尝试调整页面样式

## 已知问题

1. `ty.snapshot` 在应对一些复杂布局, 以及在 iOS 18 系统下可能无法正确截图的情况, 请使用 canvas 进行绘制进行 base64 转换后再进行图片的保存.