跳至主要內容

入门介绍

2023/10/27约 1656 字大约 6 分钟老猫

ui 模块提供了编写用户界面的支持。在 v9 中，UI 模块基于 Node.js 引擎，使用 Activity 类来创建和管理界面。

提示

给 Android 开发者或者高阶用户的提醒，Auto.js 的 UI 系统来自于 Android，所有属性和方法都能在 Android 源码中找到。如果某些代码或属性没有出现在 Auto.js 的文档中，可以参考 Android 的文档。

启用 Node.js 引擎

在 v9 中，使用 UI 模块的脚本必须在文件开头使用 "nodejs"; 或 "ui nodejs"; 来启用 Node.js 引擎。正确示范：

"nodejs";

// 脚本的其他代码

或者如果同时需要 UI 和 Node.js：

"ui nodejs";

// 脚本的其他代码

字符串 "nodejs" 的前面可以有注释、空行和空格，但是不能有其他代码。

基本概念

界面是由视图(View)组成的。View 分成两种，控件(Widget)和布局(Layout)。控件(Widget)用来具体显示文字、图片、网页等，比如文本控件(text)用来显示文字，按钮控件(button)则可以显示一个按钮并提供点击效果，图片控件(img)则用来显示来自网络或者文件的图片，除此之外还有输入框控件(input)、进度条控件(progressbar)、单选复选框控件(checkbox)等；布局(Layout)则是装着一个或多个控件的"容器"，用于控制在他里面的控件的位置，比如垂直布局(vertical)会把他里面的控件从上往下依次显示(即纵向排列)，水平布局(horizontal)则会把他里面的控件从左往右依次显示(即横向排列)，以及帧布局(frame)，他会把他里面的控件直接在左上角显示，如果有多个控件，后面的控件会重叠在前面的控件上。

使用 Activity 创建界面

在 v9 中，我们使用 Activity 类来创建界面。首先需要导入 ui/activity 模块，然后创建一个继承自 Activity 的类，并通过 layoutXml getter 返回 XML 布局字符串。最后使用 setMainActivity() 函数设置主 Activity。

基本示例

"nodejs";
const { Activity, setMainActivity } = require("ui/activity");

class MainActivity extends Activity {
  get layoutXml() {
    return `
      <vertical>
        <button text="第一个按钮"/>
        <button text="第二个按钮"/>
      </vertical>
    `;
  }
}

setMainActivity(MainActivity);

在这个例子中：

  1. 第 1 行使用 "nodejs"; 启用 Node.js 引擎
  2. 第 2 行导入 ui/activity 模块，解构出 Activity 类和 setMainActivity 函数
  3. 第 4-11 行定义了一个 MainActivity 类，继承自 Activity
  4. 第 5-10 行的 get layoutXml() 方法返回 XML 布局字符串，指定了界面的具体内容
  5. 第 6 行的标签 <vertical> ... </vertical> 表示垂直布局，布局的标签通常以 <...> 开始，以 </...> 结束
  6. 第 7-8 行是两个按钮控件(button)，控件的标签通常以 <... 开始，以 /> 结束，他们之间是控件的具体属性
  7. 第 7 行的 text="第一个按钮" 部分就是按钮控件的属性，这个属性指定了这个按钮控件的文本内容(text)为"第一个按钮"
  8. 第 13 行使用 setMainActivity() 设置主 Activity，这样应用启动时会自动创建并显示这个 Activity

这两个控件在垂直布局中，因此会纵向排列。

水平布局示例

如果我们把这个例子的垂直布局(vertical)改成水平布局(horizontal)：

"nodejs";
const { Activity, setMainActivity } = require("ui/activity");

class MainActivity extends Activity {
  get layoutXml() {
    return `
      <horizontal>
        <button text="第一个按钮"/>
        <button text="第二个按钮"/>
      </horizontal>
    `;
  }
}

setMainActivity(MainActivity);

