关于下一代同文主题设计规范的讨论

[tumuyan]

背景
同文主题参多，功能复杂，支持的书写方式繁多，部分参数命名混乱，并且无配套GUI工具。制作和调试需要消耗大量时间。最终成品良莠不齐，结构复杂，可维护性低。

目的
讨论并制定下一代同文主题的设计规范

行动

1. 增加一系列新的主题读取方法对应下一代同文主题，同时对原有读取主题的方法也进行重构，旧方法添加deprecated标记，新主题中增加trime_version参数。当trime_version参数与同文版本一致时，使用新方法，否则弹出消息并使用旧方法；新方法完全不对旧方法做兼容。
2. 与目前比较有影响力的主题作者联络，尽量让主题上github，以协作的方式保障这些主题适用于下一代同文。
3. 在同文4.0时完全去除旧方法
4. 内置键盘配列设计工具，预设按键样式设计工具，以及配色调试工具。

正文

1. 调整第一级主要参数列表做如下调整：
   原主题：

• style
• fallback_colors
• preset_color_schemes
• liquid_keyboard
• preset_keyboards
• android_keys
• preset_keys

新主题：

• style
• fallback_colors
• preset_color_schemes
• fallback_style #增加按键外观预设组合的fallback表
• preset_key_style #增加按键外观预设组合
• liquid_keyboard
• preset_keyboards #需要移除颜色相关的全部参数，增加class参数
• android_keys #android预设key可以作为制作主题的参考资料，没有必要进行预设
• preset_keys #需要移除颜色相关的全部参数

2. 彻底拆分主题按键样式（preset_key_style）和键盘配列（preset_keyboards）。用分开的工具分别对他们做调整。
3. 配列（不是按键preset_key，preset_key只包含按键功能方面的值）包含clss属性。preset_key_style里如果包含preset_key的名称，则使用对应预设样式，否则读取class，class对应的样式也没有就读取默认按键样式。
4. 由于yaml不能像css一样，多个选择器共用一套样式。为了减少重复读取参数的次数，增加 fallback_style小节。特别的，针对按键样式，会自动把按压状态按原状态前加前缀来取值。如果没有，或者缺少部分内容，自动读原状态的值而无需fallback
5. preset_key_style是预设按键样式的map，其中default必须包含全部属性，其他样式可以简写属性，缺少的属性套用default。全部属性包含背景色，文字颜色，符号颜色，hint颜色，不包含尺寸
6. class优先使用预设class名称（待补充）
7. 移除原有的function属性和shift的样式属性，改为class。目前shift键状态太多，需要削减为默认、按下2个状态，锁定时使用和按下完全相同的外观。候选栏中的选项、悬浮窗、点击按键弹出字符也抽象地看作具有特殊class的按键。
8. 全部配色资源都在preset_color中，其他节点只使用预设名称。也就是说，读取顺序 view ⇨ preset_key_style ⇨ fallback_style ⇨ preset_color
9. 除透明外，其他配色和图片都不出现在preset_color以外的地方（这不止利于后续皮肤更新，在加载皮肤时也有更高的效率）
10. preset_color使用位置和功能的命名方式，而不是使用颜色、图像内容。原有的通过patch按键颜色的方式，改为patch class
11. 纯色>.9图>png/jpg
12. 主题如有图片资源，必须指定资源所在目录
13. 推荐使用liquidKeyboard代替符号键盘

[wwzrh]

这个我不懂，听你的！😅
另外开发一个候选面板，对于拼音用户很需要。

[tumuyan]

1. 针对有冲突的参数，进行合并，或者添加验校功能。两个方式都有不小的工作量。
   比如按键的repeatable和long_click有冲突，把repeatable作为long_click的参数，取消repeatable。
2. 针对按键的action，进行重新调整和规划。复杂功能尽量合并到command类型中去。在主题中，原则上使用command，而不是预设组合键（例如用paste命令代替Ctrl+v）。组合键类型由难以理解的text改为更直观的macro
3. 目前按键的action中，send和text定位混乱，在功能上text完全可以取代send，只是多写了一个{}。因此令send支持{}，取消text
4. 增加任意按键的锁定属性，即保持按下状态。这个功能比较复杂，涉及了其他按键点击后是否是否复位的问题。

[tumuyan]

