按键动画

恰当的按键动画可以让键盘交互更加生动和有趣。元书输入法支持多种类型的动画效果，包括缩放、卡通和物理动画。

动画类型

缩放动画 (scale)

缩放动画是在按键被按下时产生缩小效果，释放时恢复原状。

1
scaleAnimation:
2
  animationType: scale
3
  isAutoReverse: true
4
  scale: 0.95
5
  pressDuration: 850
6
  releaseDuration: 100

isAutoReverse：是否区分按键状态自动反转动画。默认为 false。
- 当设置为 true 时，按键动画会使用 pressDuration 的时间播放缩小动画，随后使用 releaseDuration 的时间播放放大动画。动画是连贯的，由按键按下状态触发。
- 当设置为 false 时：按键按下状态使用 pressDuration 的时间播放缩小动画；按键释放状态使用 releaseDuration 的时间播放放大动画。动画是不连贯的，按键按下和释放状态分别触发。
scale：按键缩放比例，默认为 0.95，表示按下时按键缩小到原来的 95%。
pressDuration：按键按下状态时，动画持续时间，单位为毫秒。
releaseDuration：按键释放状态时，动画持续时间，单位为毫秒。

图片播放动画（cartoon）

图片播放动画通过一系列图片帧来实现动画效果，适用于需要展示复杂动画的场景。

1
cartoonAnimation:
2
  animationType: cartoon
3
  fps: 30
4
  targetScale: 0.3
5
  zPosition: 'above'
6
  images:
7
    - "frame1.png"
8
    - "frame2.png"

fps：动画播放的帧率，默认为 30 帧每秒。表示一张图片显示的时间为 1/30 秒。
targetScale：图片缩放比例，默认为 nil，即不进行缩放，建议按效果设置，图片如果不缩放，会占用较多的内存。
zPosition：图片的显示层级，默认为 above，表示图片显示在按键之上。可选值有 above（按键上方）、below（按键下方）。
images：帧图片文件名数组，按顺序列出所有用于动画的图片文件名。

物理动画 (physics)

物理动画提供对图片移动、旋转、透明度变化的效果。

1
physicsAnimation:
2
  animationType: physics
3
  duration: 600
4
  randomImage: true
5
  targetScale: 0.3
6
  images:
7
    - "01.png"
8
    - "02.png"
9
  startPosition: { x: 0, y: 0 }
10
  startRandomPosition: { x: 0, y: 0 }
11
  endPosition: { x: 0, y: -10 }
12
  endRandomPosition: { x: 100, y: 0 }
13
  # randomPosition 已删除
14
  randomPosition: { x: 0, y: 0 }
15
  useOpacity: true
16
  startOpacity: 1.0
17
  endOpacity: 0.1
18
  useRotation: true
19
  startAngle: 0
20
  endAngle: 360
21
  randomAngle: 50

