键盘皮肤结构

皮肤文件

皮肤文件是一个文件后缀为 cskin 的 zip 格式的压缩文件。

一个皮肤文件的结构大致如下

• demo.png
• README.md
• config.yaml
• Directoryfonts/

  • …
• Directorydark/

  • Directoryresources/

    • anjian.png
    • anjian.yaml
• Directorylight/

  • Directoryresources/

    • …

• demo.png：必须。用于向用户展示皮肤外观样式。
• README.md: 非必须，建议提供，用于向用户描述皮肤使用的教程，比如如何切换中英文等。
  • 可在应用中长按皮肤，选择「README」选项，查看该文件内容。
  • 此 md 文件不支持图片，超链接等信息，仅支持文字描述的语法内容。
  • 建议仅提供皮肤使用相关说明，不建议提供 Jsonnet 代码相关说明。
• config.yaml：必需，用来描述皮肤中包含的键盘。
• fonts：非必须，存放皮肤中使用的字体文件（注意字体版权）。
• dark：必须，用于提供暗色模式下键盘配置文件。
  • resources：非必须，用于存放图片及其图片描述文件，如果皮肤不需要图片可不提供。
    • 图片文件： 仅支持 png 格式图片文件
    • 图片文件描述文件: 用来描述一张图片中的子内容，比如从当前图片的某个像素开始，宽多少，高多少是一个子图片
• light：必须，用于提供浅色模式下键盘配置文件及图片资源文件。
  • resources：非必须：与 dark/resources 定义相同

cskin 文件

在安装元书应用后，在 iOS 端你可以使用元书打开这个文件，或者分享这个文件给元书，元书会自动导入皮肤文件。

config.yaml

config.yaml 文件是一款皮肤的基础配置文件，此文件用来描述皮肤中包含了哪些键盘， 并描述了在不同情况下（如横屏，纵屏）、不同设备下（如 iPhone，iPad）使用那些具体的配置文件。

键盘类型分为几种：

• pinyin: 表示中文键盘
• alphabetic: 表示英文键盘
• numeric: 数字键盘
• symbolic: 符号键盘
• 自定义键盘

配置示例：

pinyin:
  iPad:
    floating: "pinyinPortrait"
    landscape: "iPadPinyinLandscape"
    portrait: "iPadPinyinPortrait"
  iPhone:
    landscape: "pinyinLandscape"
    portrait: "pinyinPortrait"

在上面示例中，如果当前设备为 iOS 并处于纵屏模式下：

• 当设备为浅色模式时，使用 light/pinyinPortrait.yaml的内容，
• 反之，使用 dark/pinyinPortrait.yaml 的内容。

在一款皮肤中，拼音键盘是必须提供的，其余键盘是可选的：

• 当不提供 numeric 时，系统会使用皮肤目录下内置 numeric 数字键盘。
• 当不提供 symbolic 时，系统会使用元书内置的符号键盘。
  • 注意：内置符号键盘是有程序生成的，不是配置文件定义的。

如果皮肤没有提供某种设备下、某种情况下的键盘文件，则键盘会显示空白内容。

举例：如上面示中中，假设没有提供 iPhone/landscape 配置，那么在 iPhone 横屏时，键盘会变为空白。

除了上面的键盘类型外，config.yaml还有以下属性：

属性	类型	说明
name	字符串	非必须：皮肤名称，为空时使用文件夹名称作为皮肤名
author	字符串	非必须：作者
fontFace	对象	非必须，皮肤应用的字体，参见fontFace

fontFace

重要：

• 字重属性 fontWeight 会影响字体的设置
• 如果设置了字重，则需使用与字重匹配的字体文件

注意

两种情况：

1. 使用应用中的字体设置功能，一次设置，全部键盘生效；
2. 当在 config.yaml 中设置了字体后，则使用当前 config.yaml 中的字体，无论应用中是否设置了字体；

字体设置，数组类型，其中数组中的每个元素为一个字体类型。字体按数组顺序设置优先级别。

每个字体包含以下属性：

属性	类型	说明
url	字符串	fonts 目录下的字体文件名称（需要包含文件后缀）
name	字符串	系统内置字体名称。当 name 与 url 同时存在，已 name 优先。
ranges	数组类型，非必须	字体 Unicode 生效范围，可以为一个字体设置多个范围，参见ranges。

ranges

某个字体的 Unicode 生效范围。它包含以下属性：

属性	类型	说明
location	整数，必须	字符 unicode 值
length	整数，必须	范围长度

location + length 为一个字体 Unicode 的生效区间。

注意：字重属性（fontWeight）设置会影响到字体的优先级及 ranges 生效范围。

字体配置示例

fontFace:
  - url: FLjiangdouti-Regular-2.ttf
    ranges:
    - location: 65
      length: 26

皮肤图片及其描述文件

皮肤中的图片使用拼合图片，即将用到的多个图片拼合为一张大的图片。

「图片描述文件」是用来说明拼合图片中包含的小图的位置、大小及「保护区域」信息。

保护区域

「保护区域」指图片放大后不可拉伸区域。

图片描述文件有两个要求：

1. 文件内容使用 YAML 语言描述；
2. 文件名称需与「图片名」保持一致。（「图片名」不包含文件后缀）。

举例，假设有一张 beijing.png 的图片，它包含了两张小图片。它的图片描述文件为 beijing.yaml 其内容如下：

IMG1:
  rect:
    x: 0
    y: 0
    width: 110
    height: 120
  insets:
    top: 50
    bottom: 50
    left: 35
    right: 35
IMG2:
  rect:
    x: 0
    y: 150
    width: 110
    height: 120
  insets:
    top: 50
    bottom: 50
    left: 35
    right: 35

上面内容中分别描述了名为 IMG1 与 IMG2 两张小图片，图片属性如下：

• rect 表示图片的位置及大小信息，参见rect。
• insets 表示图片中不可被拉伸的区域，它使用 top，bottom，left，right 四个方向描述，在这个区域外的图片内容是不可以被拉伸。参见insets。\n如示例中的 IMG1，它的顶部（top），有 50 个像素是不可以被拉伸的。

rect

使用二维坐标（已图片左上角为原点，x 轴向右增长，y 轴向下增长）说明一个元素的尺寸及位置，对象类型。属性如下：

属性	类型	说明
x	浮点	x 轴坐标
y	浮点	y 轴坐标
width	浮点	宽度，如果用于描述图片，则单位为像素。
height	浮点	高度，如果用于描述图片，则单位为像素。

此二维坐标系左上角为原点，x 轴向右增长，y 轴向下增长。

insets

用来设置一个距离边框的范围。属性如下：

属性	类型	说明
top	浮点	距离顶部边框的距离，默认为0。
bottom	浮点	距离底部边框的距离，默认为0。
left	浮点	距离左侧边框的距离，默认为0。
right	浮点	距离右侧边框的距离，默认为0。