一个和主题文件本身关西不大，但是在重构keyboard过程中会涉及的问题：
目前修饰键（shift/ctrl/alt/sys/meta）的状态是单独保存在每个键盘里的，是不是应该改为无关？如果改为无关，可以一定程度降低耦合程度，并且不必在多个键盘上分别放修饰键

[tumuyan]

另外，目前同文实际上没有处理大写锁定（caplock），只是模拟了shift长按的动作。在输入符号及空格选字的场景下，和pc有差别

[tumuyan]

是否应该删除send_bindings？似乎没有什么用

{click: '.', long_click: '>', has_menu: '次选', send_bindings: false}	单击输出.，长按输出>，打字出现候选时按键标签变为「次选」。⚠ send_bindings用来控制composing、has_menu、paging时是否发送按键给后台（true：发送；false：不发送，仅改变按键标签，按键的实际功能仍是click）。send_bindings默认为true，可以省略不写。

[WhiredPlanck]

主题规范的设计十分宏大，确实不是能“一口吃成胖子的”。我在 #774 提到了主题等配置文件解析重构的需要，当前也确实有必要。我们可以整理出一个路线图，一步步实现，不用着急。

[ameaninglessname]

或许我应该提一个issue，我想说一下现有的主题功能的一些体验上的问题：

我觉得我们需要一个方便的 主题预览和选取的功能。

rime现在自带的主题的配色命名太抽象了，

我在使用“同文风”主题时，（为了使用剪贴板和草稿箱），
没有提供按钮可以直接选择主题配色，（我也觉得在键盘上加一个这样的按钮不太合适，一般配色不会常换，（默认配色感觉没几个好看的😂）），因为目前想直接预览，这种方式是比较直接的。我在其它主题上体验过

对于配色的名字“丹青， steam” 其实就是换个颜色，但是光看名字，想象中的颜色和实际出入比较大，
而且对于一个喜欢的配色，，记住它的名字也有点难，
同文风主题的配色有好多颜色类似，但是名字不一样的...

个人现在的理想中的主题设置方式：
在设置里选取 主题 + 配色的搭配后，
可以有一个界面，预览搭配的结果，

最好是实时的，可以想象，一些输入法的 主题商店的感觉。

[InfinityLoop1308]

或许我应该提一个issue，我想说一下现有的主题功能的一些体验上的问题：

我觉得我们需要一个方便的 主题预览和选取的功能。

rime现在自带的主题的配色命名太抽象了，

我在使用“同文风”主题时，（为了使用剪贴板和草稿箱）， 没有提供按钮可以直接选择主题配色，（我也觉得在键盘上加一个这样的按钮不太合适，一般配色不会常换，（默认配色感觉没几个好看的joy）），因为目前想直接预览，这种方式是比较直接的。我在其它主题上体验过

对于配色的名字“丹青， steam” 其实就是换个颜色，但是光看名字，想象中的颜色和实际出入比较大， 而且对于一个喜欢的配色，，记住它的名字也有点难， 同文风主题的配色有好多颜色类似，但是名字不一样的...

个人现在的理想中的主题设置方式： 在设置里选取 主题 + 配色的搭配后， 可以有一个界面，预览搭配的结果，

最好是实时的，可以想象，一些输入法的 主题商店的感觉。

I think the Color_switch is good enough for your case?

[tumuyan]

3. 目前按键的action中，send和text定位混乱，在功能上text完全可以取代send，只是多写了一个{}。因此令send支持{}，取消text

#799 增加了另一种写法，绕过librime来直接commit文字，本质上和 swipe_down: {commit: "- [x] "} CHS_DOT1: {label: "、", commit: "、"} 一样是直接commit，但是区别在于解析了%n$s，是其他方式所不具备的。
但是从分类以及代码简洁的角度讲，这是合适的——command类型的presetkeys有option参数，只有option参数允许%n$s，而解析option参数存在一些开销。所以%n$s类型的commit的command的是有必要的，不应合并到commit参数或者text参数中

[chwt163]

1、候选栏的功能键，能不能把多个功能集成到一个按键里面？有些功能不放在那里，要用的时候不方便，平时占用一个位置又显得鸡肋。这个似乎不属于主题范畴？能不能在主题里面也可以定义候选栏功能键？
2、建议 key_symbol 符号键可以设定 ascii 参数，现在好像只有 key 键可以指定 ascii？
3、默认同文风主题的表情键盘，在切换ascii时，上下页按键的lable有点小问题，这是因为lable 只在 “ascii_mode: 1”时生效，改为全时生效或者添加参数来定义，会不会更好？

