跳至主要內容

UI规范文档

老猫2026/4/21大约 6 分钟

本规范用于约束与统一 Auto.js Pro v8（Rhino UI 模块）的界面编写方式，降低布局混乱、样式不一致、线程误用与性能问题。

0. 必要前提（必须遵守）

  1. UI 脚本必须以 "ui"; 开头
    • "ui"; 必须在第一行，不能有代码在它前面。
  2. 布局必须用 ui.layout(...) 包裹
  3. 所有 UI 更新必须在 UI 线程执行
    • 子线程需要更新界面时，使用 $ui.post(...) 或 $ui.run(...)。
  4. 颜色统一使用 #RRGGBB
  5. 透明度使用 alpha 范围 0 ~ 1，0 全透，1 全不透明。
    • <text id="title" text="标题" alpha="0.6"/>
    • $ui.title.setAlpha(0.6)
    • $ui.title.attr('alpha', '0.6')

1. 文件与结构约定（推荐）

  • 单文件脚本结构（从上到下固定顺序）：
    • "ui";
    • 常量区（颜色、间距、字号、字符串）
    • ui.layout(<xml>...</xml>)（或 $ui.layout(...)）布局区
    • const view = {...} 视图引用区（集中获取 ui.xxx）
    • 事件绑定区（点击、输入、滚动等）
    • 业务逻辑区（网络/IO/计算放子线程）
  • 复杂界面：优先拆为“组件/子布局”（见 3.6），避免一个超长 XML。

2. 术语与命名规范

2.1 控件 id 命名

  • 必须有意义：表达用途而不是外观。
  • 风格统一：推荐 camelCase。
  • 避免冲突：不要使用可能与 ui 现有属性冲突的名字（如 layout、post、run 等）。冲突时用 $ui.findView(id) 获取。

示例：

  • 好：titleText、submitBtn、searchInput、list、emptyView
  • 不建议：text1、button2、redBtn

2.2 事件处理函数命名

  • 推荐 onXxx / handleXxx：
    • onSubmitClick、handleSearchChange、onItemLongClick

3. XML 布局规范

3.1 基本规则

  • 布局必须清晰：优先使用 vertical / horizontal / frame / scroll 组合，减少不必要的嵌套层级。
  • 尽量声明式：优先在 XML 描述结构与静态样式；仅在确有必要时再动态 inflate/addView。
  • 属性显式化：对关键体验属性（padding、margin、textSize、textColor、bg）不要依赖默认值。

3.2 间距与尺寸（dp/sp）

  • 文字字号：使用 sp（如 14sp、16sp、20sp）。
  • 间距/尺寸：使用 dp（如 8dp、12dp、48dp）。
  • 触控目标：可点击控件的最小高度/宽度建议不小于 (48dp)。

3.3 颜色与对比度

  • 统一颜色来源：把常用颜色集中到常量区，避免散落魔法值。
  • 对比度优先：正文文字与背景需有足够对比，浅底用深字、深底用浅字。
  • 状态色一致：成功/警告/错误/禁用的颜色语义要稳定，不要同一颜色表达多个含义。

3.4 字体与排版

  • 正文：默认 14sp~16sp，行高（如果可控）保持舒适，不要挤压。
  • 标题：18sp~22sp，可配合加粗（如果控件/样式支持）。
  • 对齐：同一层级元素对齐方式保持一致，优先左对齐。

3.5 可滚动区域

  • 滚动容器只包需要滚动的内容，避免整页嵌套多层滚动。
  • 列表场景优先用 list 组件（如有），不要用大量动态创建 View 模拟长列表。

3.6 组件化与复用（推荐）

  • 可复用块建议抽为：
    • 自定义控件：$ui.registerWidget(name, widget)
    • 子布局：使用 $ui.inflate(xml, parent, attachToParent) 注入到容器
  • 复用时保持：
    • 输入/输出清晰（属性/回调）
    • 不依赖外部全局变量（或明确依赖）

4. JavaScript/线程规范

4.1 UI 线程原则

  • 禁止在 UI 线程执行：
    • 网络请求
    • 文件 IO
    • 大量循环/计算
    • 批量创建/更新大量 View
  • 子线程完成后，通过 $ui.post(() => { ... }) 回到 UI 线程更新界面。

