跳到主要内容

使用指南

本指南将向你展示如何使用转换器将 FCL 控件配置迁移到 ZL2。

转换流程​

1. 准备 FCL 配置​

在 FCL 启动器中导出或直接打开你的控件配置文件（通常是一个 JSON 文件）。复制其全部内容。

2. 粘贴并转换​

  1. 打开转换器网页。
  2. 将复制的内容粘贴到左侧的 FCL 输入区。
  3. 点击页面中间或下方的 "开始转换" 按钮。

3. 获取结果​

  1. 转换完成后，右侧的 ZL2 输出区 将显示转换后的 JSON。
  2. 你可以点击 "复制到剪贴板" 直接使用，或点击 "下载文件" 保存。

核心转换规则 (v1.0.4 更新)​

坐标与尺寸安全​

  • 比例换算: FCL (0-1000) 自动转换为 ZL2 (0-10000)。
  • 坐标钳制: 所有坐标强制限制在 0-10000 范围内，防止因负值导致 ZL2 渲染异常。
  • 最小限制:
    • 百分比尺寸最小值: 500 (5%)
    • DP 尺寸最小值: 5dp
    • 注：若原始尺寸过小，将自动提升至上述极限值以确保控件可见。

样式限制​

为确保配置文件符合 ZL2 官方规范，转换器会自动应用以下限制：

  • 文字大小: 2 - 30
  • 边框宽度: 0 - 50
  • 透明度: 0.0 - 1.0

交互逻辑​

  • 滑动联动 (Swipple): 转换后的方向键默认开启 isSwipple，允许在多个按钮间滑动触发，模拟摇杆手感。
  • 深度检测 (Deep Touch): 精确映射 FCL 的 pointerFollow 属性至 ZL2 的 isPenetrable，确保触摸事件按 z-index 正确分发。
  • 开关模式: FCL 的 autoKeep 属性将映射为 ZL2 的 isToggleable。

方向键处理​

ZL2 不直接支持 FCL 式的一体化方向键。转换器会将其拆解为 8 个按钮（上、下、左、右、以及四个斜向键），布局如下：

◤  ▲  ◥
◀  ○  ▶
◣  ▼  ◢

颜色值安全机制​

为了防止 ZL2 导入非标准颜色值导致崩溃，转换器默认使用以下安全颜色：

  • 背景: 半透明黑色
  • 边框/文字: 白色/灰色

反向转换 (ZL2 → FCL) 健壮性优化​

在 v1.0.5 版本中，我们大幅增强了反向转换器的稳定性：

  • 空值防御: 自动处理 ZL2 配置中缺失的 layers、styles 或 clickEvents 字段，不再因不完整的配置文件而崩溃。
  • 样式自动补全: 如果 ZL2 按钮引用了不存在的样式 UUID，转换器将自动为其生成“默认样式”以确保 FCL 能够正常加载。
  • 事件安全解析: 能够安全忽略 ZL2 中未定义的自定义事件类型，保证核心按键功能的迁移。

常见问题​

  • Q: 粘贴后提示 "JSON 格式错误"？
    • A: 请确保你粘贴的是完整的 JSON 内容，且没有任何多余的字符。
  • Q: 导入 ZL2 后控件位置不对？
    • A: 转换器按比例转换。如果屏幕比例不一致，可能需要在 ZL2 编辑器中进行微调。
  • Q: 反向转换时部分样式丢失？
    • A: 转换器会尽力还原样式。如果样式在 ZL2 中未定义或引用损坏，将回退至系统默认值。