Language Guide

语言指南

Language Guide

适用版本：4.0.0。

Applies to 4.0.0.

首页 · 脚本 API 参考

Home · Script API Reference

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.

模块与依赖

Modules and Dependencies

每个可执行模块以 @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);
}

变量、函数与闭包

Variables, Functions, and Closures

使用 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

对象、数组与内置值

Objects, Arrays, and Built-in Values

普通对象适合灵活属性，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(",");

错误、诊断与输出

Errors, Diagnostics, and Output

用 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;
}

宿主全局与声明文件

Host Globals and Declaration Files

宿主通过 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);

继续阅读

Continue Reading

• 宿主集成：配置 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.

• TDoc 类型文档：保留日期、Packed Array、路径和已注册 CLR/CIL 类型的数据格式。

  TDoc Typed Document: a data format that preserves dates, packed arrays, paths, and registered CLR/CIL types.