4.2 更新 UI 的推荐方式

  • 简单异步更新：$ui.post(callback[, delay])
  • 需要拿到返回值且允许阻塞当前线程：$ui.run(callback)

5. 交互规范（必须有一致性）

5.1 点击与反馈

  • 点击必须有反馈（系统点击态/涟漪、文本变化、loading 等其一）。
  • 提交类按钮在请求中应进入 loading/disabled，避免重复提交。

5.2 输入与校验

  • 输入框应提供：
    • 合理的提示文案（placeholder/hint）
    • 必要的格式限制与实时校验（如手机号/验证码长度）
    • 错误提示靠近输入框，文案明确可执行

5.3 空态 / 错误态 / 加载态（必备三态）

每个“列表/内容区”至少考虑：

  • 加载态：首屏加载中
  • 空态：无数据/无权限/条件筛选无结果
  • 错误态：网络失败/接口错误/解析错误（提供重试入口）

6. 可访问性（A11y）与可用性

  • 文字可读：避免低对比度与过小字号。
  • 可点击区域足够大：小图标需加 padding 扩大触控区域。
  • 信息不只靠颜色：错误提示除红色外应有文案/图标。

7. 性能与稳定性红线

  • 不要用 for 循环动态 inflate 上百个 View 组成列表；用列表组件或分页渲染。
  • 避免频繁全量刷新：仅更新变化的控件（如只改 text、visibility）。
  • 图片：
    • 网络图要考虑缓存与失败占位（如适用）
    • 必要时使用 $ui.imageCache.clearMemory() / $ui.imageCache.clearDiskCache()（注意其线程行为）

8. XML 中使用变量（重要）

在 ui.layout(<xml>...</xml>) 的 XML 里可以嵌入 JavaScript 表达式，用于复用常量或条件渲染（以实际运行环境支持为准）。建议遵守：

  • 变量来自“常量区”：如 COLORS、SIZES，避免到处随意声明。
  • 表达式保持简单：不要在 XML 里写复杂逻辑，复杂逻辑放到布局之后用 JS 更新属性。

示例（仅示意）：

"ui";

const COLORS = {
  bg: "#FFFFFF",
  primary: "#009688",
  text: "#222222",
};

$ui.layout(
  <vertical bg="{{COLORS.bg}}" padding="16dp">
    <text
      id="titleText"
      text="示例标题"
      textColor="{{COLORS.text}}"
      textSize="20sp"
    />
    <button
      id="submitBtn"
      text="提交"
      style="Widget.AppCompat.Button.Colored"
    />
  </vertical>,
);

9. 推荐模板（可直接复用）

"ui";

const COLORS = {
  bg: "#FFFFFF",
  text: "#222222",
  subText: "#666666",
  primary: "#009688",
  danger: "#E53935",
};

$ui.layout(
  <vertical bg="{{COLORS.bg}}" padding="16dp">
    <text
      id="titleText"
      text="页面标题"
      textSize="20sp"
      textColor="{{COLORS.text}}"
    />

    <input id="searchInput" hint="请输入关键字" marginTop="12dp" />

    <button id="submitBtn" text="搜索" marginTop="12dp" />

    <text
      id="statusText"
      text="就绪"
      marginTop="12dp"
      textSize="14sp"
      textColor="{{COLORS.subText}}"
    />
  </vertical>,
);

ui.submitBtn.on("click", () => {
  ui.statusText.attr("text", "加载中…");
  ui.submitBtn.attr("enabled", false);

  // 模拟耗时任务：真实项目把网络/IO/计算放子线程
  // 开启子线程
  threads.start(() => {
    // 模拟耗时操作
    java.lang.Thread.sleep(2500);

    // 更新UI必须用 ui.post
    ui.post(() => {
      ui.statusText.setText("耗时任务执行完毕 ✅");
      ui.submitBtn.attr("enabled", true);
    });
  });
});

10. 发布前检查清单（建议逐项过）

  • 模式：脚本第一行是 "ui";，且之前无任何代码
  • 线程：所有 UI 更新都在 UI 线程（子线程通过 $ui.post/$ui.run 回来）
  • 三态：主要内容区有加载/空/错误态
  • 适配：不同屏幕尺寸下不遮挡、不溢出、可滚动区域正确
  • 可用性：主要按钮触控面积 (\ge 48dp)，无重复提交
  • 一致性：颜色、字号、间距不乱；命名清晰无冲突
Copyright © 2026 老猫