自定义键盘

在内置键盘不能满足您的自定义需求时，您可以根据此文档，自定义属于您自己的键盘。

如何定义一个键盘

这里将一个键盘抽象为 Keyboard, Row, Key，KeySwipe 等模型。

其中 Keyboard 模型用来表示具体的键盘，Row 表示键盘的一行，Key 表示行中按键，KeySwipe 表示按键的划动配置。

Keyboard 模型

name: 键盘名称。
- 必选项，字符串类型。
- 请保证名称的唯一性，否则相同名称的键盘会存在覆盖情况。
isPrimary: 是否是主键盘类型
- 可选值，布尔类型，默认值为 false
- 用于点击符号返回主键盘功能。
rowHeight：键盘中全部行的行高。如果为此项赋值，那么键盘的所有行高都为此值。
- 可选项，对应 RowHeight 选项，可分别为横屏或纵屏设置不同的高度。
buttonInsets: 按钮内距。
- 可选项，对应 ButtonInsets 选项。
rows: 键盘的行。
- 必选项，数组类型。
- 数组中每个元素对应 Row 模型。

keyStyle: 按键样式。

可选项，字典类型。
字典的键: 为样式名称，供按键模式中的 lightModeStyleName 或 darkModeStyleName 引用
字典的值: 为按键样式，对应 KeyStyle 按键样式

配置示例

keyboards:
- name: 26keys
  keyStyle:
    light1:
      buttonBackgroundColor: '0xFF0024E2'
      # 其他属性
    light2:
      buttonBackgroundColor: '0xFF0024E2'
      # 其他属性
    dark1:
      buttonBackgroundColor: '0xFF0024E2'
      # 其他属性
    dark2:
      buttonBackgroundColor: '0xFF0024E2'
      # 其他属性
  rows:
    - keys:
        - action: { character: { char: q }}
          lightModeStyleName: light1
          darkModeStyleName: light1
  # 其他属性

Row 模型

rowHeight: 当前行的行高。
- 可选项，对应 RowHeight 选项，可分别为横屏或纵屏设置不同的高度。
- 如果自定义的键盘的所有行的高度是相等的，请使用 Keyboard 模型中的 rowHeight 属性。
keys：当前行的按键。
- 必选项，数组类型。
- 数组中每个元素对应 Key 模型。

Key 模型

action：按键对应的操作。
- 必选项，字符串类型。内容必须符合 Action 选项，具体如何填写请参考 Action 选项。
width：按键宽度。
- 可选项，字符串类型。如果为空，则默认为 input 宽度选项。
- 填写值对应 KeyWidth 选项选项。
processByRIME：是否由 RIME 引擎处理。
- 可选值，布尔类型(true/false)。如果不填写，默认为 ture，表示默认由 RIME 引擎处理。
注意：此参数对 symbol 类型无效，symbol 类型始终不经过 rime 引擎处理。
label: 按键显示文本。每个元素对应 KeyLabel 模型
- 可选值，字符串类型。如果不填写，则使用 action 对应的文本显示，比如 action 的值为 character(a)，则显示为 a。
- label 可填写两种格式:
  - 格式1: label: '常显文本'，为非空格键指定常显的文本。
  - 格式2: 为空格指定加载文本使用。
```
label:
loadingText: '加载文字'
text: '常显文字'
systemImageName: 'SF Font名称'
```
swipe：按键滑动配置。
- 可选值，数组类型，每个元素对应 KeySwipe 模型。如果为空，则表示该按键没有划动配置。
- 具体配置参考 KeySwipe 模型。
callout：按键长按呼出视图配置。
- 可选值，数组类型，每个元素对应 KeyCallout 模型。如果为空，则表示该按键长按呼出设置。
- 具体配置参考 KeyCallout 模型。
- 例如：
```
callout:
- action: { shortcutCommand: "#上个输入方案" }
```
lightModeStyleName
- 可选项，字符串类型，表示浅色模式下按键样式名称。用来引用 Keyboard 模型的 keyStyle 字典类型的名称。
darkModeStyleName
- 可选项，字符串类型，表示暗色模式下按键样式名称。用来引用 Keyboard 模型的 keyStyle 字典类型的名称。