[lovelock]

确实有必要，网上找的主题一应用程序就崩溃

[Freed-Wu]

如果要验证一个 XXX.trime.yaml 的 正确性的话， 我觉得 json schema 可能会有帮助

https://python-jsonschema.readthedocs.io/en/stable/
https://www.schemastore.org/json/

只需编写一个 json schema 文件，然后就可以用来验证一个 json、yaml、toml 是否正确。

[WhiredPlanck]

如果要验证一个 XXX.trime.yaml 的 正确性的话， 我觉得 json schema 可能会有帮助

https://python-jsonschema.readthedocs.io/en/stable/ https://www.schemastore.org/json/

只需编写一个 json schema 文件，然后就可以用来验证一个 json、yaml、toml 是否正确。

听起来很不错，但是我搞不懂怎么整 ……

[Freed-Wu]

我给一个 demo 吧： #1294

$ yaml2json app/src/main/assets/rime/tongwenfeng.trime.yaml -o /dev/shm/tongwenfeng.trime.json
$ jsonschema -opretty -i/dev/shm/tongwenfeng.trime.json doc/trime-schema.json
===[SUCCESS]===(/dev/shm/tongwenfeng.trime.json)===

1. 先把 1 个 trime.yaml 转为 json
2. 在用 json schema 验证它。

假如有错的话会是这样：

我们将 tongwenfeng.trime.yaml 改为 ：

...
style:
  auto_caps: wrong #自動句首大寫:true|false|ascii

$ jsonschema -opretty -i/dev/shm/tongwenfeng.trime.json doc/trime-schema.json
===[ValidationError]===(/dev/shm/tongwenfeng.trime.json)===

'wrong' is not one of [True, False, 'ascii']

Failed validating 'enum' in schema['properties']['style']['properties']['auto_caps']:
    {'default': False,
     'description': '自动句首大写',
     'enum': [True, False, 'ascii']}

On instance['style']['auto_caps']:
    'wrong'
-----------------------------

于是在用户加载错误的 trime.yaml 导致崩溃前可以提前注意到 auto_caps 错了。

对 trime.yaml 的开发者而言，他们也可以利用支持 LSP 的编辑器辅助开发，例如：

[WhiredPlanck]

@Freed-Wu 这个 demo 我觉得很有意思，不知道有没有更多应用案例。我想把这个检查能力移植到应用中来 ……

[Freed-Wu]

更多应用案例

我知道 tree-sitter 有用 json schema 验证一些 json 文件的正确性的。 https://github.com/tree-sitter/tree-sitter/blob/master/cli/src/generate/grammar-schema.json

不过 Android APP 的例子好像还没见到过。

[FlyingpigNZ]

有没有可能将键盘配置，配色，还有liquid keyboard分割成不同的文件。
或者在代码层来允许引用其他的yaml文件。
我在查看主题定义的时候，里面包含了表情，符号的liquid keyboard，这个部分基本上不会有太大的改动。
如果可能的话，单独出来。颜色定义如果可以的话，也可以这样。
键盘的定义，能否分组，一个键盘组包含ASCII和非ASCII两个键盘定义。切换的时候在这两个定义之间转换。
现在感觉是主题定义的灵活性太大了，很容易就让人迷惑了而且出错。

我理想中的键盘定义方式是：

1. 键盘schema定义
2. 键盘布局组，包含ASCII/非ASCII键盘layout。
3. liquid keyboard键盘定义。
4. 颜色定义组，包含light/dark主题，这样在light和dark之间切换的话也更直观一点，目前是通过颜色的attribute来控制的。
   以上四项构成一个键盘定义。
   每一组键盘定义可以通过类似的名字组合在一起，比如说
   pinyin..schema.yaml
   pinyin.trime.layout.yaml
   pinyin.trime.accessory.yaml.
   pinyin.trime.color.yaml
   这样，切换的时候其实切换的是这一组键盘定义。

如果需要修改某个键盘schema定义对应的键盘布局，可以生成对应的patch文件，比如pinyin.trime.layout.patch.yaml来override default layout定义。
liquid keyboard和颜色同理。
这样，最小化一个输入法所要包含的数据定义。
一点浅见，一起讨论一下。