# 文字水印

> 为图片叠加文字水印：参数说明与使用示例。

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

> **Warning**
>
> 文字水印只作用于静态图片。动图（GIF、动态 WebP、APNG 等）会原样输出，不加水印。

## 参数说明

### 内容与字体

| 参数                | 说明                                                |     默认值    | 取值                                       |
| :---------------- | ------------------------------------------------- | :--------: | ---------------------------------------- |
| `txt`             | **水印内容**。为空则不加水印；建议 UrlEncode。`%0A` 表示换行，支持 emoji |      空     | 最长 256 字符                                |
| `txt-font`        | **字体**。多个字体用半角逗号分隔，按顺序匹配；名称不区分大小写，空格与连字符可省略       | NotoSansSC | Inter、NotoSansSC、NotoSansTC、SmileySans 等 |
| `txt-lang`        | **汉字地区字形**。不传时自动判断：含假名按日文，含谚文按韩文，其余按简体中文          |     自动     | `zh` / `zh-TW` / `zh-HK` / `ja` / `ko`   |
| `txt-size`        | **字号**。小于 1：按图片短边的比例自动计算；大于等于 1：按像素设定             |     自动     | 0 \~ 500                                 |
| `txt-weight`      | **字重**，同 CSS `font-weight`                        |     400    | 100 \~ 950                               |
| `txt-line-height` | **行高**，按倍数设定，同 CSS `line-height`（不支持 px）          |     1.1    | 0 \~ 100                                 |
| `txt-track`       | **字距**，单位像素                                       |      0     | -50 \~ 200                               |
| `txt-width`       | **最大行宽**，超出自动换行。中日韩文字逐字可断，拉丁文按词断                  |     不换行    | 像素，或百分比（按图片宽度）                           |
| `txt-align`       | **多行对齐方式**                                        |   `left`   | `left` / `center` / `right`              |

### 颜色与效果

| 参数               | 说明                                                  |    默认值   | 取值                                                                                                                                    |
| :--------------- | --------------------------------------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------- |
| `txt-color`      | **文字颜色**。多个颜色用半角逗号分隔即为渐变，方向由 `txt-color-deg` 决定     |   `FFF`  | 3 / 4 / 6 / 8 位十六进制（4 / 8 位的末段为不透明度），或 CSS 颜色名                                                                                        |
| `txt-color-deg`  | **渐变角度**，90 表示从左到右                                  |    90    | 0 \~ 360                                                                                                                              |
| `txt-alpha`      | **不透明度**，0 为全透明，1 为不透明。不传时沿用 `mark-alpha`           |     1    | 0 \~ 1                                                                                                                                |
| `txt-shad`       | **阴影虚化半径**，单位像素；不传则无阴影。`txt-color` 为渐变时阴影自动关闭       |    无阴影   | 0 \~ 50                                                                                                                               |
| `txt-shad-pos`   | **阴影偏移**，单位像素                                       |     –    | 0 \~ 100                                                                                                                              |
| `txt-shad-color` | **阴影颜色**，只支持单色                                      |   `666`  | 同 `txt-color`                                                                                                                         |
| `txt-line`       | **描边宽度**，单位像素                                       |     0    | 0 \~ 50                                                                                                                               |
| `txt-line-color` | **描边颜色**                                            |   `000`  | 十六进制（4 / 8 位的首段为不透明度）                                                                                                                 |
| `txt-bg`         | **底框颜色**。底框范围为文字区域加 `txt-pad`                       |    无底框   | 十六进制（4 / 8 位的首段为不透明度，如 `8000` 为 50% 黑）                                                                                                |
| `txt-radius`     | **底框圆角**，需配合 `txt-bg`；`50%` 为胶囊形                    |     0    | 像素 0 \~ 9999，或百分比（按底框短边）                                                                                                              |
| `txt-pad`        | **文字四周留白**，单位像素；有底框时即底框内边距                          |     0    | 0 \~ 9999                                                                                                                             |
| `txt-blend`      | **混合模式**                                            | `normal` | `normal` / `multiply` / `screen` / `overlay` / `darken` / `lighten` / `soft-light` / `hard-light` / `difference` / `add` / `subtract` |
| `mark-hdr-rate`  | **HDR 亮度增益**（与图片水印共用），仅对带增益图的 HDR 输出生效。0 为不提亮，1 为最亮 |    0.5   | 0 \~ 1，或 0% \~ 100%                                                                                                                   |

### 位置与尺寸