KeySwipe 模型

direction: 滑动方向。
- 必选值，字符串类型。内容必须符合 Direction 选项选项。
action：表示划动触发的操作。
- 必选值，配置与 Key 模型中的 action 配置相同。
label: 表示划动显示的文本。
- 可选值，字符串类型。配置与 Key 模型中的 label 配置相同。
display: 表示是否在按键 UI 中显示滑动的文本。
- 可选值，布尔类型(true/false)。如果不填写，默认为 true，即显示。
processByRIME: 表示滑动触发操作是否经过 RIME 引擎处理。
- 可选值。布尔类型(true/false)。如果不填写，默认为 false，即不经过 rime 引擎处理。
  
  注意：此参数对 symbol 类型无效，symbol 类型始终不经过 rime 引擎处理。

KeyCallout 模型

注意：长按选项不支持换行

action：表示触发的操作。
- 必选值，配置与 Key 模型中的 action 配置相同。
- 如果不想呼出的 action 操作由 RIME 处理，请使用 symbol, character开头的操作会经过 rime 引擎处理。
label: 表示划动显示的文本。
- 必选值，字符串类型。配置与 Key 模型中的 label 配置相同。

KeyLabel 模型

loadingText: 空格启动加载文字，仅对 Action是空格时 有效，且只有键盘首次加载显示。
text: 按键显示文字。如果想使用无刻模式，可以使用 " " 设置
systemImageName: 苹果 SF Symbol 名称，可在官网下载查询

注意：SF Symbol 图片效果也可通过按键的 keyStyle 调节。

Action 选项

对应 action 的值，action的值必须为以下形式

backspace：表示物理键盘的退格键。
enter：表示物理键盘的回车键。
shift：表示物理键盘的 Shift 键。
tab：表示物理键盘的 Tab 键。
space：表示物理键盘的空格键。
character: { char: 字符 }：表示物理键盘的字符按键，其中字符表示具体的 ASCII 字符。

注意：character类型会经过 RIME 引擎处理，所以必须是 ASCII 中的单个字符，如果是多个，则截取首个字符。

例如：
- a 键的配置为 action: { character: { char: a } }，注意是小写，如果想显示为大写可以通过 label 属性配置实现。
characterMargin: { char: 字符 }：用来表示虚拟按键的占位符。不显示，但点击后会和 character 的效果相同。例如中文26键中 A 键的左侧空白，L键的右侧空白。

注意：characterMargin 类型会经过 RIME 引擎处理，所以必须是 ASCII 中的单个字符，如果是多个，则截取首个字符。
keyboardType: type: 表示切换虚拟键盘的类型，其中 type 表示切换的类型。type 必须符合 KeyboardType 选项，具体如何填写请参考 KeyboardType 选项。

例如：
- 表示切换到数字九宫格键盘 action: { keyboardType: numericNineGrid }。
- 表示切换分类符号键盘 action: { keyboardType: classifySymbolic }。
- 表示切换到自定义键盘-仓颉 action: { keyboardType: 仓颉 }。
symbol: { char: string }：用来表示想要输入字符串，其中 string 表示您想输入的字符串，可以为任何 unicode 字符，不限长度。

注意：symbol 类型不会经过 RIME 引擎处理。

例如：
- action: { symbol: { char: 您好 } }，会直接上屏“您好”。
shortcutCommand: command: 用来表示快捷指令，其中 command 表示指令名称。具体指令名称请参考 #ShortcutCommand 选项。

例如：
- action: { shortcutCommand: "#行首" }：表示移动到行首。
none: 仅用来表示占位符，不做任何操作且UI不应呈现。
nextKeyboard: 系统键盘切换键，类似系统的地球键，用来切换到 iOS 系统中的其他键盘。

KeyboardType 选项

对应 action 中 keyboardType 的 type 值。