duration：动画持续时间，单位为毫秒。
randomImage：是否从 images 图片列表中随机选择图片，默认为 false。
targetScale：图片缩放比例，默认为 nil，即不进行缩放，建议按效果设置，图片如果不缩放，会占用较多的内存。
images：图片文件名数组，按顺序列出所有用于动画的图片文件名。
startPosition：图片移动位置的起始点
- x: 表示起始点的横向位置，默认为当前按键横向中间点。
- y: 表示起始点的纵向位置，默认为当前按键纵向最低点。
startRandomPosition：为 startPosition 添加一个随机变量
- x: 表示为起始点的横向位置添加一个随机值，随机值在 [-x，x] 之间，即 x = startPosition.x + random(-x, x)，
- y: 表示为起始点的纵向位置添加一个随机值，随机值在 [-y，y] 之间，即 y = startPosition.y + random(-y, y)，
- 注意：需 tf >= 428，商店 >= 1.6.27
endPosition：图片移动位置的结束点
- x: 表示结束点的横向位置，默认为当前按键横向中间点。
- y: 表示结束点的纵向位置，默认为当前按键纵向最高点。
endRandomPosition: 为 endPosition 添加一个随机变量
- x: 表示为结束点的横向位置添加一个随机值，随机值在 [-x，x] 之间，即 x = startPosition.x + random(-x, x)，
- y: 表示为结束点的纵向位置添加一个随机值，随机值在 [-y，y] 之间，即 y = startPosition.y + random(-y, y)，
- 注意：需 tf >= 428，商店 >= 1.6.27
randomPosition：为动画的起始位置和结束位置添加随机偏移
- x: 横向随机偏移范围
- y: 纵向随机偏移范围
- 注意：tf >= 428，商店 >= 1.6.27 删除了这个属性，请使用 startRandomPosition，endRandomPosition 代替
useOpacity：是否启用透明度变化效果，默认为 false。
startOpacity：动画开始时图片的透明度，范围为 0.0 到 1.0，默认为 1.0。仅当 useOpacity 设置为 true 时生效。
endOpacity：动画结束时图片的透明度，范围为 0.0 到 1.0，默认为 0.8。仅当 useOpacity 设置为 true 时生效。
useRotation: 是否启用旋转效果，默认为 false。
startAngle：图片的开始角度，单位为度。
endAngle：图片的结束角度，单位为度。
randomAngle：开始角度的随机偏移范围，单位为度。

变换动画 (transform)

scale 只能整键缩小，physics 只能新建图层播放图片。若想让按键已有的某一层 （键帽、字形、角标）位移、绕指定锚点缩放或旋转，用 transform。

1
badgeFloatUp:
2
  animationType: transform
3
  target: qButtonBadgeForegroundStyle   # 只动这一层；不写则整个按键一起动
4
  trigger: press
5
  duration: 200
6
  delay: 0
7
  timing: easeOut
8
  repeatCount: 1
9
  autoreverses: false
10
  restoreOnFinish: true
11
  holdUntilRelease: false
12
  releaseDuration: 120
13
  anchorPoint: { x: 0.5, y: 1.0 }
14
  positionUnit: point
15
  startPosition: { x: 0, y: 0 }
16
  endPosition: { x: 0, y: -9 }
17
  startScale: 1.0
18
  endScale: 1.2
19
  useRotation: false
20
  startAngle: 0
21
  endAngle: 0
22
  useOpacity: true
23
  startOpacity: 1.0
24
  endOpacity: 0.0

target：要作用的图层，取值为该按键 backgroundStyle / foregroundStyle 里用到的样式名。不设置时作用于整个按键。样式名在当前按键中不存在时，本次动画跳过。
trigger：由哪个按键状态触发。press 按下（默认）、release 抬起、both 两者都触发。开启 holdUntilRelease 后本属性失效。
duration：动画时长，单位为毫秒，默认 200。
delay：起播延迟，单位为毫秒，默认 0。
timing：缓动曲线。可选 linear、easeIn、easeOut、easeInEaseOut（默认）、default。也可以直接写四个数，表示自定义三次贝塞尔控制点 [c1x, c1y, c2x, c2y]，例如 timing: [0.34, 1.56, 0.64, 1] 是一条带回弹的曲线。
repeatCount：播放次数，最少 1 次。
autoreverses：播完后是否反向播回起点，默认 false。开启后 duration 是单程时间，一个来回共 duration × 2，终点回到起点状态。
restoreOnFinish：播完是否恢复原状，默认 true。设为 false 时停在终点状态。
holdUntilRelease：按下播到终点后停住，抬起时再反向播回起点，默认 false。详见下方「按住保持」。
releaseDuration：holdUntilRelease 抬起回程的时长，单位为毫秒。不写则与 duration 相同。
anchorPoint：缩放与旋转围绕的锚点，单位坐标。{ x: 0.5, y: 0.5 } 为图层中心（默认）， { x: 0, y: 0 } 为左上角，{ x: 0.5, y: 1 } 为底边中点。取值可以超出 0~1，例如 { x: 0.05, y: 1.15 } 表示绕图层左下角外侧的一个点缩放，缩小时图层会朝那个方向”收”过去。该属性只决定本次变换绕哪个点发生，不会改动图层自身的 anchorPoint，因此不影响布局。
positionUnit：位移的单位。
- point（默认）：单位为点。
- layer：按目标图层自身宽 / 高的倍数取值。
- button：按整个按键宽 / 高的倍数取值。皮肤里的尺寸本来就都是相对值，位移写死点值换个机型、换个键盘高度就会偏。装饰图浮出键帽这类效果，视觉参照的是键帽，用 button；图层自己抖动、缩进这类效果用 layer。
startPosition / endPosition：位移的起止值，相对图层原位置，单位由 positionUnit 决定。y 负方向朝上。
startScale / endScale：缩放的起止倍率，默认均为 1。写标量表示等比缩放；写 { x: 0.85, y: 0.9 } 表示 x / y 分别缩放。
useRotation：是否启用旋转，默认 false。
startAngle / endAngle：旋转的起止角度，单位为度。仅当 useRotation 为 true 时生效。
useOpacity：是否启用透明度变化，默认 false。
startOpacity / endOpacity：透明度的起止值。仅当 useOpacity 为 true 时生效。
detached：是否脱离按键播放，默认 false。为 true 时把目标图层复制一份浮到键盘之上，动画挂在副本上，播完自动删除，原图层在此期间隐藏。

