---
type: reference
title: 自定义模式参考
summary: 每个可自定义的面背后那个共享的字段类型和预设模型、每个维度允许的字段类型、每个接受的值，以及模式和预设如何被定义和解析。
---

这是 Caputchin 的 **字段类型和预设模型** 的那一份参考，即每个可自定义的面之下那个共享的根基：

- [游戏自定义](/docs/game-customization/overview)：一个应用市场游戏的语言、皮肤和配置。
- [自定义游戏模式](/docs/custom-game-development/dashboard-schema)：你自己为一个自定义游戏撰写的那个模式。
- [应用市场游戏清单](/docs/marketplace-game-development/the-caputchin-json-manifest)：一个游戏作者声明的那些 `locales` / `skins` / `configurations` 块。
- [给组件做白标](/docs/widget-customization/white-label)：组件外壳的内置模式。

四者都用这里描述的同样的字段类型和同样的预设模型。自定义由 **预设** 构建，而一个预设是一袋带类型的 **字段**。

## 按维度的字段类型

每个维度允许一组固定的字段类型：

| 维度 | 允许的字段类型 |
|---|---|
| Configuration | `boolean`、`number`、`range`、`list`、`string`、`link` |
| Locale | 只 `string` |
| Skin | `color`、`image`、`audio`、`video`、`boolean`、`number`、`range`、`list` |

一个皮肤不只是颜色和资源：它也能暴露标量旋钮 `boolean`、`number`、`range` 和 `list`（一个“阴影”开关、一个圆角半径数字、一个“图案”选择）。这些的行为恰好像它们的配置对应物，并解析为它们的带类型值（一个 `boolean` 保持 `true`、一个 `number` 保持 `8`）；`color` 和资源值解析为字符串。皮肤不允许 `string` 或 `link`（自由文本属于语言；一个链接目标是一个配置）。

## 每种类型接受什么

| 类型 | 值 | 规则 |
|---|---|---|
| `string` | 自由文本 | 任何文本。 |
| `boolean` | 一个开关 | `true` 或 `false`。 |
| `number` | 一个数字 | 任何有限的数。 |
| `range` | 一个有界的数字 | 字段的最小值和最大值之内的一个有限数。step 是一个滑块便利；偏离 step 的值仍被接受。 |
| `list` | 一个选择 | 必须是字段所列选项之一。 |
| `link` | 一个 URL | 一个 `http` 或 `https` URL。内嵌的凭据被拒绝。 |
| `color` | 一个颜色 | 一个十六进制颜色（`#rgb`、`#rgba`、`#rrggbb` 或 `#rrggbbaa`）或一个 `rgb()` / `rgba()` 值。命名颜色和其他颜色空间不被接受。 |
| `image` | 一个图像 | 一个上传的文件，或一个以 `.png`、`.jpg`、`.jpeg`、`.webp`、`.svg` 或 `.gif` 结尾的 `https` URL。 |
| `audio` | 一段音频 | 一个上传的文件，或一个以 `.mp3`、`.ogg` 或 `.wav` 结尾的 `https` URL。 |
| `video` | 一个视频 | 一个上传的文件，或一个以 `.mp4` 或 `.webm` 结尾的 `https` URL。 |

Caputchin 在你保存时校验每一个值，所以一个不合它类型的值在它能到达一位访客之前就被拒绝。

## 保留键

在它的内容字段之外，一个预设携带几个保留的 **元数据键**（每个以一个下划线为前缀），它们控制它如何被选中和解析，而非它显示什么。你如何设置它们取决于那个面：一个 [应用市场游戏作者](/docs/marketplace-game-development/the-caputchin-json-manifest) 在 `caputchin.json` 里字面地写它们；在仪表盘编辑器里（自定义游戏、白标）你通过控件设置它们，而从不键入那个键。无论哪种方式，含义都一样。