alphabetic：表示英文键盘。
classifySymbolic：表示分类符号键盘。
chinese：表示中文26键的键盘。
chineseNineGrid：表示中文九宫格键盘。
numericNineGrid：表示数字九宫格键盘。
emojis：表示 Emoji 键盘，预留功能，目前还不支持 emoji 键盘。
自定义键盘名称: 表示自定义键盘，对应 Keyboard 模型中的 name 值。

ShortcutCommand 选项

对应 action 中 shortcutCommand 的 command 值。

#重输：表示清空还未上屏的输入字符。
#简繁切换: 表示中文简繁切换。
#中英切换：表示中文英文切换。
#行首：表示光标移动到行首。
#行尾：表示光标移动到行尾。
#次选上屏：表示候选文字列表中次选文字上屏。
#三选上屏：表示候选文字列表中第三位候选文字上屏。
#上个输入方案：表示当在“输入方案列表”中选择两个或两个以上方案时，最近一次的输入方案与当前输入方案切换。
#换行：表示换行，注意：这里使用 \r 表示换行。
#RimeSwitcher：表示进入 RIME 的 switch 功能。
#左移：表示光标向左移动一个字符。
#右移：表示光标向右移动一个字符。
sendKeys: { keys: string }：表示向 RIME 引擎发送指定按键。string 表示组合按键的配置，配置示例: action: { shortcutCommand: { sendKeys: { keys: "Control+l" } } }。
openURL: { url: string }：表示打开某个 URL。string 表示需要打开的地址。 openURL 有三种使用方式：
1. 将 string 设置为固定值，每次打开一个固定的地址。如每次打开微信：action: { shortcutCommand: { openURL: { url: "weixin://" } } }；
2. 将 string 设置为 #pasteboardContent，每次打开剪贴板中的地址，如果剪贴板中有多个地址，则只会打开首个地址。
3. 将 string 设置为 固定地址#pasteboardContent，表示使用剪贴板中内容替换地址中的 #pasteboardContent，然后在打开地址，如使用百度搜索剪贴板中的内容 action: { shortcutCommand: { openURL: { url: "https://www.baidu.com/s?wd=#pasteboardContent" } } }.
#关闭键盘：表示关闭当前键盘。
#左手模式: 单手模式中的左手模式。
#右手模式: 单手模式中的右手模式。
#方案切换: 显示以选的方案列表，在列表中可切换当前输入方案。

KeyWidth 选项

用来表示键宽。

KeyWidth 选项可以填写以下值：

available: 表示剩余宽度，如果同行中有两个及两个以上的按钮的宽度为 available 类型，则它们会平分剩余宽度。
input: 全键盘中全部 input 类型的按键，宽度相同。系统会自动计算 input 类型的宽度。
inputPercentage: value: 使用 input 类型宽度的百分比作为按键的宽度, 其中 value 为表示百分比的值，浮点类型。

例如:
- width: { inputPercentage: 2 } 表示 input 类型宽度的 2 倍作为按键宽度。
- width: { inputPercentage: 0.5 } 表示 input 类型宽度的 1/2 作为按键宽度。
percentage: value：使用行宽度的百分比作为按键的宽度，其中 value 为表示百分比的值，浮点类型。

例如：width: { percentage: 0.13 } 表示行宽度的 13% 作为当前按键的宽度。
points: value: 指定按键宽度为以 pt(point) 为单位的固定值。其中 value 为浮点类型。

例如：width: { points: 20 }：表示当前按键宽度为 20 个 pt。

按键宽度有两种表示方式：

方式1: 直接赋值，表示横屏模式/纵屏模式宽度相同。

width: available
width: { percentage: 0.13 }

方式2: 为横屏/纵屏模式设置不同值。

width:
  portrait: { percentage: 0 }
  landscape: { percentage: 0.07 }

Direction 选项

up: 表示向上划动。
down：表示向下划动。
left: 表示向左划动。
right：表示向右划动。

RowHeight 选项

用来表示行高。有两种表达方式：

方式1：单独填写浮点类型数值，如：rowHeight: 40.5，则表示屏幕在横屏与纵屏模式下行高相同。
方式2：纵屏和横屏模式下设定不同的高度。可以为portrait与landscape赋值。如：

