「仓输入法皮肤」迁移指南

如何迁移

背景及前景样式添加 `buttonStyleType` 参数

新增必选参数 buttonStyleType，用于设定样式的类型。

确保背景样式（backgroundStyle）及前景样式（foregroundStyle）中都指定了 buttonStyleType 参数，否则无法解析已定义的样式。

示例：

1
# 改造前
2
foregroundStyle: qButtonForegroundStyle
3
qButtonForegroundStyle:
4
  text: "q"
5

6
# 改造后
7

8
foregroundStyle: qButtonForegroundStyle
9
qButtonForegroundStyle:
10
  buttonStyleType: text
11
  text: "q"

根据你想要添加的样式内容，为 buttonStyleType 指定相应的值，具体内容请查阅 buttonStyleType 配置参考。

文字位置

在新版中，文字样式的初始位置为「居中」对齐。如果之前为文字样式添加了 center 属性，需要将其移除或者调整其值，使文字显示在您想要的位置。

JavaScript 脚本内容移除

在新版中，皮肤中的 JavaScript 脚本功能已被废除。这意味着之前通过 JavaScript 动态生成的样式名称或文本内容将不再有效。

如需动态生成样式或文本，请使用事件通知、条件样式来代替。

事件通知：用来监听某个键盘的状态变化，当状态改变时，更新相应的样。使用场景：根据输入了某个按键，切换另一个按键的样式；回车键根据环境变化。
条件样式：用来初始化按键的样式，根据某个条件来决定使用哪种样式。使用场景：中英切换，简繁切换。

示例：

1
lockButton:
2
  backgroundStyle: systemButtonBackgroundStyle
3

4
  foregroundStyle: |-
5
    // JavaScript
6
    function getText() {
7
      return $getSymbolicKeyboardLockState() ? "lockButtonForegroundStyle" : "unlockButtonForegroundStyle";
8
    }
9

10
lockButtonForegroundStyle:
11
  systemImageName: "lock"
12
  normalColor: 000000
13
  highlightColor: 000000
14
  fontSize: 20
15

16
unlockButtonForegroundStyle:
17
  systemImageName: "lock.open"
18
  normalColor: 000000
19
  highlightColor: 000000
20
  fontSize: 20

1
lockButton:
2
  backgroundStyle: systemButtonBackgroundStyle
3

4
  foregroundStyle:
5
    - {
6
        styleName: unlockButtonForegroundStyle,
7
        conditionKey: $symbolicKeyboardLockState,
8
        conditionValue: false,
9
      }
10
    - {
11
        styleName: lockButtonForegroundStyle,
12
        conditionKey: $symbolicKeyboardLockState,
13
        conditionValue: true,
14
      }
15

16
lockButtonForegroundStyle:
17
  buttonStyleType: systemImage
18
  systemImageName: "lock"
19
  normalColor: 000000
20
  highlightColor: 000000
21
  fontSize: 20
22

23
unlockButtonForegroundStyle:
24
  buttonStyleType: systemImage
25
  systemImageName: "lock.open"
26
  normalColor: 000000
27
  highlightColor: 000000
28
  fontSize: 20

按键长按显示符号样式调整

在新版本中使用 hintSymbolsStyle（旧版本为：holdSymbolsStyle）来定义按键长按时显示的符号样式。

示例：

1
qButton:
2

3
  holdSymbolsStyle: qButtonHoldSymbolsStyle
4

5
  hintSymbolsStyle: qButtonHintSymbolsStyle

同时，里面的参数也发生了一些变化。

新增可选 size 参数，可自定义符号列表中符号的大小，如果不指定，默认与当前按键的可视区域大小相同。
旧版本使用 selectedStyle 定义选中后的符号高亮样式，新版本中使用 selectedBackgroundStyle 参数。
旧版本使用 foregroundStyle 与 actions 联合定义一个符号的外观及它的行为。新版本新增 symbolStyles 参数，用于定义长按后显示的每个符号的样式。

1
qButtonHoldSymbolsStyle:
2
  backgroundStyle: alphabeticHoldSymbolsBackgroundStyle
3

4
  foregroundStyle:
5
    - qButtonHoldSymbolsOfqForegroundStyle
6
    - qButtonHoldSymbolsOf1ForegroundStyle
7
    - qButtonHoldSymbolsOfQForegroundStyle
8
  actions:
9
    - { character: q }
10
    - { symbol: 1 }