| 键 | 维度 | 含义 |
|---|---|---|
| `_lang` | Locale | 一个 locale 预设服务的 BCP-47 语言标签（`en`、`es`，等等）。预设按它分组；几个预设可以共享一个 `_lang`（例如两个英语变体）。 |
| `_direction` | Locale | `ltr` 或 `rtl`。可选，对从右到左的语言（`ar`、`he`、`fa`、`ur`、`yi`、`ps`、`sd`）从 `_lang` 自动派生；很少手工设置。 |
| `_theme` | Skin | `light`、`dark` 或 `any`。一个 `light` / `dark` 预设只在那种背景下显示；一个 `any` 预设在两种下都工作且对任一都有资格。缺失时默认为 `light`。 |
| `_default` | 全部 | 当访客不选一个时，标记服务器为它那组挑的那个预设。每组一个默认（皮肤按模式）；一个 `any` 皮肤可以是亮、暗或两者的默认。 |
| `_extends` | 全部 | 点名另一个要从之继承的预设。见 [扩展一个预设](#extending-a-preset)。 |

保留的元数据键在 **解析期间被剥离**：`_extends` 和 `_default` 绝不到达游戏，只有幸存的元数据（`_lang`、`_direction`、`_theme`）加上扁平化的内容字段被交付。

## 扩展一个预设 [#extending-a-preset]

`_extends` 让一个预设从另一个继承每一个值，于是你只撰写有差异的那些字段，而不是重复一整个预设。把 `_extends` 设为 **同一维度里另一个预设的名字**；这个扩展的预设从那个预设所有的值起步，并覆盖它自己设置的那些键。

```json
{
  "skins": {
    "presets": {
      "brand-light": { "_theme": "light", "accent": "#2da44e", "bg": "#ffffff" },
      "brand-light-warm": { "_extends": "brand-light", "accent": "#d97706" }
    }
  }
}
```

这里 `brand-light-warm` 从 `brand-light` 继承 `bg`，并只改 `accent`。

两个细节：

- **皮肤主题快捷方式。** 在一个皮肤预设上，`_extends` 可以改为点名一个主题（`light` 或 `dark`）而非一个预设。那种形式解析为那个主题的 `_default` 是哪个预设，这是一个把一个变体建立在“那个默认亮皮肤”上而不点名它的便利方式。
- **它解析掉。** `_extends` 被跟随然后被剥离；游戏收到完全合并的结果，绝不收到 `_extends` 键本身。

## 一个模式从哪里来

一个预设能填的那个字段集（它的 **模式**）有三个来源，全都用上面同样的字段类型：

- **应用市场游戏**：模式来自游戏作者的清单，在你打开编辑器时拉取。你覆盖游戏的预设，但不改它的模式。
- **自定义游戏**：你自己在仪表盘里定义模式，然后对着它撰写预设。见 [自定义游戏](/docs/game-customization/custom-games)。
- **组件外壳（白标）**：一个固定的、内置的模式。你覆盖它的预设；那个字段集不是作者声明的。见 [给组件做白标](/docs/widget-customization/white-label)。

## 预设与解析

在一个维度内，字段被归入命名的预设，而服务器从分层的范围为每组解析一个有效预设，站点密钥盖过团队、团队盖过捆绑默认，逐个值计算。选择器按维度不同：locale 由访客的浏览器语言选中、skin 由访客的亮或暗偏好选中（一个模式为 `any` 的预设对任一都有资格），而 configuration 是服务端权威的（访客无法选它）。范围模型见 [概览](/docs/game-customization/overview#troop-and-site-key-scope)。

## 另见

- [游戏自定义概览](/docs/game-customization/overview)：注册并管理游戏，外加 [配置](/docs/game-customization/configurations)、[语言](/docs/game-customization/locale) 和 [皮肤](/docs/game-customization/skin) 的逐维度操作指南。
- [自定义游戏仪表盘模式](/docs/custom-game-development/dashboard-schema)：你自己为一个自定义游戏撰写一个模式。
- [caputchin.json 清单](/docs/marketplace-game-development/the-caputchin-json-manifest)：作为一个应用市场游戏作者声明这些块。
- [给组件做白标](/docs/widget-customization/white-label)：应用到组件外壳上的同样那些类型。