Xime 输入法v2.4.0 定制教程

手机键盘的按钮一般可以设计为4种手势操作: 点按，上滑，下滑，长按。

我们可以每一种手势定义，显示是什么，动作是什么，输出又是什么。

通过抽象配置化就可以做到定制化功能。

⚠️⚠️⚠️版本要求：此功能需要 Xime v2.4.0 及以上版本，旧版本不支持自定义配置文件。⚠️⚠️⚠️

变动

现在，键盘上的26键的上中下显示区和上滑，下滑，长按可定制化。

此外，为了保证简洁性和可维护性，这些功能不会在UI上提供。

因此，下面是一份在UI之外控制键盘行为和显示效果的教程。

教程

下面的内容，针对有动手能力的用户教程。

⚠️⚠️⚠️所有编辑内容都围绕着 xime.custom.yaml 进行！⚠️⚠️⚠️

配置文件结构总览

customization:        # 版本信息,暂时无意义
  distribution_code_name: Xime
  distribution_version: 0.13.3
  generator: "Xime"
  modified_time: "2026-06-09"
  rime_version: 0.14.3

xime_index:           # 方案/插件/模型市场索引
  base_urls: [...]   # 下载源地址列表

style:                # 全局样式
  color_scheme: lavender_purple

color_schemes:        # 配色方案定义
  lavender_purple:    # 配色名称（与 style.color_scheme 对应）
    name: "薰衣草紫"
    primary_color: 0x8F73E2

keyboard:             # 键盘按键配置
  keys:
    q: { tap: "q", swipe_up: "1", swipe_down: {...}, long_press: {...} }
    # ...

`style` — 全局样式

style:
  color_scheme: lavender_purple  # 使用的配色方案名称（对应 color_schemes 中的键名）

其中 color_scheme 为字符串类型，默认值为 "lavender_purple"，用于引用 color_schemes 中定义的配色键名。

比如 app 内置的 8 大颜色主题，你不喜欢可以自定义。

配色主题示例

展示了不同灰度的配色方案（银灰 · 浅、中灰 · 中、烟灰 · 深、墨灰 · 浓），可供参考自定义 color_schemes：

style:
  color_scheme: zine_medium

color_schemes:
  zine_light:
    name: "银灰 · 浅"
    primary_color: 0x9E9E9E
  
  zine_medium:
    name: "中灰 · 中"
    primary_color: 0x616161
  
  zine_dark:
    name: "烟灰 · 深"
    primary_color: 0x424242
  
  zine_deep:
    name: "墨灰 · 浓"
    primary_color: 0x212121

`keyboard.colors` — 键盘颜色配置

可选，不设置则使用内置默认值。

keyboard:
  colors:
    keyboard_bg_color: 0xE3E4E8
    keyboard_bg_color_dark: 0x202020
    key_bg_color: 0xFFFFFF
    key_bg_color_dark: 0x4A4A4A
    # special_key_bg_color: 0x9fef86        # 不设置时默认取主题色
    # special_key_bg_color_dark: 0x4A4A4A   # 不设置时默认取主题色
    candidate_bar_bg_color: 0xE3E4E8
    candidate_bar_bg_color_dark: 0x202020
    key_text_color: 0x202124
    key_text_color_dark: 0xE8EAED
    candidate_text_color: 0x202124
    candidate_text_color_dark: 0xE8EAED

各字段说明如下：

背景色 — keyboard_bg_color / keyboard_bg_color_dark（键盘背景色）、key_bg_color / key_bg_color_dark（按键背景色）、special_key_bg_color / special_key_bg_color_dark（特殊按键背景色，不设置时默认取主题色）、candidate_bar_bg_color / candidate_bar_bg_color_dark（候选栏背景色）
文字色 — key_text_color / key_text_color_dark（按键文字颜色）、candidate_text_color / candidate_text_color_dark（候选文字颜色）