11
    - { character: Q }
12

13

14
  selectedStyle: alphabeticHoldSymbolsSelectedStyle
15
  selectedIndex: 0

1
qButtonHintSymbolsStyle:
2

3
  size:
4
    width: 50
5
    height: 50
6
  insets: { top: 4, bottom: 4, left: 4, right: 4 }
7

8
  backgroundStyle: alphabeticHoldSymbolsBackgroundStyle
9

10
  selectedBackgroundStyle: alphabeticHoldSymbolsSelectedStyle
11

12
  selectedIndex: 0
13

14
  symbolStyles:
15
    - qButtonHintSymbolsOf1Style
16
    - qButtonHintSymbolsOf2Style
17
    - qButtonHintSymbolsOf3Style

现在单个符号的样式与键盘按键样式是相同的。如：

1
qButtonHintSymbolsOf1Style:
2
  foregroundStyle: qButtonHoldSymbolsOfqForegroundStyle
3
  action: { character: q }

动画调整

旧版本的动画定义是在背景样式或前景样式中定义的，而新版本中，动画必须定义在「按键」的样式下。

示例：

1
# 字母按键背景样式
2
alphabeticBackgroundStyle:
3
  ...
4
  animation: alphabeticBackgroundAnimation
5

6
# 字母按键背景动画
7

8
alphabeticBackgroundAnimation:
9
  # type: 动画类型
10
  # - bounds: 尺寸大小变化动画
11
  - type: bounds
12
    duration: 40 # 动画时长，单位毫秒
13
    repeatCount: 1
14
    fromScale: 1
15
    toScale: 0.87
16
  - type: bounds
17
    duration: 80
18
    repeatCount: 1
19
    fromScale: 0.87
20
    toScale: 1
21
  - type: apng
22
    file: animation

1
qButton:
2
  backgroundStyle: qButtonBackgroundStyle
3

4
  animation:
5
    - scaleAnimation
6
    - cartoonAnimation
7
    - physicsAnimation
8

9
# 放大或缩小的动画
10
scaleAnimation:
11
  animationType: scale
12
  isAutoReverse: false
13
  scale: 0.80
14
  pressDuration: 40
15
  releaseDuration: 80
16

17
# 用于替代 apng 图片类型的动画
18
cartoonAnimation:
19
  animationType: cartoon
20
  # 默认60，可不设置
21
  fps: 60
22
  images:
23
    - lleeimage_0.png
24
    - lleeimage_1.png
25

26
# 用于替换之前 emit 动画
27

28
physicsAnimation:
29
  animationType: physics
30
  duration: 1500
31
  images:
32
    - 01.png
33
    - 02.png
34
  randomImage: true
35
  randomPosition: { x: 50, y: 10 }
36
  startPosition: { x: 0, y: 0 }
37
  endPosition: { x: 0, y: -70 }
38
  useOpacity: true
39
  startOpacity: 1
40
  endOpacity: 0.2
41
  useRotation: true
42
  randomAngle: 6.28
43
  startAngle: 0
44
  endAngle: 6.28

在按键的定义中，新增了 animation 参数，用于定义按键的动画效果。其中每个动画通过 animationType 参数来指定动画类型，不同的动画类型有不同的参数和动画效果。

具体参数说明请查阅参数字典。

预编辑区调整

预编辑区样式关键字变更

1
#
2
preedit:
3

4
preeditStyle:
5
  insets: { left: 4, top: 1 }
6
  backgroundStyle: preeditBackgroundStyle
7
  foregroundStyle: preeditForegroundStyle

工具栏调整

工具栏调整结构

将工具栏样式与工具栏布局单独为两个属性：toolbarStyle 与 toolbarLayout，
删除原候选文字栏设置相关属性

工具栏布局 toolbarLayout 与按键区域布局逻辑相同

1
#
2
    toolbar:
3
      backgroundStyle: toolbarBackgroundStyle
4
      # primaryButtonStyle: primaryButtonStyle
5
      secondaryButtonStyle:
6
        - toolbarButton1Style
7
        - toolbarButton2Style
8
        - toolbarButton3Style
9
        - toolbarButton4Style
10
      horizontalCandidateStyle: horizontalCandidateStyle
11
      verticalCandidateStyle: verticalCandidateStyle
12

13
    # 工具栏样式
14
    toolbarStyle:
15
      insets: { left: 50, right: 50 }
16
      backgroundStyle: toolbarBackgroundStyle