rowHeight:
  portrait: 40.5
  landscape: 30.5

ButtonInsets 选项

用来表示按键内距。有两种表达方式：

方式1: 单独填写浮点数值，如buttonInsets: 3，表示按键的四条边的内距相同，都为 3。
方式2：对象模式，为四边分别设定内距。如：

buttonInsets: { left: 2, right: 2, top: 4, bottom: 4 }

注意：单个属性如果未赋值，则该属性值为零。

KeyStyle 按键样式

以下颜色均为 BGR格式，且必须以 0x 开头，0x 只是表明格式为十六进制，且程序也是以十六进制做处理的，别想着省略 0x，或者转为别的进制。

buttonBackgroundColor: 按键背景色，字符串类型。
pressedButtonBackgroundColor: 按下时按键背景色，字符串类型。
buttonForegroundColor: 按键上文字颜色，字符串类型。
pressedButtonForegroundColor：当按键按下时，按键上文字颜色，字符串类型。
swipeForegroundColor: 按键划动文字颜色，字符串类型。
pressedSwipeForegroundColor: 当按键按下时，按键划动文字颜色，字符串类型。
cornerRadius: 按键的圆角半径，数值类型。
borderColor：按键边框色，字符串类型。
borderSize：按键边框大小，数值类型。
fontSize：按键文字大小，数值类型。
swipeFontSize：划动文字大小，数值类型。
lowerEdgeColor：按键下方边缘颜色，字符串类型。
shadowColor: 按键阴影颜色，字符串类型。
shadowSize：按键阴影大小，数值类型。

配置示例

keyboards:
  - name: "仓颉"
    isPrimary: true
    rows:
      - keys:
          - action: { character: { char: q } }
            label: "手"
            swipe:
              - direction: up
                action: { character: { char: 1 } }
                display: true
          - action: { character: { char: w } }
            label: "田"
            swipe:
              - direction: up
                action: { character: { char: 2 } }
                display: true
          - action: { character: { char: e } }
            label: "水"
            swipe:
              - direction: up
                action: { character: { char: 3 } }
                display: true
          - action: { character: { char: "r" } }
            label: "口"
            swipe:
              - direction: up
                action: { character: { char: "4" } }
                display: true
          - action: { character: { char: "t" } }
            label: "廿"
            swipe:
              - direction: up
                action: { character: { char: "5" } }
                display: true
          - action: { character: { char: "y" } }
            label: "卜"
            swipe:
              - direction: up
                action: { character: { char: "6" } }
                display: true
          - action: { character: { char: "u" } }
            label: "山"
            swipe:
              - direction: up
                action: { character: { char: "7" } }
                display: true
          - action: { character: { char: "i" } }
            label: "戈"
            swipe:
              - direction: up
                action: { character: { char: "8" } }
                display: true
          - action: { character: { char: "o" } }
            label: "人"
            swipe:
              - direction: up
                action: { character: { char: "9" } }
                display: true
          - action: { character: { char: "p" } }
            label: "心"
            swipe:
              - direction: up
                action: { character: { char: "0" } }
                display: true
      - keys:
          - action: { characterMargin: { char: "a" } }
            width: available
          - action: { character: { char: "a" } }
            label: "日"
            swipe:
              - direction: up
                action: { character: { char: "!" } }
                display: true
          - action: { character: { char: "s" } }
            label: "尸"
            swipe:
              - direction: up
                action: { character: { char: "@" } }
                display: true
          - action: { character: { char: "d" } }
            label: "木"
            swipe:
              - direction: up
                action: { character: { char: "#" } }
                display: true
          - action: { character: { char: "f" } }
            label: "火"
            swipe:
              - direction: up
                action: { character: { char: "$" } }
                display: true
          - action: { character: { char: "g" } }
            label: "土"
            swipe:
              - direction: up
                action: { character: { char: "%" } }
                display: true
          - action: { character: { char: "h" } }
            label: "竹"
            swipe:
              - direction: up
                action: { character: { char: "&" } }
                display: true
          - action: { character: { char: "j" } }
            label: "十"
            swipe:
              - direction: up
                action: { character: { char: "*" } }
                display: true
          - action: { character: { char: "k" } }
            label: "大"
            swipe:
              - direction: up
                action: { character: { char: "(" } }
                display: true
          - action: { character: { char: "l" } }
            label: "中"
            swipe:
              - direction: up
                action: { character: { char: ")" } }
                display: true
          - action: { characterMargin: { char: "l" } }
            width: available
      - keys:
          - action: { keyboardType: classifySymbolic }
            width: { percentage: 0.13 }
          - action: { characterMargin: { char: "z" } }
            width: available
          - action: { character: { char: "z" } }
            label: "重"
            swipe:
              - direction: up
                action: { character: { char: "~" } }
                display: true
          - action: { character: { char: "x" } }
            label: "難"
            swipe:
              - direction: up
                action: { character: { char: ":" } }
                display: true
          - action: { character: { char: "c" } }
            label: "金"
            swipe:
              - direction: up
                action: { character: { char: "'" } }
                display: true
          - action: { character: { char: "v" } }
            label: "女"
            swipe:
              - direction: up
                action: { character: { char: "_" } }
                display: true
          - action: { character: { char: "b" } }
            label: "月"
            swipe:
              - direction: up
                action: { character: { char: "," } }
                label: "，"
                display: true
          - action: { character: { char: "n" } }
            label: "弓"
            swipe:
              - direction: up
                action: { character: { char: "." } }
                label: "。"
                display: true
          - action: { character: { char: "m" } }
            label: "一"
            swipe:
              - direction: up
                action: { character: { char: "?" } }
                label: "？"
                display: true
          - action: { characterMargin: { char: "m" } }
            width: available
          - action: backspace
            width: { percentage: 0.13 }
            swipe:
              - direction: up
                action: { shortcutCommand: "#重输" }
      - keys:
          - action: { keyboardType: numericNineGrid }
            width: { percentage: 0.19 }
          - action: space
            width: available
            label:
              loadingText: "仓输入法"
              text: "空格"
          - action: { character: { char: "," } }
            label: "，"
            swipe:
              - direction: up
                action: { character: { char: "." } }
                label: "。"
                display: true
          - action: { keyboardType: alphabetic }
            width: { percentage: 0.13 }
          - action: enter
            width: { percentage: 0.19 }

