样式

样式节点用于描述键盘中可绘制内容的外观。按键、区域、集合视图等节点通常通过 backgroundStyle 和 foregroundStyle 引用样式节点。

样式引用关系

backgroundStyle：引用背景样式。通常用于绘制背景色、渐变色、图片背景等。
foregroundStyle：引用前景样式。通常用于绘制文本、图标或叠加元素；可配置为数组以叠加多个前景样式。
uppercasedStateForegroundStyle / capsLockedStateForegroundStyle：按键在大写/大写锁定状态下使用的前景样式。
hintStyle：按键气泡样式。
hintSymbolsStyle：长按符号面板样式。

样式节点本身必须通过 buttonStyleType 指定类型，但区域样式（如 keyboardStyle、toolbarStyle）和集合视图的 cellStyle 引用节点不一定需要 buttonStyleType，它们通常再通过 backgroundStyle / foregroundStyle 引用真正的绘制样式。

背景样式

通过 backgroundStyle 参数引用。

类型：String | ConditionStyle[]

是否必须：否。不设置时，不绘制背景。

参见条件样式 ConditionStyle

前景样式

通过 foregroundStyle 参数引用。

类型：String | String[] | ConditionStyle[]

是否必须：否。不设置时，不绘制前景。

参见条件样式 ConditionStyle

前景样式可以配置为字符串数组，用于在同一个按键上叠加多个文本、图标或图片样式。

通用样式参数

以下参数可用于多个样式类型。

参数	类型	默认值	说明
`buttonStyleType`	`'geometry'、'systemImage'、'assetImage'、'fileImage'、'text'`	无	样式类型。
`insets`	`{ top?: Float, left?: Float, bottom?: Float, right?: Float }`	`{ top: 0, left: 0, bottom: 0, right: 0 }`	缩小样式绘制区域。
`bounds`	`Bounds`	当前按键区域	进一步定义样式可视区域。
`center`	`{ x?: Float, y?: Float }`	当前区域中心点	调整内容中心点位置。
`zPosition`	`Float、'above' 或 'below'`	无	图层层级；数值表示具体层级，`above` 表示在按键上方，`below` 表示在按键下方。
`normalColor`	`String 或 String[]`	无	普通状态颜色。`geometry` 支持颜色数组作为渐变色。
`highlightColor`	`String 或 String[]`	无	按下状态颜色。`geometry` 支持颜色数组作为渐变色。

字体参数

systemImage 和 text 都支持字体相关参数。

参数	类型	默认值	说明
`fontSize`	`Float 或 String`	系统默认字体大小	字体大小。字符串可写数字字符串，也可写 `em` 相对单位。
`fontWeight`	`'ultraLight'、'thin'、'light'、'regular'、'medium'、'semibold'、'bold'、'heavy'、'black'`	`regular`	字重。

fontSize 示例：

1
fontSize: 18
2
fontSize: '18'
3
fontSize: '1.2em'

其中 1.2em 表示系统默认字体大小的 1.2 倍。

图片通用参数

systemImage、assetImage、fileImage 支持图片显示模式。

参数	类型	默认值	说明
`contentMode`	`'scaleToFill'、'scaleAspectFit'、'scaleAspectFill'、'center'`	见各样式类型说明	图片显示模式。

可选值：

scaleToFill：拉伸填充。
scaleAspectFit：按比例缩放以适应。
scaleAspectFill：按比例缩放以填充。
center：居中显示。

样式类型

geometry

通过设置 buttonStyleType: geometry，使用 iOS 原生属性绘制形状、颜色、边框和阴影。

参数	类型	默认值	说明
`normalColor`	`String 或 String[]`	无	普通状态颜色。数组表示渐变色。
`highlightColor`	`String 或 String[]`	无	按下状态颜色。数组表示渐变色。
`colorLocation`	`Double[]`	无	渐变色位置，取值范围 `0.0` 到 `1.0`。
`colorStartPoint`	`{ x: Double, y: Double }`	系统默认	渐变开始位置。
`colorEndPoint`	`{ x: Double, y: Double }`	系统默认	渐变结束位置。
`colorGradientType`	`'axial'、'conic'、'radial'`	`axial`	渐变类型。
`cornerRadius`	`Double`	无	圆角半径。
`borderSize`	`Double`	无	边框宽度。需同时设置边框颜色才会显示边框。
`normalBorderColor`	`String`	无	普通状态边框颜色。
`highlightBorderColor`	`String`	无	按下状态边框颜色。
`normalLowerEdgeColor`	`String`	无	普通状态底部边缘颜色。
`highlightLowerEdgeColor`	`String`	无	按下状态底部边缘颜色。
`normalShadowColor`	`String`	无	普通状态阴影颜色。
`highlightShadowColor`	`String`	无	按下状态阴影颜色。
`shadowOpacity`	`Double`	系统默认	阴影透明度，取值范围 `0.0` 到 `1.0`。
`shadowRadius`	`Double`	系统默认	阴影模糊半径。
`shadowOffset`	`{ x?: Double, y?: Double }`	`{ x: 0, y: 0 }`	阴影偏移。