17
    # 工具栏布局
18
    toolbarLayout:
19
    - HStack:
20
        subviews:
21
        - Cell: horizontalNumberSymbols
22
        - Cell: leftArrowButton
23
        - Cell: downArrowButton
24
        - Cell: rightArrowButton

横向候选文字栏调整

横向候选文字栏从原 toolbar 属性中拆分，独立为 horizontalCandidatesStyle，horizontalCandidatesLayout 两个属性。

horizontalCandidatesStyle：用于设置文字栏整体的外观样式
horizontalCandidatesLayout：用于设置文字栏的内部空间的布局，与按键区域布局逻辑相同

1
#
2
    toolbar:
3
      ...
4
      horizontalCandidateStyle: horizontalCandidateStyle
5

6
    # 横向候选文字栏调整
7
    horizontalCandidatesStyle:
8
      insets: { left: 3, bottom: 1, top: 3 }
9
      backgroundStyle: horizontalCandidatesBackgroundStyle
10
    # 横向候选文字栏布局
11
    horizontalCandidatesLayout:
12
    - HStack:
13
        subviews:
14
            - Cell: horizontalCandidates
15
            - Cell: clearPreeditButton
16
            - Cell: expandButton

纵向候选文字栏调整

纵向候选文字栏也从原 toolbar 属性中拆分，独立为样式 verticalCandidatesStyle 布局 verticalCandidatesLayout 两个属性。

verticalCandidatesStyle：用于设置文字栏整体的外观样式
verticalCandidatesLayout：用于设置文字栏的内部空间的布局，与按键区域布局逻辑相同

1
#
2
    toolbar:
3
      ...
4
      verticalCandidateStyle: verticalCandidateStyle
5

6
    # 纵向候选文字栏样式
7
    verticalCandidatesStyle:
8
      insets: { top: 3, bottom: 3, left: 4, right: 4 }
9
      backgroundStyle: verticalCandidateBackgroundStyle
10
    # 纵向候选文字栏布局
11
    verticalCandidatesLayout:
12
      - HStack:
13
          subviews:
14
            - Cell: verticalCandidates
15
      - HStack:
16
          style: verticalLastRowStyle
17
          subviews:
18
            - Cell: verticalPageUpButton
19
            - Cell: verticalPageDownButton
20
            - Cell: collapseCandidatesButton
21
            - Cell: candidateBackspaceButton

候选字长按列表调整

候选字长按列表 candidateContextMenu 属性从 toolbar 中拆分。

1
#
2
    toolbar:
3
      ...
4
      candidateContextMenu: candidateContextMenu
5

6
    candidateContextMenu:
7
      - name: "测试删除"
8
        action: { sendKeys: "Shift+Delete" }
9

10
candidateContextMenu:
11
  - name: "测试删除"
12
  action: { sendKeys: "Shift+Delete" }

新增横向自定义符号列表

1
    horizontalNumberSymbols:
2

3
      type: horizontalSymbols
4
      size:
5
        width: 2/3
6
      # （非必须，默认为 5）用来调整显示区域内最大列数
7
      maxColumns: 10
8
      # （非必须，默认为 false）用来调整显示区域内的内容是否从右向左排列
9
      contentRightToLeft: true
10
      insets: { left: 3, right: 3 }
11
      backgroundStyle: alphabeticBackgroundStyle
12
      dataSource: horizontalSymbolsDataSource
13
      # 用于定义符号列表中每个符号的样式(仅支持文本)
14
      cellStyle: collectionCellStyle
15

16
    collectionCellStyle:
17
      backgroundStyle: collectionCellBackgroundStyle
18
      foregroundStyle: collectionCellForegroundStyle
19

20
    collectionCellBackgroundStyle:
21
      buttonStyleType: fileImage
22
      highlightImage:
23
        file: anjian
24
        image: image11
25

26
    collectionCellForegroundStyle:
27
      buttonStyleType: text
28
      normalColor: 000000
29
      badgeNormalColor: 575757
30
      badgeHighlightColor: 575757
31
      fontSize: 18
32
      fontWeight: bold
33

34
    # 数据源无需定义在 dataSource 之下
35
    horizontalSymbolsDataSource:
36
      - { label: '1', action: tab }
37
      - 2
38
      - 3
39
      - 4

数据源的定义目前支持三种方式

纯字符串

1
horizontalSymbolsDataSource:
2
  - 1
3
  - 2
