Apache Royale 0.9.12 常用工具与 API 详解

Apache Royale 0.9.12 常用工具与 API 详解：mxmlc/asjsc/asnodec 等编译工具、Maven 插件目标、MXML 组件 API 速查、框架 SWC 清单，含运行示例与 FAQ，全程实测。

Apache RoyaleApache Royale2026/10/13

Apache Royale 0.9.12 常用工具与 API 详解

目标：详解 Apache Royale 0.9.12 的常用工具与核心 API。工具集中在 SDK 的 js/bin/ 编译脚本与 Maven 插件目标；API 以 MXML 组件（js 命名空间）为核心。本文给出工具用途、命令示例、MXML 核心组件速查、框架 SWC 清单与 Node 端运行示例，所有示例在 Ubuntu 22.04.5 + JDK 11 环境实测。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • Java：OpenJDK 11.0.32.1
  • Royale 版本：0.9.12（SDK 位于 /opt/royale/apache-royale-0.9.12-bin-js）
  • 编译工具目录：royale-asjs/js/bin/
  • 示例工程：/root/royale-hello/、/root/royale-node-hello/

二、工具概览

Royale 以「SDK + 编译器」形态提供，工具分两类：SDK 自带编译脚本（Java 进程）与 Maven 插件目标。

工具/类别位置用途
mxmlcjs/bin/mxmlcMXML/ActionScript → JavaScript（浏览器目标，实测默认输出 bin/js-release 与 js-debug）
asjscjs/bin/asjsc纯 ActionScript → JavaScript Core
asnodecjs/bin/asnodec纯 ActionScript → Node.js 模块（等价 mxmlc + -js-output-type=node + +configname=node）
compcjs/bin/compc组件库/框架 SWC 编译
externcjs/bin/externcexterns 类型定义生成
Maven 插件royale-maven-pluginmvn package 一站式编译、信任、打包 JS 应用

三、前置条件

已按《Ubuntu 22.04 安装 Apache Royale 0.9.12 指南》安装 SDK 并配置环境：

export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
export PATH=$ROYALE_HOME/js/bin:$PATH

验证工具版本：

$ROYALE_HOME/js/bin/mxmlc --help

实测回显：

Apache Royale MXML and ActionScript Compiler (mxmlc)
Version 0.9.12 build 0
MXMLJSC
+royalelib=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/frameworks
-sdk-js-lib=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/frameworks/js/Royale/generated-sources

四、编译工具详解

4.1 mxmlc（MXML/ActionScript → JavaScript）

编译 MXML 应用（含 UI 组件）为浏览器 JavaScript：

cd /root/royale-hello
$ROYALE_HOME/js/bin/mxmlc src/HelloRoyale.mxml

实测回显（关键行）：

INFO: 0 error(s), 0 warning(s), 97.3% typed
The project 'HelloRoyale' has been successfully compiled and optimized.
12.110269487 seconds

产物：bin/js-release/HelloRoyale.js（79630 B，压缩优化）+ HelloRoyale.min.css + index.html；bin/js-debug/HelloRoyale.js（6880 B，未压缩）。

4.2 asjsc（纯 ActionScript → JavaScript）

编译不含 MXML 的纯 ActionScript 类为 JavaScript，语法同 mxmlc，目标为 JS Core（-js-output-type=jsc）。

4.3 asnodec（纯 ActionScript → Node.js）

编译 ActionScript 为 Node 模块，产物可直接 node 运行：

cd /root/royale-node-hello
$ROYALE_HOME/js/bin/asnodec src/main/royale/HelloWorld.as
cd bin/js-release && node index.js

实测回显与输出：

WARNING: externs/zlib.js:384: WARNING - name module is not defined in the externs.
module.exports = zlib;
Oct 12, 2026 4:51:29 PM com.google.javascript.jscomp.LoggerErrorManager printSummary
WARNING: 0 error(s), 68 warning(s), 97.5% typed
The project 'HelloWorld' has been successfully compiled and optimized.
11.071976096 seconds

Hello Royale World!

退出码 0。externs/zlib.js 的 WARNING 与 68 条警告为类型定义提示，不影响产物运行。

4.4 compc 与 externc

  • compc：组件编译器，用于把自定义组件/库打包为 SWC（框架 SWC 即由此产出），Maven 工程中框架库以 <type>swc</type> 依赖引入。
  • externc：生成 externs 类型定义文件，供闭包编译器识别外部 JS API。

五、Maven 插件目标

mvn package 实测依次执行三个目标：

目标作用（实测回显）
compile-app以 -load-config=target/compile-app-config.xml 调用 MXMLC 编译主应用（INFO: 0 error(s), 0 warning(s), 97.2% typed）
trust创建 FlashPlayer 安全信任文件（Creating new FlashPlayer security trust file at: /root/.macromedia/Flash_Player/...）
package-js打包 JS 产物（BUILD SUCCESS，24.276s）

产物含 target/javascript/bin/js-release/ 三件套、js-debug/ 与可直接部署的 target/royale-hello-0.9.12.war。

六、MXML 核心 API 速查

6.1 命名空间

MXML 根元素声明两个命名空间：

<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
                xmlns:js="library://ns.apache.org/royale/basic">
  • js：Royale 基础组件命名空间（library://ns.apache.org/royale/basic）。
  • fx：MXML 语言命名空间（声明绑定、脚本等语言特性）。