颜色值格式为 0xAARRGGBB（Alpha + RGB），AA 可省略（默认为完全不透明）。

`keyboard.shadow` — 按键阴影配置

可选，不设置则使用默认值。

keyboard:
  shadow:
    enabled: true      # 是否启用阴影
    elevation: 1       # 阴影高度（dp）
    shape_radius: 8    # 阴影圆角半径（dp）

三个配置项：

enabled — 布尔值，默认 true，是否启用按键阴影
elevation — 整数，默认 1，阴影高度（dp）
shape_radius — 整数，默认 8，阴影圆角半径（dp）

你可以通过上面的配置达到无边框的效果：

key

`keyboard.keys` — 键盘按键配置

这是全键盘配置的核心部分，每个按键可以定义 4 种手势操作。

手势类型

每个按键支持四种手势：

点按（tap）— 单击按键，最基础的操作
上滑（swipe_up）— 从按键向上滑动
下滑（swipe_down）— 从按键向下滑动
长按（long_press）— 长按按键，弹出气泡后左右滑动选择

手势值格式

每个手势的值有两种格式：

1. 字符串简写

直接填写字符串，点击后上屏该文本，按键上显示的也是它。

q: { tap: "q" }

2. 对象格式

q: { tap: { label: "Q", action: "commit", value: "q" } }

对象包含以下字段：

label（必填）— 按键上显示的文字
action（必填）— 动作类型，见下方动作列表
value（可选）— 上屏时的输出文本，不指定则用 label
display（可选）— 显示模式，仅 swipe_down 和 long_press 支持

3. 动作类型（action）

支持的动作用于控制按键按下时的行为：

文字输出类 — commit 上屏文字（value 指定内容，不指定则用 label）；repeat 重复上一次输入
编辑操作类 — select_all 全选、copy 复制、cut 剪切、paste 粘贴、undo 撤销、line_start 光标到行首、line_end 光标到行尾
特殊类 — command 执行内置命令（value 指定命令名）；none 无动作，仅用于显示（如显示五笔字根）

4. 内置命令（command）

当 action 为 command 时，value 目前仅支持 clear_composition（清空当前输入编码和候选词）。

5. 显示模式（display）

仅 swipe_down 和 long_press 支持两种模式：

气泡显示（"bubble"）— 下滑或长按时以气泡弹出显示内容，不占用按键空间
按键显示（"key"）— 直接在按键上显示文字，最多显示 2 个字符

长按配置（long_press）

长按支持弹出多个选项供用户滑动选择。使用 display: "bubble" 配合 values 数组：

# 对象格式 — 可指定 label、action、value
long_press:
  display: "bubble"
  values:
    - { label: "大写", action: "commit", value: "A" }
    - { label: "Ä",   action: "commit", value: "ä" }

# 字符串简写 — 直接上屏
long_press:
  display: "bubble"
  values: ["q", "Q"]

下滑配置（swipe_down）

下滑通常用于显示五笔字根（action: none 仅显示不上屏），或快捷操作（如粘贴、全选等）。

字根显示（气泡模式）

swipe_down:
  label: "金 钅𠂊勺㐅 犭𱼀"   # 字根文字
  action: "none"                # 仅显示，不上屏
  display: "bubble"             # 气泡显示

快捷操作（按键模式）

swipe_down:
  label: "粘贴"      # 按键上显示的文字
  action: "paste"    # 粘贴动作
  display: "key"     # 直接显示在按键上

有了上面的基础，我们可以实现下面几种模式：

仓颉输入法显示

cangjie

带快捷编辑键的键盘

shortcut

我最喜欢的五笔字根显示

wubi

如何导入手机app？

你可以通过手机app->Xime输入法->更多(…)->浏览器导入，然后打开浏览器导入 xime.custom.yaml即可。

这个文件可以联 rime 配置一起发行。

声明

如果你看不懂上面的内容，说明你不是上面的使用对象，请不要去尝试。使用默认配置即可。

变动

教程