| 参数                                    | 说明                                                           |     默认值     | 取值          |
| :------------------------------------ | ------------------------------------------------------------ | :---------: | ----------- |
| `txt-pos`                             | **水印位置**，格式 `x,y`，详见下方「位置写法」                                 | `0.95,0.93` | –           |
| `txt-pct`                             | **最大占比**。水印超过「图片宽高 × 该值」时等比缩小；大于 1 表示允许超出图片。可写 `x,y` 分别约束宽、高 |      1      | 大于 0，至多 5   |
| `txt-rot`                             | **旋转角度**，顺时针，连同底框、描边、阴影整体旋转                                  |      0      | -360 \~ 360 |
| `txt-tile`                            | **平铺**，设为 `1` 时铺满整张图，隔行错位                                    |      关闭     | `1`         |
| `txt-tile-gap`                        | **平铺间距**，格式 `横,纵`；百分比按水印自身宽高计算                               |    `50%`    | 像素或百分比      |
| `txt-tile-rot`                        | **平铺倾斜角度**                                                   |      0      | -90 \~ 90   |
| `txt-if-min-width``txt-if-min-height` | **尺寸门槛**。图片宽或高小于该值时不加水印，避免缩略图被水印遮挡                           |      不限     | 像素          |

### 位置写法

`txt-pos` 的 `x`、`y` 各自独立，可以混用不同写法；只写一个值时两个方向取相同值。位置按**处理后的图片**（缩放、裁剪之后）计算。

**比例值（小于 1）** 有三种定位基准：

| 写法      | 定位基准                                          | 效果                |
| :------ | --------------------------------------------- | ----------------- |
| `0.5`   | 在「水印完整留在图内」的范围里按比例取位：0 贴左 / 上边，越接近 1 越靠右 / 下边 | 水印始终完整显示          |
| `*0.5`  | 水印**中心**落在图片的该比例处                             | 靠近边缘时最多有一半超出图片    |
| `**0.5` | 水印**左 / 上边缘**落在图片的该比例处                        | 靠近右 / 下边缘时可完全移出图片 |

**绝对值（大于等于 1）**：水印左上角相对图片左上角的像素偏移。

> **Tip**
>
> 建议为 `txt-size` 和 `txt-pos` 设定小于 1 的**比例值**。原图的尺寸与比例各不相同（尤其是配合 `w`、`h` 缩放裁剪之后），比例值能让水印的大小和位置在不同图片上保持一致。

## 参数示例

<details>
<summary>演示 1：添加文字水印 Bitiful，其余参数取默认值</summary>

URL：[https://demo.bitiful.com/bridge.jpeg? **`txt=Bitiful`**](https://demo.bitiful.com/bridge.jpeg?txt=Bitiful\&fmt=png)

![文字水印：默认样式](https://demo.bitiful.com/bridge.jpeg?txt=Bitiful\&fmt=png)

</details>

<details>
<summary>演示 2：水印置于底部居中并探出边界，字号约为短边的 55%，不透明度 3%</summary>

URL：[https://demo.bitiful.com/bridge.jpeg?txt=Bitiful& **`txt-size=0.55 & txt-pos=0.5,*0.96 & txt-alpha=0.03`**](https://demo.bitiful.com/bridge.jpeg?txt=Bitiful\&txt-size=0.55\&txt-pos=0.5,*0.96\&txt-alpha=0.03\&fmt=png)

![文字水印：底部居中并探出边界](https://demo.bitiful.com/bridge.jpeg?txt=Bitiful\&txt-size=0.55\&txt-pos=0.5,*0.96\&txt-alpha=0.03\&fmt=png)

</details>

<details>
<summary>演示 3：水印缩小并移至图片正中，使用三色从左到右渐变</summary>

为便于观察水印，示例同时用 `blur=50` 模糊了原图。

URL：[https://demo.bitiful.com/bridge.jpeg?txt=Bitiful\&blur=50& **`txt-size=0.3 & txt-pos=0.5,0.5 & txt-color=03FF76,FFE05B,03FFFE`**](https://demo.bitiful.com/bridge.jpeg?blur=50\&txt=Bitiful\&txt-size=0.3\&txt-pos=0.5,0.5\&txt-color=03FF76,FFE05B,03FFFE\&fmt=png)

![文字水印：三色渐变](https://demo.bitiful.com/bridge.jpeg?blur=50\&txt=Bitiful\&txt-size=0.3\&txt-pos=0.5,0.5\&txt-color=03FF76,FFE05B,03FFFE\&fmt=png)

</details>