6.2 js:Application 与 js:View

js:Application 是应用根组件，js:initialView 声明启动时的初始视图，js:View 是承载内容的视图组件：

<js:Application ...>
    <js:initialView>
        <js:View>
            ...
        </js:View>
    </js:initialView>
</js:Application>

6.3 js:Label 等基础组件

js:Label 文本组件，text 设置内容、x/y 设置坐标（实测示例）：

<js:Label text="Hello Apache Royale 0.9.12!" y="24" x="24"/>

基础命名空间下还提供按钮、输入框、布局组件等（详见框架 SWC 清单对应库）。

6.4 js:SimpleCSSValuesImpl

js:valuesImpl 用于声明值实现，js:SimpleCSSValuesImpl 提供简单 CSS 样式值解析：

<js:valuesImpl>
    <js:SimpleCSSValuesImpl/>
</js:valuesImpl>

七、框架 SWC 清单

royale-asjs/frameworks/js/libs/ 下共 37 个框架 SWC（实测清单，按库名分域）：

领域SWC
核心/基础BasicJS、CoreJS、CollectionsJS、LanguageJS、XMLJS、ReflectionJS
界面组件HTMLJS、HTML5JS、GraphicsJS、TextJS、EffectsJS、IconsJS、JewelJS、FlatJS、MXRoyaleBaseJS、MXRoyaleJS、SparkRoyaleJS、RoyaleSiteJS
数据/网络NetworkJS、StorageJS、FormattersJS、ChartsJS、BindingJS、ExpressJS、CreateJSJS
集成/第三方AceJS、CruxJS、DragDropJS、FontAwesomeJS、GoogleMapsJS、MaterialDesignLiteJS、MobileJS、jQueryJS、TLFJS
测试RoyaleUnitJS、RoyaleUnitUIJS

框架 SWC 清单以实测 ls 输出为准。Maven 方案中常用 Basic 库（org.apache.royale.framework:Basic:0.9.12，type swc，classifier js）。

八、Node 端 API

Node 目标下，ActionScript 类编译为 Node 模块，入口 index.js。常用 API 即 JavaScript 环境原生能力，实测示例：

package {

public class HelloWorld {

    public function HelloWorld() {
        console.log("Hello Royale World!")
    }

}

}

编译运行：

cd /root/royale-node-hello
$ROYALE_HOME/js/bin/asnodec src/main/royale/HelloWorld.as
cd bin/js-release && node index.js

实测输出：

Hello Royale World!

退出码 0，js-debug 版本输出一致。

九、完整示例串联

把工具与 API 串成一次完整的「编译 → 校验 → 运行」流程：

export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
export MAVEN_OPTS="-Xms256m -Xmx512m"

# 1. Maven 编译浏览器端应用
cd /root/royale-hello && mvn package

# 2. 浏览器端 JS 语法校验（产物依赖 DOM，不能 node require）
node --check target/javascript/bin/js-release/HelloRoyale.js

# 3. Node 端编译并运行
cd /root/royale-node-hello && $ROYALE_HOME/js/bin/asnodec src/main/royale/HelloWorld.as
cd bin/js-release && node index.js

实测最终输出 Hello Royale World!，退出码 0，全流程通过。

十、注意事项

⚠️ 注意：

  1. 所有编译脚本位于 royale-asjs/js/bin/，依赖 ROYALE_HOME 环境变量定位 SDK；脚本是 Java 进程，受 JVM 堆限制（默认 -Xmx384m）。
  2. 浏览器目标 JS 产物依赖 DOM，只能用 node --check 做语法校验；服务器端运行请使用 asnodec 的 Node 目标。
  3. mvn package 需联网拉取框架 SWC 与编译器依赖，离线环境请提前准备本地 Maven 仓库。

十一、常见问题

Q1：mxmlc、asjsc、asnodec 有什么区别？ mxmlc 编译 MXML/ActionScript（含 UI），默认浏览器目标；asjsc 编译纯 ActionScript 为 JS Core；asnodec 编译纯 ActionScript 为 Node.js 模块（-js-output-type=node + +configname=node）。UI 应用用 mxmlc/Maven，服务器端逻辑用 asnodec。

Q2：如何编译自己的 SWC 组件库？ 用 compc 工具把组件源码编译为 SWC，之后在应用侧用 -compiler.external-library-path 引用，或作为 <type>swc</type> 依赖放入 Maven 工程。

Q3：浏览器端 JS 产物如何运行？ 将 index.html 与对应 JS/CSS 部署到 Web 服务器后用浏览器打开；Maven 构建的 war 包（royale-hello-0.9.12.war）可直接部署。不要在 Node 里 require 浏览器产物。

Q4：编译输出 externs/zlib.js ... name module is not defined 等 WARNING 有影响吗？ 没有。实测 0 error 即成功产出，68 条 WARNING 为闭包编译器类型定义提示，产物运行正常（Hello Royale World!，退出码 0）。

Q5：工具版本如何确认？ mxmlc --help 首行输出 Version 0.9.12 build 0；Maven 方案以 pom 中 royale.version 属性为准，须与 SDK 版本一致。

十二、参考链接

  • Apache Royale 官方文档：https://royale.apache.org/
  • Apache Royale 官方下载目录：https://downloads.apache.org/royale/
  • royale-asjs 源码与示例：https://github.com/apache/royale-asjs