> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义设计

> 通过 API 设置二维码样式：点和定位角的形状、颜色、边框和 Logo。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

创建或更新二维码时，可以使用可选的 `styles`、`frameOptions` 和 `logoOptions` 对象设置样式。所有字段都是可选的，未提供的字段会使用默认值。

这三个对象同样适用于[二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)、[模板](https://docs.getqr.com/zh/api/endpoints/templates.md)和[批量创建](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)。未知的形状、边框或 Logo 会被拒绝，并返回 `422`。

## 设计对象示例

```json theme={null}
{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}
```

将它与二维码的其他字段一起发送：

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'
```

## 样式

`styles` 对象用于设置图案的形状和颜色。

| 字段 | 取值 |
| - | - |
| `dotsOptions.type` | 主体点的形状：`square`、`dots`、`rounded`、`classy`、`classy-rounded`、`extra-rounded` |
| `cornersSquareOptions.type` | 角方块（眼框）的形状：`square`、`rounded`、`dot`、`classy-rounded` |
| `cornersDotOptions.type` | 角点（眼球）的形状：`square`、`dot`、`dots`、`rounded`、`classy` |
| `dotsOptions.color` | 前景色。默认为 `#000000`。 |
| `backgroundOptions.color` | 背景色。默认为 `#ffffff`。 |
| `cornersSquareOptions.color`, `cornersDotOptions.color` | 可以发送，但不会生效：定位角始终使用 `dotsOptions.color`。 |

* **颜色。** 只接受十六进制值：`#RGB` 或 `#RRGGBB`。
* **纠错级别。** 始终为 `Q`，且不能作为输入。发送 `styles.qrOptions` 会返回 `422`。
* **Branded design 和 AI design。** 无法通过 API 设置。发送 `styles.logoQrArt` 会返回 `422`。
* **内容。** `styles.data` 会被忽略。图片始终编码二维码自身的内容。

> [!TIP]
>
> 前景色和背景色之间要保持足够的对比度，最好是浅色背景配深色前景。对比度过低的二维码可能无法扫描。请参阅[颜色](https://docs.getqr.com/zh/design/colors.md)。

## 边框

`frameOptions` 对象会在二维码周围添加带有行动号召的装饰性边框。

| 字段 | 说明 |
| - | - |
| `id` | 发送 `frameOptions` 时必填。边框类型，取自下方列表。`none` 表示不使用边框。 |
| `text` | 行动号召文字，最多 12 个字符。默认为 `Scan me!`。 |
| `color` | 边框颜色，十六进制。 |
| `textColor` | 文字颜色，十六进制。边框显示文字时，必须与 `color` 不同，除非这组颜色是该边框的内置颜色预设之一。 |
| `borderColor` | 描边颜色，十六进制。 |
| `fingerPrintColor` | 边框图标的强调色，十六进制。 |

> [accordion] 通用边框
>
> `none`, `card`, `card-1`, `card-2`, `card-3`, `card-4`, `card-5`, `card-7`, `card-8`, `card-9`, `card-10`, `card-11`, `card-12`, `card-13`, `card-14`, `card-15`, `card-hor`, `wreath`, `envelope`, `waitress`, `coffee-cup`, `scooter`, `clipboard`
>
> `card-hor` 不显示文字。

> [accordion] 按二维码类型分组的边框
>
> | 类型 | 带文字的边框 | 不带文字的边框 |
> | - | - | - |
> | App Link | `app-3` | `app-1`, `app-2` |
> | vCard | `contact-1`, `contact-5` | `contact-2`, `contact-3`, `contact-4` |
> | Email | `email-1` | `email-2`, `email-3`, `email-4`, `email-5` |
> | Feedback | — | `feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5` |
> | Image | — | `image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6` |
> | Location | `location-3` | `location-1`, `location-2`, `location-4`, `location-5`, `location-6` |
> | Multi-Link | `multilink-3` | `multilink-1`, `multilink-2` |
> | Payment | — | `payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5` |
> | PDF | `pdf-1` | `pdf-2`, `pdf-3`, `pdf-4` |
> | SMS | `sms-3`, `sms-5`, `sms-7` | `sms-1`, `sms-2`, `sms-4`, `sms-6` |
> | Social Media | `social-3` | `social-1`, `social-2`, `social-4` |
> | Video | `video-1`, `video-3` | `video-2`, `video-4`, `video-5`, `video-6` |
> | Website | `website-1` | `website-2`, `website-3`, `website-4`, `website-5` |
> | WhatsApp | `whatsapp-2` | `whatsapp-1`, `whatsapp-3`, `whatsapp-4` |
> | WiFi | — | `wifi-1`, `wifi-2`, `wifi-3`, `wifi-4` |
>
> 任何边框都可以用于任何类型的二维码。此分组与控制台一致。

不带文字的边框在控制台中没有行动号召字段，并且 `textColor` 必须与 `color` 不同的规则对它们不适用。

## Logo

`logoOptions` 对象用于在二维码中心放置 Logo。通过设置 `type` 选择 Logo 的种类。

### 推荐 Logo

将 `type` 设为 `suggested`，并从目录中选择一个 `id`。使用 `logo-none` 表示不使用 Logo。

```json theme={null}
{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }
```

> [accordion] 所有推荐 Logo 的 ID
>
> `logo-none`, `logo-website-3`, `logo-website-4`, `logo-link`, `logo-pdf-1`, `logo-pdf-2`, `logo-pdf-3`, `logo-picture-1`, `logo-picture-2`, `logo-picture-3`, `logo-picture-5`, `logo-picture-7`, `logo-picture-8`, `logo-video-1`, `logo-video-5`, `logo-whatsapp-1`, `logo-whatsapp-2`, `logo-whatsapp`, `logo-wifi-1`, `logo-wifi-2`, `logo-wifi-3`, `logo-wifi`, `logo-airbnb`, `logo-apple`, `logo-binance`, `logo-bitcoin`, `logo-bolt-food`, `logo-booking`, `logo-facebook`, `logo-glovo`, `logo-google`, `logo-google-maps`, `logo-google-play`, `logo-instagram`, `logo-linkedin`, `logo-location`, `logo-mail`, `logo-paypal`, `logo-stripe`, `logo-venmo`, `logo-cashapp`, `logo-braintree`, `logo-square`, `logo-verifone`, `logo-google-pay`, `logo-apple-pay`, `logo-klarna`, `logo-ayden`, `logo-giropay`, `logo-cartes-bancaires`, `logo-restaurant`, `logo-scan-me`, `logo-tripadvisor`, `logo-trustpilot`, `logo-uber-eats`, `logo-youtube`, `logo-spotify`, `logo-spotify-black`

### 自定义 Logo

**1. 上传图片**

使用 `"target": "logo"` 通过[文件](https://docs.getqr.com/zh/api/endpoints/files.md)注册图片，然后将文件上传到返回的 `uploadUrl`。

**2. 引用文件**

将 `type` 设为 `uploaded`，并将 `fileId` 设为返回的 `fileId`。`fileId` 为必填项，且必须是文件端点返回的 ID。

```json theme={null}
{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }
```

未知的文件、未完成的上传或使用其他用途上传的文件都会被拒绝。

### Logo 大小

`scalePercent` 以二维码尺寸的百分比设置 Logo 大小。取值为 15 到 45 之间的整数，默认值为 25。其他值（包括 `0.25` 这样的比例值）会返回 `422`。

## 更新设计

* **部分更新。** 在[更新二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#更新二维码)时，`styles`、`frameOptions` 和 `logoOptions` 会合并到已保存的设计中。部分对象只会更改其中指定的内容。
* **更换 Logo。** 选择其他 Logo 会替换已保存的 Logo，但保留其 `scalePercent`。
* **模板。** 创建时提供 `templateId`，您发送的字段会合并到模板设计之上。请参阅[模板](https://docs.getqr.com/zh/api/endpoints/templates.md)。
* **Branded design 和 AI design。** `designKind` 为 `branded` 或 `ai` 的二维码是在控制台中创建的。API 无法编辑其图案，但在您更改其他字段时会保留它。
* **读取设计。** 响应会在 `design` 下返回已保存的设计，其结构与请求字段相同，因此可以直接回传。

## 常见问题

> [accordion] 422 "Error correction is always Q and is not an input"
>
> 从请求中移除 `styles.qrOptions`。

> [accordion] 422 "Frame caption is at most 12 characters"
>
> 将 `frameOptions.text` 缩短到 12 个字符以内。

> [accordion] 422 "Frame caption color must differ from the frame color"
>
> 在显示文字的边框上，`textColor` 与 `color` 相同。请选择一个对比明显的 `textColor`。

> [accordion] 422 "Logo scale is a whole number from 15 to 45"
>
> 请以整数百分比发送 `scalePercent`，例如 `25`，而不是 `0.25`。

> [accordion] 定位角颜色没有变化
>
> 定位角始终使用 `dotsOptions.color`。`cornersSquareOptions.color` 和 `cornersDotOptions.color` 不会生效。

## 后续步骤

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)

> [card] [模板](https://docs.getqr.com/zh/api/endpoints/templates.md)

> [card] [文件](https://docs.getqr.com/zh/api/endpoints/files.md)

> [card] [设计概览](https://docs.getqr.com/zh/design/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.