布局

布局是键盘设计的核心部分，它决定了按键在键盘上的排列方式。

布局原理

布局通过 行 HStack 和 列 VStack 划分空间，最终在 行 或 列 中放置按键。按键通过自身属性 size 的描述，最终确定了自己的位置及尺寸。

举例：

定义一个包含两行，每行中有不同按键的布局：

1
- HStack:
2
    subviews:
3
     - Cell: QButton
4
     - Cell: WButton
5
     - Cell: EButton
6
- HStack:
7
    subviews:
8
     - Cell: AButton
9
     - Cell: SButton

定义一个包含三列，每列中有不同按键的布局：

1
- VStack:
2
    subviews:
3
     - Cell: 1Button
4
     - Cell: 4Button
5
     - Cell: 7Button
6
- VStack:
7
    subviews:
8
     - Cell: 2Button
9
     - Cell: 5Button
10
     - Cell: 8Button
11
- VStack:
12
    subviews:
13
     - Cell: 3Button
14
     - Cell: 6Button
15
     - Cell: 9Button

结合行和列布局，创建一个更复杂的键盘布局：

先是将空间划分为两行
- 在第一行中继续按列划分
  - 在第一列中按行划分
    - 在第一行中放置按键
    - 在第二行中放置按键
    - 在第三行中放置按键
  - 在第二列中放置一个按键集合
  - 在第三列中按行划分
    - 在第一行中放置按键
    - 在第二行中放置按键
    - 在第三行中放置按键
- 在第二行中直接放置按键

1
- HStack:
2
    subviews:
3
      - VStack:
4
          subviews:
5
            - HStack:
6
                subviews:
7
                  - Cell: hpButton
8
                  - Cell: shButton
9
                  - Cell: zhButton
10
            - HStack:
11
                subviews:
12
                  - Cell: lButton
13
                  - Cell: dButton
14
                  - Cell: yButton
15
            - HStack:
16
                subviews:
17
                  - Cell: chButton
18
                  - Cell: qButton
19
                  - Cell: gButton
20
      - VStack:
21
          subviews:
22
            - Cell: symbolicCollection
23
      - VStack:
24
          subviews:
25
            - HStack:
26
                subviews:
27
                  - Cell: bButton
28
                  - Cell: xButton
29
                  - Cell: msButton
30
            - HStack:
31
                subviews:
32
                  - Cell: wzButton
33
                  - Cell: jkButton
34
                  - Cell: rnButton
35
            - HStack:
36
                subviews:
37
                  - Cell: cfButton
38
                  - Cell: tButton
39
                  - Cell: backspaceButton
40
- HStack:
41
    subviews:
42
      - Cell: bottom1Button
43
      - Cell: alphabeticButton
44
      - Cell: bottom2Button
45
      - Cell: spaceButton
46
      - Cell: bottom3Button
47
      - Cell: enterButton

需要注意的是：同级中只能使用相同的类型划分空间。

比如你先用了行划分空间，那么只能按行将空间划分完毕后，才能在行的子级中继续使用列/行进一步划分空间。

错误的示例：

HStack 与 VStack 在同级别中混用

1
- HStack:
2
  ...
3
- VStack:
4
  ...

Cell 与 HStack/VStack 在同级别中混用

1
- HStack:
2
    subviews:
3
      - Cell: AButton
4
      - HStack:
5
          ...

布局的属性

无论是 HStack 还是 VStack，都支持以下属性：

subviews：必选，类型 Object[]，用于定义自己的子视图，可以是 Cell、HStack 或 VStack。
style：可选，类型 String，引用同级样式节点。通常在该样式节点中通过 size 设置 HStack 或 VStack 在父容器中占用的宽度或高度；不设置时，由同级未设置尺寸的元素平均分配剩余空间。

示例：

1
- HStack:
2
    style: "topRowStyle"
3
    subviews:
4
      - Cell: QButton
5
      - Cell: WButton
6
      - Cell: EButton
7
- HStack:
8
    subviews:
9
      - Cell: AButton
10

11
topRowStyle:
12
  size: { height: 1/3 }

表示第一行的高度为容器高度的三分之一，第二行高度为剩余空间的高度。

按键的定义

按键的定义不需要特别的名称，只需要位于当前 Yaml 文件的主节点下即可。

需要注意的是：定义的名称需要与布局中的 Cell 引用的值对应。

示例：

1
...
2
- HStack:
3
    subviews:
4
      - Cell: QButton
5
...
6

7
qButton:
8
  size: { width: 1/3 }
9
  ...

按键的属性

按键支持以下属性：

参数	类型	说明
`size`	`Size`	定义按键占用空间。
`bounds`	`Bounds`	定义按键内容的可视区域，不改变按键占用空间。
`backgroundStyle`	`String 或 ConditionStyle[]`	引用按键背景样式节点。
`foregroundStyle`	`String、String[] 或 ConditionStyle[]`	引用按键前景样式节点，可叠加多个前景样式。
`uppercasedStateForegroundStyle`	`String 或 String[]`	大写状态下的前景样式。
`capsLockedStateForegroundStyle`	`String 或 String[]`	大写锁定状态下的前景样式。
`hintStyle`	`String`	引用按键气泡样式节点。
`hintSymbolsStyle`	`String`	引用长按符号面板样式节点。
`action`	`KeyboardAction`	默认点击动作。
`preeditStateAction`	`KeyboardAction`	预编辑状态（有未上屏输入）下的点击动作；未设置时使用 `action`。
`repeatAction`	`KeyboardAction`	长按后重复执行的动作；未设置时不重复执行。
`uppercasedStateAction`	`KeyboardAction`	大写或大写锁定状态下的点击动作。
`swipeUpAction`	`KeyboardAction`	向上滑动动作。
`swipeDownAction`	`KeyboardAction`	向下滑动动作。
`swipeLeftAction`	`KeyboardAction`	向左滑动动作。
`swipeRightAction`	`KeyboardAction`	向右滑动动作。
`animation`	`String[]`	引用动画节点，可同时配置多个动画。
`notification`	`String 或 String[]`	引用通知节点，通知匹配后可改变样式或动作。

backgroundStyle、foregroundStyle、hintStyle、hintSymbolsStyle、animation、notification 都是通过名称引用同级节点。按键动作参数的具体写法参见按键动作。

如何布局一个键盘

通常一个键盘会包含以下几个区域：

预编辑区：显示当前输入的，但还未上屏的信息，如键入的拼音字母等。
工具栏区：放置一些快捷功能，如打开常用语面板，关闭键盘等等。
按键区：放置各种按键。
横向候选字栏：显示当前输入的候选字。
纵向候选字栏：全屏当前输入的候选字。

将这几个区域组合起来，就可以形成一个完整的键盘布局。