则这两个按钮会横向排列。

设置控件和布局属性

一个控件可以指定多个属性(甚至可以不指定任何属性)，用空格隔开即可；布局同样也可以指定属性，例如：

"nodejs";
const { Activity, setMainActivity } = require("ui/activity");

class MainActivity extends Activity {
  get layoutXml() {
    return `
      <vertical bg="#ff0000">
        <button text="第一个按钮" textSize="20sp"/>
        <button text="第二个按钮"/>
      </vertical>
    `;
  }
}

setMainActivity(MainActivity);

第三行 bg="#ff0000" 指定了垂直布局的背景色(bg)为"#ff0000"，这是一个 RGB 颜色，表示红色(有关 RGB 的相关知识参见RGB颜色对照表)。第四行的 textSize="20sp" 则指定了按钮控件的字体大小(textSize)为"20sp"，sp 是一个字体单位，暂时不用深入理会。

使用 setContentView 方法

除了使用 layoutXml getter，你也可以在 onCreate() 方法中使用 setContentView() 方法来设置布局：

"nodejs";
const { Activity, setMainActivity, MATCH_PARENT, WRAP_CONTENT } = require("ui");

class MainActivity extends Activity {
  onCreate() {
    super.onCreate();
    
    this.setContentView({
      type: "vertical",
      bg: "#ffffff",
      children: [
        {
          type: "text",
          text: "Hello Auto.js Pro",
          textSize: "20sp",
          width: MATCH_PARENT,
          height: WRAP_CONTENT
        },
        {
          type: "button",
          text: "点击我",
          width: WRAP_CONTENT,
          height: WRAP_CONTENT
        }
      ]
    });
  }
}

setMainActivity(MainActivity);

启动其他 Activity

使用 startActivity() 函数可以启动其他 Activity：

"nodejs";
const { Activity, setMainActivity, startActivity } = require("ui/activity");

class MainActivity extends Activity {
  get layoutXml() {
    return `
      <vertical>
        <button id="btnStart" text="启动第二个界面"/>
      </vertical>
    `;
  }
  
  onCreate() {
    super.onCreate();
    
    // 通过 viewId 访问视图
    const btnStart = this.contentView.findViewById("btnStart");
    btnStart.on("click", () => {
      startActivity(SecondActivity);
    });
  }
}

class SecondActivity extends Activity {
  get layoutXml() {
    return `
      <vertical>
        <text text="这是第二个界面"/>
        <button text="返回" id="btnBack"/>
      </vertical>
    `;
  }
  
  onCreate() {
    super.onCreate();
    
    const btnBack = this.contentView.findViewById("btnBack");
    btnBack.on("click", () => {
      this.finish(); // 关闭当前 Activity
    });
  }
}

setMainActivity(MainActivity);

术语说明

一个界面便由一些布局和控件组成。为了便于文档阅读，我们再说明一下以下术语：

  • 子视图, 子控件: 布局里面的控件是这个布局的子控件/子视图。实际上布局里面不仅仅只能有控件，还可以是嵌套的布局。因此用子视图(Child View)更准确一些。在上面的例子中，按钮便是垂直布局的子控件。

  • 父视图，父布局: 直接包含一个控件的布局是这个控件的父布局/父视图(Parent View)。在上面的例子中，垂直布局便是按钮的父布局。

与 v8 的区别

v9 的 UI 模块与 v8 的主要区别：

  1. 模块导入方式: v9 使用 require("ui/activity") 导入模块，而不是 v8 的全局变量
  2. 界面创建方式: v9 使用 Activity 类和 layoutXml getter，而不是 v8 的 "ui"; 模式和 ui.layout() 函数
  3. 引擎要求: v9 需要在文件开头使用 "nodejs"; 启用 Node.js 引擎
  4. 布局设置: v9 可以使用 layoutXml getter 或 setContentView() 方法设置布局

相关文档

五云学习
Copyright © 2025 老猫