按下时的效果有两种完全不同的形态，别混：

脉冲（autoreverses: true）——播到终点再原路返回，duration 是单程时间，播完回到原状，按住不放也不会停在终点。大多数按压效果都是这一种：键帽缩一下弹回、装饰图弹出来再落回去。

保持（holdUntilRelease: true）——按下播到终点就停住，手指按住期间一直维持，抬起才反向播回起点。整键 scale 一直是这个行为。适合「按住期间必须一直看得出来被按着」的场合。

1
# 保持：按下缩到 85% 并停住，松手用 120ms 弹回
2
capHold:
3
  animationType: transform
4
  target: mButtonBackgroundStyle
5
  holdUntilRelease: true
6
  duration: 80
7
  releaseDuration: 120
8
  endScale: 0.85

开启 holdUntilRelease 后 trigger、detached、autoreverses 均不再生效。

按键抬起时，图层会按抬起状态重绘——只写了 highlightImage 的图层内容会被清空。于是「按下弹出一个小东西、飘一下再收回」这种动画，手指一松就断了，只播了个开头。

detached: true 让动画在按键之外的副本上跑完，不受按下 / 抬起状态影响，也不会被按键自身的 scale 动画连带缩放。仅对有图片内容的图层有效（fileImage / assetImage），其他情况会自动退回不脱离。

连击时：同一按键的同一条动画只会有一份副本。上一次还没播完就又按下，副本会被从头重放（硬切回起点），而不是再叠一份出来。连打速度快于 duration 时，动画每次都放不完，观感就是持续停在前半程—— 这与原生输入法的表现一致。

常见用法

1
# 1. 绕底边缩放，模拟按键被"压下去"
2
pressDown:
3
  animationType: transform
4
  duration: 80
5
  anchorPoint: { x: 0.5, y: 1.0 }
6
  startScale: 1.0
7
  endScale: 0.9
8
  autoreverses: true
9

10
# 2. 只让字形轻微下沉，键帽不动
11
glyphSink:
12
  animationType: transform
13
  target: qButtonForegroundStyle
14
  duration: 60
15
  endPosition: { x: 0, y: 2 }
16
  autoreverses: true
17

18
# 3. 抬起时角标闪一下
19
badgeBlink:
20
  animationType: transform
21
  target: qButtonBadgeForegroundStyle
22
  trigger: release
23
  duration: 150
24
  useOpacity: true
25
  startOpacity: 0.2
26
  endOpacity: 1.0

分层按压：一个按键挂多条 transform

