# 图片缩放

> 调整图片尺寸：等比缩放、裁切、补边与智能裁切。

以下示例的原图均为：<https://demo.bitiful.com/girl.jpeg>

## 参数说明

| 参数     | 含义                         |    默认值   | 取值                                           |
| :----- | -------------------------- | :------: | -------------------------------------------- |
| `w`    | **目标宽度**                   |     –    | 像素（至多 10000），或百分比如 `50%`                     |
| `h`    | **目标高度**                   |     –    | 同上                                           |
| `dpr`  | **额外缩放倍率**，目标宽高再乘以该值       |     1    | 大于 0，至多 10                                   |
| `mode` | **缩放模式**，见下表               |  `crop`  | `crop` / `clip` / `fill` / `scale` / `adapt` |
| `pos`  | **裁切时保留的位置**，见下文           | `center` | 预设方位、自定义坐标或智能裁切                              |
| `fill` | **补边方式**，仅 `mode=fill` 时生效 |  `solid` | `solid` / `blur` / `dominant` / `auto`       |
| `bg`   | **背景色**，用于补边               |    白色    | 十六进制颜色                                       |

URL 中 `%` 需写作 `%25`，如 `w=50%25`。

### 缩放模式

| mode    | 行为                              | 输出尺寸      |
| :------ | ------------------------------- | --------- |
| `crop`  | 等比缩放后**裁掉多余部分**                 | 恰为 w × h  |
| `clip`  | 等比缩放到 w × h 的框内，**不裁切**         | 不超过 w × h |
| `fill`  | 等比缩放到框内，再**补边**至目标尺寸            | 恰为 w × h  |
| `scale` | **拉伸**到目标尺寸，不保持宽高比              | 恰为 w × h  |
| `adapt` | 自动选择：裁切损失不大时按 `crop`，否则按 `fill` | 恰为 w × h  |

- 只指定 `w` 或 `h` 其中之一时，始终等比缩放。
- 同时指定 `w` 和 `h` 且未指定 `mode` 时，按 `crop` 处理。

### 补边方式

`mode=fill` 时，`fill` 决定留白区域的填充内容：

| fill       | 效果                               |
| :--------- | -------------------------------- |
| `solid`    | 用 `bg` 指定的纯色                     |
| `blur`     | 用原图放大模糊后的画面作背景                   |
| `dominant` | 用原图的主色                           |
| `auto`     | 内容感知：边缘是纯色或平滑渐变时沿边缘自然延伸，否则使用模糊背景 |

### 裁切位置

`mode=crop` 时，`pos` 决定保留画面的哪一部分。

| 写法        | 取值                                                                                         |
| :-------- | ------------------------------------------------------------------------------------------ |
| **九宫格**   | `top-left`、`top`、`top-right`、`left`、`center`、`right`、`bottom-left`、`bottom`、`bottom-right` |
| **居中偏移**  | `top-center`、`bottom-center`、`left-center`、`right-center`：在居中的基础上向该方向偏移                    |
| **自定义坐标** | `x,y`，取值 0 \~ 1 或 0% \~ 100%，如 `0.25,0.75`                                                 |
| **智能裁切**  | `smart`（`face`、`auto` 等价）                                                                  |

### 智能裁切

`pos=smart` 会识别画面中的**人脸、人体、猫狗和显著主体**，自动选择最能完整保留它们的裁切窗口；有人脸时会让人脸落在画面偏上的自然位置。

- 仅当原图与目标的宽高比相差超过 25% 时才进行识别，否则居中裁切。
- 动图不做识别，居中裁切。

> **Tip**
>
> 头像、商品图、信息流封面等需要把不同比例的图片裁成统一比例的场景，推荐使用 `pos=smart`。

## 使用示例

<details>
<summary>演示：只指定宽度 w=200，等比缩放</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200`**](https://demo.bitiful.com/girl.jpeg?w=200)

![等比缩放到 200 宽](https://demo.bitiful.com/girl.jpeg?w=200)

</details>

<details>
<summary>演示：只指定高度 h=200，等比缩放</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`h=200`**](https://demo.bitiful.com/girl.jpeg?h=200)

![等比缩放到 200 高](https://demo.bitiful.com/girl.jpeg?h=200)

</details>

<details>
<summary>演示：同时指定 w=200 & h=200（默认 mode=crop，pos=center）</summary>

![裁切逻辑示意](https://demo.bitiful.com/static/docs/crop-mode-demo-1.png?w=200\&fmt=webp\&q=90)

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200)

![居中裁切](https://demo.bitiful.com/girl.jpeg?w=200\&h=200)

</details>

<details>
<summary>演示：w=200 & h=200，mode=clip 等比缩入框内</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & mode=clip`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&mode=clip)

![等比缩入框内](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&mode=clip)

</details>

<details>
<summary>演示：w=200 & h=200，dpr=0.5 输出 100 × 100</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & dpr=0.5`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&dpr=0.5)

![缩放倍率 0.5](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&dpr=0.5)

</details>

<details>
<summary>演示：w=200 & h=200，pos=top 保留上部</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=top`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=top)

![保留上部](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=top)

</details>

<details>
<summary>演示：w=200 & h=200，pos=bottom 保留下部</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=bottom`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=bottom)

![保留下部](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=bottom)

</details>

<details>
<summary>演示：w=200 & h=200，pos=smart 智能裁切</summary>

URL：[https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=smart`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=smart)

![智能裁切](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=smart)

</details>

<details>
<summary>演示：w=300 & h=200，mode=fill 并用模糊背景补边</summary>

URL：

<https://demo.bitiful.com/girl.jpeg?w=300&h=200&mode=fill&fill=blur>

</details>