配置工具

感谢 @lost-melody 开发的自定义键盘工具。

https://lost-melody.github.io/hamster-tools

如何使用定义好的键盘

「仓」提供两种方式使用自定义键盘。

方式一：导入

「键盘设置」->「键盘布局」，点击「+」，可将节点为 keyboards 的自定义键盘 yaml 文件导入到仓中。

方式二：自定义配置文件

这部分可以参考，SharedSupport/hamster.yaml文件，在这个配置文件中有如下内容：

keyboards:
  __include: hamster_keyboards:/keyboards

这个配置的意思是，导入hamster_keyboards.yaml文件中的keyboards节点内容。

而keyboards节点内容就是定义好的键盘。其为数组类型，可以定义多个键盘。

内容类似如下，下面示例中定义了两个键盘。

keyboards:
  - name: "仓颉"
    # 省略键盘定义内容
  - name: "大千注音"
    # 省略键盘定义内容

这两种方式有什么区别？

方式一是通过界面导入的，导入的内容会存储在应用内部存储（非文本文件格式），不利于临时修改调整。也不利于 iCloud同步 功能。
方式二是通过配置文件生效的，您可以看到明文内容，可随时调整，也可以利用iCloud同步功能。

自定义键盘

自定义键盘

如何定义一个键盘

Keyboard 模型

Row 模型

Key 模型

KeySwipe 模型

KeyCallout 模型

KeyLabel 模型

Action 选项

KeyboardType 选项

ShortcutCommand 选项

KeyWidth 选项

Direction 选项

RowHeight 选项

ButtonInsets 选项

KeyStyle 按键样式

配置示例

配置工具

如何使用定义好的键盘

results matching ""

No results matching ""