商业皮肤里「按一下键」往往不是整键缩一下，而是键帽、字形、角标、装饰图各自绕不同的锚点做不同的动作。做法是给同一个按键挂多条 transform，每条用 target 指向自己那一层。

下面这组还原的是一类常见效果：键帽整体缩小，字形绕偏上的点收缩，角标朝左下角收，同时一个只在按下时出现的装饰图往上浮并放大。

四条都是一个来回的脉冲——autoreverses: true 让动画播到终点后原路返回， duration 是单程时间，所以键帽那条总共 160ms。按住不放也不会停在终点，播完就回到原状；装饰图则一直留在键上，直到抬起才消失。

1
mButton:
2
  backgroundStyle: mButtonBackgroundStyle
3
  foregroundStyle:
4
    - mButtonForegroundStyle       # 字形 m
5
    - mButtonUpForegroundStyle     # 角标 ？
6
    - keyDecorationStyle           # 只写了 highlightImage 的装饰图
7
  animation:
8
    - capPress
9
    - glyphPress
10
    - badgePress
11
    - decorationPop
12

13
# 键帽：绕中心缩到 85% 再弹回，单程 80ms
14
capPress:
15
  animationType: transform
16
  target: mButtonBackgroundStyle
17
  duration: 80
18
  autoreverses: true
19
  endScale: 0.85
20

21
# 字形：绕偏上的点缩到 85% 再弹回
22
glyphPress:
23
  animationType: transform
24
  target: mButtonForegroundStyle
25
  duration: 80
26
  autoreverses: true
27
  anchorPoint: { x: 0.5, y: 0.4 }
28
  endScale: 0.85
29

30
# 角标：绕左下角外侧的点收缩再弹回
31
badgePress:
32
  animationType: transform
33
  target: mButtonUpForegroundStyle
34
  duration: 80
35
  autoreverses: true
36
  anchorPoint: { x: 0.05, y: 1.15 }
37
  endScale: 0.85
38

39
# 装饰图：上浮键高的 16% 并放大到 120%，再原路回到原位原大小，单程 200ms 线性
40
decorationPop:
41
  animationType: transform
42
  target: keyDecorationStyle
43
  duration: 200
44
  timing: linear
45
  autoreverses: true
46
  positionUnit: button
47
  endPosition: { x: 0, y: -0.16 }
48
  endScale: 1.2

这里几个属性各自解决一个问题： target 让四条动画互不干扰；anchorPoint 决定每层往哪个方向收； autoreverses 让效果播一个来回后回到原状； positionUnit: button 让上浮距离随键盘尺寸缩放，而不是写死点值。

装饰图那一层通常只配 highlightImage，按下才出现、抬起即消失，它的「留在键上」靠的是按键的高亮状态，不是动画停在终点—— 所以这类效果不要用 holdUntilRelease，否则会停在放大后的样子不回来。

动画的设置

animation: 类型: [String], 用于设置当前按键的动画效果，可以配置多个动画，当按键按下时同时播放。

注意：animation 属性只能配置在按键的属性配置中有效。

配置示例

1
qButton:
2
  size:
3
    width: 112.5/1125
4
  backgroundStyle: alphabeticBackgroundStyle
5
  foregroundStyle:
6
    - qButtonForegroundStyle
7
    - qButtonUpForegroundStyle
8
  uppercasedStateForegroundStyle:
9
    - qButtonUppercasedStateForegroundStyle
10
    - qButtonUpForegroundStyle
11
  ...
12
  animation:
13
    - scaleAnimation
14
    - cartoonAnimation
15
    - physicsAnimation
16

17
scaleAnimation:
18
  animationType: scale
19
  ...
20

21
cartoonAnimation:
22
  animationType: cartoon
23
  ...
24

25
physicsAnimation:
26
  animationType: physics
27
  ...

在上面的例子中，按键 qButton 配置了三种动画效果：缩放动画、图片播放动画和物理动画。当用户按下该按键时，这些动画将同时播放，增强用户的交互体验。