配置示例：

1
geometryBackground:
2
  buttonStyleType: geometry
3
  insets: { top: 6, left: 3, bottom: 6, right: 3 }
4
  normalColor:
5
    - '#9bafd9'
6
    - '#103783'
7
  highlightColor:
8
    - '#432371'
9
    - '#faae7b'
10
  colorLocation: [0, 1]
11
  colorStartPoint: { x: 0.5, y: 0 }
12
  colorEndPoint: { x: 0.5, y: 1 }
13
  colorGradientType: radial
14
  cornerRadius: 6
15
  borderSize: 3
16
  normalBorderColor: '#f5d7a1'
17
  highlightBorderColor: '#552E5A'
18
  normalLowerEdgeColor: '#f5d7a1'
19
  highlightLowerEdgeColor: '#552E5A'
20
  normalShadowColor: '#e60b09'
21
  highlightShadowColor: '#e60b09'
22
  shadowRadius: 2
23
  shadowOffset: { x: 0, y: 3 }
24
  shadowOpacity: 0.8

systemImage

通过设置 buttonStyleType: systemImage，使用 SF Symbols 图标作为样式。

参数	类型	默认值	说明
`systemImageName`	`String`	无	普通状态 SF Symbols 图标名称。
`highlightSystemImageName`	`String`	`systemImageName`	按下状态 SF Symbols 图标名称。
`contentMode`	`ContentMode`	`center`	图标显示模式。
`fontSize`	`Float 或 String`	系统默认字体大小	图标大小。
`fontWeight`	`FontWeight`	`regular`	图标粗细。
`normalColor`	`String`	无	普通状态图标颜色。
`highlightColor`	`String`	`normalColor`	按下状态图标颜色。

配置示例：

1
backspaceIcon:
2
  buttonStyleType: systemImage
3
  systemImageName: delete.left
4
  highlightSystemImageName: delete.left.fill
5
  fontSize: 20
6
  fontWeight: semibold
7
  normalColor: '#333333'
8
  highlightColor: '#000000'

assetImage

通过设置 buttonStyleType: assetImage，使用 App 内置资源图片作为样式。

参数	类型	默认值	说明
`assetImageName`	`String`	无	App 内置资源图片名称。
`contentMode`	`ContentMode`	`center`	图片显示模式。
`normalColor`	`String`	无	普通状态图片着色。
`highlightColor`	`String`	`normalColor`	按下状态图片着色。

fileImage

通过设置 buttonStyleType: fileImage，使用皮肤包中的图片文件作为样式。

参数	类型	默认值	说明
`normalImage`	`ImageRef`	无	普通状态图片。
`highlightImage`	`ImageRef`	`normalImage`	按下状态图片。
`contentMode`	`ContentMode`	`scaleToFill`	图片显示模式。

ImageRef 支持以下字段：

参数	类型	说明
`file`	`String 或 String[]`	图片文件名称。引用 `resources` 中的图片描述文件名（不含 `.yaml` 后缀）或图片文件。
`image`	`String`	图片描述文件中的子图片名称。

示例：

1
keyBackground:
2
  buttonStyleType: fileImage
3
  normalImage:
4
    file: anjian
5
    image: image1
6
  highlightImage:
7
    file: anjian
8
    image: image2

随机图片示例：

1
randomDecoration:
2
  buttonStyleType: fileImage
3
  enableRandomImage: true
4
  normalImage:
5
    file:
6
      - deco1
7
      - deco2
8
      - deco3

text

通过设置 buttonStyleType: text，使用文本内容作为样式。

参数	类型	默认值	说明
`text`	`String`	无	文本内容。
`fontSize`	`Float 或 String`	系统默认字体大小	文本大小。
`fontWeight`	`FontWeight`	`regular`	文本字重。
`normalColor`	`String`	无	普通状态文本颜色。
`highlightColor`	`String`	`normalColor`	按下状态文本颜色。

特殊文本内容：

$rimePreedit：Rime 预编辑文本。
$rimeCandidate：Rime 首个候选字。
$rimeCandidateComment：Rime 首个候选字 comment 信息。
$rimeSchemaName：Rime 方案名称。
$returnKeyType：返回键文本。

配置示例：

1
qText:
2
  buttonStyleType: text
3
  text: q
4
  fontSize: 18
5
  fontWeight: medium
6
  normalColor: '#333333'
7
  highlightColor: '#000000'