4
  ...

显示与输出分开定义

1
  horizontalSymbolsDataSource:
2
    - { label: '1', value: "a" }
3
    ...

注意：这种方式会使用 symbol 类型直接上屏，不会发送给 rime 引擎。

独立 action 定义

1
horizontalSymbolsDataSource:
2
  - { label: '1', action: tab }
3
  ...

这种方式有最大的灵活度，你可以为每个数据源自定义按键动作。

数据源对象新增 styleName 参数，用于指定自定义样式。

可选参数，默认为空，如果不指定，则使用 cellStyle 定义的文本样式。

注意：此参数必须与 label 一起使用。

1
horizontalSymbolsDataSource:
2
  - { label: '1', action: tab, styleName: 'leftArrowButton'}
3
  - { label: '1', value: "1", styleName: 'leftArrowButton'}
4
  - 2
5
  - 3
6
  - 4
7
leftArrowButton:
8
  backgroundStyle: alphabeticBackgroundStyle
9
  foregroundStyle:
10
    - leftArrowButtonForegroundStyle

styleName 引用的样式与按键样式定义相同。

注意：动作 action 的定义需要放在数据源中，样式引用中的定义的 action 是无效的。

新增横向候选字列表类型

为了支持横向候选文字栏可以自定义布局，新增了 horizontalCandidates 类型。

用于在自定义布局中，自定义一块区域用来显示横向候选文字。

注意：此类型仅适用于 horizontalCandidatesLayout 布局中，如果在其他布局中使用，会出现不显示候选字的问题。

1
horizontalCandidates:
2
  # 定义一个横向候选文字展示区域
3
  type: horizontalCandidates
4
  size:
5
    width: 2/3
6
  # （非必须，默认值为 7）用于定义显示区域内最大候选文字数量
7
  maxColumns: 10
8
  insets: { left: 3, right: 3 }
9
  backgroundStyle: alphabeticBackgroundStyle
10
  # 用于定义候选文字显示样式
11
  candidateStyle: candidateStyle
12

13
candidateStyle:
14
  insets: { left: 3, right: 3 }
15
  highlightBackgroundColor: ffffff
16
  preferredBackgroundColor: ffffff
17
  preferredIndexColor: 000000
18
  preferredTextColor: 000000
19
  preferredCommentColor: 000000
20
  indexColor: 000000
21
  textColor: 000000
22
  commentColor: 000000
23
  indexFontSize: 18
24
  textFontSize: 18
25
  commentFontSize: 18

新增纵向候选文字列表类型

为了支持纵向候选文字区域可以自定义布局，新增了 verticalCandidates 类型。

用于在自定义布局中，自定义一块区域用来显示纵向候选文字。

注意：此类型仅适用于 verticalCandidatesLayout 布局中，如果在其他布局中使用，会出现不显示候选字的问题。

1
verticalCandidates:
2
  # 定义一个纵向候选文字显示区域
3
  type: verticalCandidates
4
  insets: { left: 3, right: 3 }
5
  # （非必须，默认值为 4）显示区域内候选文字最大行数
6
  maxRows: 8
7
  # （非必须，默认值为 5）显示区域内候选文字最大列数
8
  maxColumns: 10
9
  # （非必须）显示区域内分割线颜色
10
  separatorColor: '#33338888'
11
  backgroundStyle: alphabeticBackgroundStyle
12
  # 候选文字样式
13
  candidateStyle: verticalCandidateCellStyle
14

15
verticalCandidateCellStyle:
16
  highlightBackgroundColor: ffffff
17
  preferredBackgroundColor: ffffff
18
  preferredIndexColor: 1a73e9
19
  preferredTextColor: 1a73e9
20
  preferredCommentColor: 1a73e9
21
  indexColor: 000000
22
  textColor: 000000
23
  commentColor: 000000
24
  indexFontSize: 16
25
  textFontSize: 16
26
  commentFontSize: 16
27
  bottomRowHeight: 50

数据源调整

符号列表的数据源，无需在放在 dataSource 下。

1
#
2
dataSource:
3
  category:
4
    [
5
      "常用",
6
      "中文",
7
      ...
8
    ]
9
  常用:
10
    - "，"
11
    - "。"
12
    - "？"
13
    ...
14

15
category:
16
    [
17
    "常用",
18
    "中文",
19
    ...
20
    ]
21
常用:
22
    - "，"
23
    - "。"
24
    - "？"
25
    ...