Language Guide

语言指南

Language Guide

适用版本：4.0.0。

Applies to 4.0.0.

首页 · 脚本 API 参考

AuroraScript 的写法接近 JavaScript，但语义和运行时 API 以 AuroraScript 为准。不要把浏览器、Node.js 或 ECMAScript 的 API 假定为可用。

AuroraScript resembles JavaScript in syntax, but its semantics and runtime APIs are defined by AuroraScript. Do not assume browser, Node.js, or ECMAScript APIs are available.

模块与依赖

每个可执行模块以 @module(NAME); 开始。import 导入模块导出，include 合并源码；路径由宿主的 Source Resolver 解析，而不是由脚本直接读取文件系统。

Every executable module begins with @module(NAME);. import consumes module exports and include combines source; paths are resolved by the host's Source Resolver rather than by scripts reading the file system directly.

// math.as
@module(MATH);

export func add(left, right) {
    return left + right;
}

// main.as
@module(MAIN);
import math from "./math";

export func run() {
    return math.add(20, 22);
}

变量、函数与闭包

使用 var 声明可变局部变量，const 声明不可重新赋值的绑定。函数可以作为值传递并捕获外层局部变量；热点循环中应把反复读取的属性缓存到 local。

Use var for mutable locals and const for bindings that are not reassigned. Functions can be passed as values and capture outer locals; cache repeatedly read properties in a local inside hot loops.

func makeAdder(base) {
    return value => base + value;
}

var addTwenty = makeAdder(20);
return addTwenty(22); // 42

对象、数组与内置值

普通对象适合灵活属性，Array 适合异构集合；已知长度且只做数值循环时，优先使用 Int32Array、Float64Array、Int8Array 或 BooleanArray。详细成员请在脚本 API 参考中按对象查找。

Ordinary objects suit flexible properties and Array suits heterogeneous collections. For known-length numeric loops, prefer Int32Array, Float64Array, Int8Array, or BooleanArray. Look up detailed members by object in the Script API Reference.

var profile = { name: "Aurora", enabled: true };
var scores = [20, 22];
scores.push(42);
return profile.name + ":" + scores.join(",");

错误、诊断与输出

用 throw new Error(message) 表示无法继续的错误；正常的“未找到”结果通常应返回 null 或约定值。使用 console.log 和 console.error 输出由宿主收集的日志。

Use throw new Error(message) for failures from which execution cannot continue; an expected “not found” result should usually return null or an agreed value. Use console.log and console.error for host-collected output.

func findPositive(values) {
    var item = values.find(value => value > 0);
    if (item == null) throw new Error("positive value is required");
    console.log("found", item);
    return item;
}

宿主全局与声明文件

宿主通过 ScriptGlobal 注入的名称可以直接在脚本中使用。若需要编辑器诊断和补全，在 Resolver 可见目录添加独立的 @global(); 声明文件；使用 declare const、declare var 或 declare func，不要使用 export declare。

Names injected by the host through ScriptGlobal can be used directly in scripts. For editor diagnostics and completion, add a standalone @global(); declaration file visible to the Resolver; use declare const, declare var, or declare func, not export declare.

@global();

declare const APP_NAME;
declare func HOST_ADD(left, right);

继续阅读

• 宿主集成：配置 Resolver、Domain、状态和 CLR 互操作。
• 示例手册：面向常见任务的完整小样例。
• 性能与基准：热点写法与可复现测量方法。

• Host Integration: configure resolvers, domains, state, and CLR interop.
• Cookbook: complete small examples for common tasks.
• Performance and Benchmarks: hot-path patterns and reproducible measurement.