API 参考

运行时提供的全部全局对象、宿主模块与内置模块。按"能不能用"写清楚,而不是只列名字 —— 每个 API 都标注实际行为与默认值,末尾单列一份与 Node.js / 浏览器的差异清单。

1运行时与全局作用域

Gox 是单线程的字节码虚拟机。一个脚本从词法分析一路走到栈式帧执行,期间 不会在多线程之间迁移 —— 网络回调在 Go 的 goroutine 上被捕获后,会被重新调度回 这条唯一的脚本线程上执行。所以你的 JS 代码永远单线程,不需要锁。

四种执行方式

方式命令说明
REPLgox交互式,:help / :clear / :exit
运行脚本gox app.js执行完最后一个顶层表达式后回显其值,并等待所有定时器与异步回调跑完才退出
创建工程gox create my-app脚手架:铺出一个开箱即跑的 GUI 工程(new / init 同义,需 0.4.0+)
打包成单文件go run ./packager app.js -o app.exe把运行时与脚本一起编成独立可执行文件

goxjs 与 gox 是同一个二进制的两个命令名;从源码构建出来的叫 Gox / Gox.exe。子命令的判定规则是"这个参数像不像脚本路径" (看扩展名与路径分隔符),所以 gox help.js 仍然是跑脚本而不是 help。

全局作用域里有什么

宿主能力(fs / path / process / http / fetch / console)与标准内建对象 全部直接挂在全局,不需要 import。只有 gx/* 系列(界面与平台能力)需要显式导入:

// 宿主能力:直接用,无需 import
let cfg = fs.readFileSync("app.json", "utf-8");
console.log(process.platform, path.join("a", "b"));

// 界面能力:必须 import(内置模块优先于文件系统解析)
import { createSignal } from "gx/solid";
import { h, render } from "gx/gfx";

模块系统

import / export 是静态的,相对路径以 当前文件为基准解析;也支持默认导出、命名空间导入与动态 import()。 gx/ 开头的名字与 gox 是保留的内置模块命名空间: 只查内置模块表,查不到直接报错并列出可用模块 —— 拼写错误不会变成文件读取错误, 内置模块也不会被同名文件覆盖。

import sq, { PI } from "./math_utils.js";      // 默认 + 命名导出
import * as math from "./math_utils.js";       // 命名空间导入
import { h, render, createSignal } from "gox"; // 聚合入口: gx/* 全部导出的并集
import("./math_utils.js").then(m => m.PI);     // 动态加载
导入别名 as 不支持

import { PI as P } from "…" 不生效:解析器会把 as 与 P 都当成普通命名导入,于是 P 静默为 undefined(不报错,最难查的一种)。 要换名字就 import { PI } 之后自己赋给新变量。 命名空间形式 import * as math 与默认导出不受影响。

globalThis

globalThis 指向全局对象本身,读写自定义属性、以及用静态属性名访问内置对象都可以:

let n = 0;              // 全局作用域可见,但不是 globalThis.n
globalThis.n = 0;       // 显式挂到全局对象上
console.log(globalThis.Math === Math);   // true
globalThis 不支持动态键访问,也不可枚举

globalThis.Uint8Array(点语法)能拿到值,但 globalThis["Uint8Array"] 或 globalThis[k](方括号 / 变量键)返回 undefined; Object.keys(globalThis) 永远是空数组。 "fs" in globalThis 则为 true。 所以"反射式探测全局有哪些 API"这种写法在 Gox 里行不通 —— 直接用点语法写名字即可。

脚本最后一行会被回显

命令行运行脚本时,运行时会打印最后一个顶层表达式的值(undefined 除外)。 不想让它打印就在末尾写 void 0; —— 多窗口演示脚本就是靠这个收尾的。 另外最后一条语句是 import 时会把模块对象当回显值打出来,所以 import 一律放文件顶部。

2全局速查表

一张表看全全局环境。带 仅 Windows 标记的能力在其它平台会安全降级。

类别成员
基础 Object Array String Number Boolean Function Symbol BigInt globalThis
集合 Map Set WeakMap WeakSet WeakRef FinalizationRegistry Iterator
数值 / 数学 Math parseInt parseFloat isNaN isFinite NaN Infinity
文本 / 数据 JSON RegExp
异步 Promise,以及 async / await 语法
二进制 ArrayBuffer DataView,TypedArray 全家族(Uint8Array 等)
元编程 Proxy Reflect eval
错误 Error TypeError RangeError ReferenceError SyntaxError AggregateError
日期时间 Temporal(没有 Date)
定时器 setTimeout setInterval clearTimeout clearInterval requestIdleCallback cancelIdleCallback delay,严格定时器四件套
宿主(无需 import) console fs path process http fetch
响应式(全局函数) obs computed ever once
内置模块(需 import) gx/solid gx/gfx gx/view gx/router gx/screen gx/dialog gx/storage gx/dev gx/device gx/app gx/geo gx/media gx/permission gx/viewport,以及聚合入口 gox
命令行子命令 create / new / init(脚手架)、version、help
关键字字面量 undefined NaN Infinity

3标准内建对象

下表按"你能直接用的方法"列出,不追求罗列全部原型方法 —— 与 ES 标准一致的部分不重复展开。

3.1

基础与集合

对象要点
Objectkeys / values / entries / assign / freeze / create / getPrototypeOf 等;原型上有 toString / hasOwnProperty / valueOf
Array完整原型方法族:map / filter / reduce / find / flat / sort / splice / at 等,以及 Array.from / Array.of / Array.isArray
String原型方法族:slice / split / replace(All) / padStart / trim / startsWith / match(All) 等
NumberMAX_VALUE / MIN_VALUE / EPSILON / MAX_SAFE_INTEGER 等常量 + Number.parseInt / isInteger / toFixed
Boolean / Symbol / BigIntSymbol("x") 创建唯一符号;BigInt(1n) 任意精度整数
Map / Set完整方法族:set / get / has / delete / size / keys / values / entries / forEach
WeakMap / WeakSet弱引用集合,键必须是对象
WeakRef / FinalizationRegistry弱引用与终结回调
Iterator迭代器助手(ES2025),配合 for...of 与展开语法
3.2

数值与数学

对象要点
Mathabs / floor / ceil / round / max / min / pow / sqrt / hypot / random / trunc / sign / 三角函数,以及 PI / E 等常量
Number见上;数值字面量支持 0x / 0b / 0o / 指数 / 下划线分隔
BigInt后缀 n 字面量(10n);与 Number 不能混算
3.3

字符串与正则

对象要点
String模板字符串(`a${b}`)是语言层能力;原型方法见上表
RegExptest / exec / 命名捕获组 / 标志 gimsuy;String.prototype.replace 支持替换函数
JSONstringify(value, replacer?, space?) 与 parse(text, reviver?)
console.log(JSON.stringify({ ok: true }, null, 2));
console.log("a-b-c".split("-").map(s => s.toUpperCase()));   // [A, B, C]
console.log(/^(\d+)-(\w+)$/.exec("42-abc")[2]);              // abc
3.4

异步

对象要点
Promisenew Promise(fn)、then / catch / finally,静态 resolve / reject / all / allSettled / race / any
async / await语法层支持。async function 与 async 箭头(async () => {} / async x => x)都可以;顶层不能 await
delayGox 特有的便捷函数:delay(ms, value?) 返回一个延时 resolve 的 Promise
async function main() {
  let v = await delay(10, "timer done");     // 内置便捷函数
  console.log(v);
}
main();

// ⚠ 事件处理器要写成匿名 async 函数表达式
const onClick = async function () {
  const r = await fetch("https://example.com");
  console.log(r.status);
};
3.5

二进制

对象要点
ArrayBuffer固定长度字节缓冲,byteLength / slice
TypedArray 家族Int8Array / Uint8Array / Uint8ClampedArray / Int16Array / Uint16Array / Int32Array / Uint32Array / Float32Array / Float64Array / BigInt64Array / BigUint64Array
DataView按偏移读写任意类型:getUint8 / setInt32 / getFloat64 等,可指定大小端
let buf = new ArrayBuffer(8);
let view = new DataView(buf);
view.setInt32(0, 258, true);           // 小端写
console.log(view.getInt32(0, true));   // 258

// fs.readBytesSync 返回的正是字节数组
let bytes = fs.readBytesSync("testdata/image_demo.png");
3.6

元编程

对象要点
Proxy拦截对象操作:get / set / has / deleteProperty / apply / construct 等
Reflect与 Proxy 陷阱一一对应的函数式 API
eval在当前作用域求值字符串源码
3.7

错误类型

Error / TypeError / RangeError / ReferenceError / SyntaxError / AggregateError, 都可 new,带 message / name / stack, 配合 try / catch / finally / throw 使用。

try {
  throw new TypeError("bad argument");
} catch (e) {
  console.log(e.name, e.message);      // TypeError bad argument
} finally {
  console.log("cleanup");
}
3.8

Temporal 日期时间

没有 Date

Gox 不实现旧的 Date 对象,直接用 ES 的下一代日期时间 API Temporal。老代码里的 new Date() 会报 ReferenceError。

成员说明
Temporal.Now唯一读取系统时钟的入口:instant() / plainDateISO() / plainTimeISO() 等(ISO 后缀的方法固定用 iso8601 日历)
Temporal.Instant绝对时间点(纳秒精度),如 Instant.from("2026-09-19T00:00:00Z")
Temporal.PlainDate不带时间的日期
Temporal.PlainTime不带日期的时间
Temporal.PlainDateTime日期 + 时间,无时区
Temporal.ZonedDateTime带时区的完整时间
Temporal.Duration时长,可加减比较
Temporal.PlainYearMonth / PlainMonthDay年月 / 月日
Temporal.TimeZone / Calendar时区与日历对象
let today = Temporal.Now.plainDateISO();
console.log(today.toString());                       // 2026-09-19

let d = Temporal.PlainDate.from("2026-01-31");
console.log(d.add({ days: 1 }).toString());           // 2026-02-01

let due = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(due.total({ unit: "minutes" }));          // 150

完整方法集见运行时实现教程。

4全局函数与常量

名称签名说明
parseInt(string, radix?)解析整数,遇非法字符即停
parseFloat(string)解析浮点数
isNaN(value)是否为 NaN(会做类型转换)
isFinite(value)是否为有限数
eval(code)求值字符串源码
NaN常量非数字
Infinity常量正无穷
undefined常量未定义
console.log(parseInt("42px", 10));    // 42
console.log(parseFloat("3.14abc"));   // 3.14
console.log(isNaN(NaN), isFinite(Infinity));   // true false

5定时器与调度

常规定时器

API签名说明
setTimeout(fn, ms) => id延迟执行一次
setInterval(fn, ms) => id周期执行
clearTimeout(id)取消
clearInterval(id)取消
requestIdleCallback(fn) => id空闲时机回调,不阻塞关键路径
cancelIdleCallback(id)取消空闲回调
delay(ms, value?) => PromiseGox 便捷函数:延时 resolve 指定值,写示例与测试很方便

严格定时器

常规定时器会在事件循环空闲时才跑,实际间隔可能被拖长。对时间敏感的场景用严格定时器家族:

API说明
setStrictTimeout严格版单次定时器,按目标时刻调度而非"排队"
setStrictInterval严格版周期定时器
clearStrictTimeout取消
clearStrictInterval取消
setStrictIntervalMode调整周期定时器的补偿模式
退出语义

脚本不会在有未完成定时器或异步回调时立刻退出 —— 事件循环会把它们全部驱动完, 这也就是"顶层调用了 async 函数,过一会儿还能看到它打印结果"的原因。

GUI 应用里的光标闪烁

窗口既没有事件也没有定时器时,事件泵会睡着,输入框光标就冻住。需要持续闪烁的应用挂一个空转的 requestAnimationFrame 循环即可。

6宿主模块

全部是全局对象,无需 import,风格与 Node.js 对齐。 fs 的每个方法都提供同步与异步两态。

6.1

console

方法说明
console.log标准输出
console.info信息(输出同 log)
console.warn警告,写入 stderr
console.error错误,写入 stderr
6.2

fs — 文件系统

每个 xxxSync 都有对应的异步版本。异步版本同时支持 错误优先回调(Node 语义)与 await 两种写法。

同步异步说明
readFileSyncreadFile读文本(默认 UTF-8;传 "base64" 返回 base64)
readBytesSync—读原始字节,返回字节数组
writeFileSyncwriteFile写入(覆盖)
appendFileSyncappendFile追加
existsSync—路径是否存在
statSyncstat文件信息:size / isFile() / isDirectory()
readdirSyncreaddir列出目录项
mkdirSyncmkdir创建目录,支持 { recursive: true }
unlinkSyncunlink删除文件
rmdirSync—删除空目录
rmSync—递归删除
renameSync—重命名 / 移动
copyFileSync—复制文件
// 同步
fs.writeFileSync("hello.txt", "hello gox");
console.log(fs.readFileSync("hello.txt", "utf-8"));   // hello gox
let st = fs.statSync("hello.txt");
console.log(st.size, st.isFile());

// 异步 · 错误优先回调
fs.readFile("hello.txt", "utf-8", (err, data) => {
  if (err) throw err;
  console.log(data);
});

// 异步 · await(Promise 化)
const text = await fs.readFile("hello.txt", "utf-8");
路径基准

fs 的相对路径按进程工作目录解析,不是"脚本所在目录" (脚本可能来自 stdin / 字符串 / 打包产物,没有所在目录这个概念)。

6.3

path — 路径处理

成员说明
join(...parts)拼接路径,自动处理分隔符
resolve(...parts)解析成绝对路径
dirname(p)取上级目录
basename(p)取文件名
extname(p)取扩展名
isAbsolute(p)是否为绝对路径
sep路径分隔符(属性,非函数)
delimiter路径列表分隔符(属性,非函数)
let cfgPath = path.join(process.cwd(), "app.json");
console.log(path.extname("archive.tar.gz"));   // .gz
console.log(path.dirname("/a/b/c.txt"));       // /a/b
6.4

process — 进程信息

成员类型说明
argv属性命令行参数数组,如 [gox, app.js, ...]
env属性环境变量快照对象
platform属性windows / linux / darwin
pid属性进程 ID
cwd()函数当前工作目录
chdir(p)函数切换工作目录
exit(code)函数退出进程
console.log(process.platform, process.pid);
console.log(process.argv);              // [gox, app.js, ...]
console.log(process.env.HOME ?? process.env.USERPROFILE);
6.5

http — 客户端与服务端

成员说明
http.createServer(handler)创建 HTTP 服务,返回 server 对象
http.get(url, cb?)发起 GET 请求
http.request(opts, cb?)发起任意方法请求

server 对象:

成员说明
listen(port, cb?)监听端口;传 0 表示随机端口,实际端口写入 server.port
close()关闭服务
listening是否正在监听
port实际监听的端口

请求对象 req:method / url / path / query(已解析的查询参数) / headers / body / getHeader(name)

响应对象 res:statusCode / writeHead(status, headers) / setHeader / getHeader / removeHeader / write(chunk) / end(body)

// server.js
const server = http.createServer(function (req, res) {
  if (req.path === "/json") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ msg: "hi " + req.query.name, method: req.method }));
  } else {
    res.end("hello world");
  }
});

server.listen(8080, function () {
  console.log("listening on http://127.0.0.1:8080");
});
$ gox server.js
listening on http://127.0.0.1:8080

# 另开终端验证
$ curl "http://127.0.0.1:8080/json?name=zed"
{"msg":"hi zed","method":"GET"}

处理函数里可以 await 或用 setTimeout 延迟 end,服务器会挂起任务保活事件循环直到响应完成。 网络回调跑在 goroutine 上,被调度回脚本单线程执行 —— 无需加锁。

6.6

fetch — 全局 HTTP 客户端

用法说明
fetch(url, options?)返回 Promise<Response>;options 支持 method / body / headers

Response 对象:url / status / statusText / ok(2xx 为 true) / headers / body,以及 text() 与 json() 两个读取方法。

const r = await fetch("https://httpbin.org/get?name=zed");
console.log(r.status, r.ok);          // 200 true
console.log(await r.text());

// POST
const r2 = await fetch("https://httpbin.org/post", {
  method: "POST",
  body: JSON.stringify({ hello: "gox" }),
  headers: { "Content-Type": "application/json" }
});
const data = await r2.json();

7内置模块 gx/*

内置模块一共 9 个:8 个细分模块(按职责划分)加 1 个聚合入口 gox(8 个的并集)。 它们需要 import,并且优先于文件系统解析 —— gx/ 与 gox 是保留命名空间,拼错会直接报"未知模块"并列出可用模块, 不会退化成"读某个同名文件"。

下面每个模块都给出完整导出清单 + 签名 + 返回值 + 调用约定。 全部条目都对着 RegisterBuiltinModule 的注册表核过, 并用真实运行时枚举了一遍(Object.keys(import * as ns))。

模块地图与导入路径

模块导出数管什么平台
gox139聚合入口:下列 14 个模块导出的并集—
gx/solid8响应式原语(信号 / 副作用 / 派生值 / 异步资源 / 生命周期)全平台
gx/gfx7元素树构造、窗口挂载、帧回调、补间动画、剪贴板、右键菜单需要窗口后端
gx/view2多分支条件(Switch / Match)全平台
gx/router7路由:路由表 / 参数匹配 / 守卫 / 历史栈 / 懒加载 / 多窗口作用域全平台
gx/screen17显示器枚举、窗口几何、折叠姿态与折痕枚举需后端;姿态靠上报
gx/dialog3原生系统对话框仅 Windows 原生
gx/storage7应用级键值持久化全平台
gx/dev1开发期只读快照(帧 / 缓存 / 树 / 警告)全平台
gx/device24设备信息、电量、网络、震动、屏幕亮度与常亮、打开系统设置页部分需宿主
gx/app14前后台状态、内存告警、返回键、分享、退出、屏幕方向需宿主
gx/geo10定位(取一次 / 持续监听)、两点距离需宿主;桌面报 unavailable
gx/media8拍照、选图 / 选视频、保存图片、预览需宿主;桌面报 unsupported
gx/permission10权限查询 / 申请 / 打开应用设置页需宿主
gx/viewport21安全区、软键盘、分屏与多窗口形态、宽度档靠宿主上报

选哪条导入路径

// 应用代码:一行拿到常用的那批
import { h, render, createSignal, createRouter, RouterView } from "gox";

// 库代码 / 想精确表达依赖:用细分模块
import { h, render } from "gx/gfx";
import { createSignal } from "gx/solid";

不在 gx/* 里的东西(最容易找错的地方)

你想找的实际在哪怎么用
model / each / showh() 层的元素级指令写在元素上,如 <input model={draft} />、<view each={rows}>。不 import,也不在任何导出表里
obs / computed / ever / once全局函数(GetX 风格)直接调用,见 §8
fs / path / process / http / fetch / console全局宿主模块直接调用,见 §6
alert / confirm / openFilegx/dialogimport { alert } from "gx/dialog"。注意:它们不在 gx/gfx 里 —— 从 gx/gfx 取会得到 undefined
createSignal 家族gx/solid见 gx/solid
<window> / <column> 等元素JSX 内置标签,由 gx/gfx 的 h 解析见组件参考
三个最容易记错的点

① alert / confirm / openFile 只在 gx/dialog; gx/gfx.alert 是 undefined。
② gx/view 只导出 Switch 与 Match —— 列表与显隐是元素级指令 each / show,不在这个模块里。
③ gx/screen 的 useXxx 返回一个取值函数,要再调一次:const r = usePosture(); r()。 详见下面 gx/screen 一节。

gx/solid — 响应式原语

import {
  createSignal, createEffect, createMemo, createResource,
  onMount, onCleanup, untrack, devStats,
} from "gx/solid";
导出签名 / 返回说明
createSignal(initial) => [get, set]创建信号。get() 读值并登记依赖;set(v) 或 set(prev => v) 写值。新旧值 === 相同则不通知订阅者
createEffect(fn) => dispose立即执行一次 fn,执行期间读到的 getter 成为依赖;依赖变化时重跑,每轮重新收集依赖(上轮不再被引用的依赖退订)。返回值是注销函数
createMemo(fn) => getter惰性派生值:依赖变化只标脏,下次读取时才重算。下游读 memo 同样会被记为依赖
createResource(fetcher) => [data, res]异步资源。见下方专表
onMount(fn) => void本代子树挂载后执行一次
onCleanup(fn) => void本代子树被替换 / 销毁时执行 —— 用来收定时器、解绑回调
untrack(fn) => value在不登记依赖的前提下执行 fn 并返回其结果。路由内部就靠它调页面组件,避免"页面体里读的信号变成路由 effect 的依赖"。参数必须靠闭包捕获:取值函数用零参调用拿到的那个,转发包装层不要把自己的形参再传一遍
devStats() => object开发期统计(信号数 / 订阅数等);也出现在 devSnapshot().solid 里

createResource 的契约(与 Solid 有几处刻意不同,属公共 API 承诺):

成员取值
data()undefined(从未成功过 / pending) | 成功值 | 上一次的值(refreshing / error 期间)
res.state()"pending" | "ready" | "refreshing" | "error"
res.error()仅 error 态有值,其余为 undefined
res.refetch()重取(保留旧值显示,即 refreshing)
import { createSignal, createEffect, createMemo, createResource } from "gx/solid";

const [count, setCount] = createSignal(0);
const dispose = createEffect(() => console.log("count is", count()));  // 立即跑一次
setCount(5);                       // → count is 5
setCount(v => v + 1);              // setter 也接受更新函数
dispose();                         // 注销这个 effect

const doubled = createMemo(() => count() * 2);
setCount(10);
console.log(doubled());            // 20(惰性:读的时候才算)

const [user, res] = createResource(async function () {
  const r = await fetch("https://example.com/me");
  return await r.json();
});
// res.state(): "pending" → "ready"
// 失败后 data() 仍是上一次的值,错误读 res.error()
同一个 effect 里既读 signal 又读它的 memo ⇒ 每轮只跑一次

该 effect 同时经两条路订阅了同一次变更(直接订阅 signal + 经 memo 的 cell),引擎按"一趟通知" 去重:先把链上 memo 标脏,再跑 effect。2026-09-24 之前的版本每轮会跑两次,症状是"计数类断言 多了一倍";现在只跑一次,且读到的 memo 值必然已是新的。

gx/gfx — 界面与窗口

import {
  h, render, requestAnimationFrame,
  clipboardReadText, clipboardWriteText,
  animate, openContextMenu,
} from "gx/gfx";
导出签名 / 返回说明
h(tag, props, ...children) => node创建元素。JSX 编译后就是它,所以用了 JSX 的文件必须 import(哪怕一次都没显式调用)
render(vnode, config?) => 窗口句柄挂载元素树并开窗口。可多次调用 = 多窗口。三种形态见下
requestAnimationFrame(fn) => id以 ~60fps 帧间隔把回调挂到事件循环(内部就是 16ms 定时器)。也用来让事件泵保持醒着(驱动光标闪烁)
clipboardReadText() => string同步读剪贴板;读不到返回空串,不抛异常
clipboardWriteText(text) => boolean同步写剪贴板;失败返回 false
animate两种形态,返回 cancel 函数animate(node, prop, to, ms) 让某节点的某属性动到目标值;animate(from, to, ms, onUpdate, onDone) 自己拿插值。声明式过渡走 transition prop,不经这个函数
openContextMenu(x, y, items) => void就地弹出右键菜单。这是数据式 API,不是 contextMenu prop(同一个 JSX 元素只能有一个宿主)

render 的三种形态

// ① JSX:窗口配置写在根元素属性上(最常用)
render(<window title="Counter" width={400} height={300}>...</window>);

// ② h() 手拼树:窗口配置作为第二个参数
render(h("column", { gap: 10 }, ...), { title: "Slider demo", width: 260, height: 260 });

// ③ 省略配置:用缺省 Gox 400x300
render(h("text", null, "hello"));

返回的窗口句柄提供 close() / isClosed() / title() / setTitle(t) / resize(w, h), 详见组件参考 · 多窗口。

剪贴板是同步 API

const ok = clipboardWriteText(text());
const s  = clipboardReadText();        // 读不到是空串

脚本与窗口在同一个 OS 线程,直接调原生 API 就是正确的线程,不需要 await。后端不支持时静默降级(写返回 false、读返回空串)。

原生对话框不在这个模块里

alert / confirm / openFile 由 gx/dialog 导出。 从 gx/gfx 取会得到 undefined。

gx/view — 多分支

import { Switch, Match } from "gx/view";
导出签名说明
Switch({fallback?}, ...<Match/>)取声明序里第一个 when 为真的分支;都不真用 fallback
Match({when}, ...children)单个分支;when 要传函数。只在 Switch 里有意义 —— 挂到别处会渲染成一行 [view Match] 文本(误用可见,不静默)
这个模块为什么只有两个导出

列表(each)与显隐(show)是元素级指令 —— 写在元素上、由 h() 展开,不需要 import。只有"多分支"没有对应的元素语义, 所以留成了组件。用法见组件参考 · 列表与条件。

gx/router — 路由

import { createRouter, RouterView, RouterLink, lazy, useRoute, useRouter, useRouteState } from "gx/router";
导出说明
createRouter({routes, initial, backKeys, foldable})建路由器。路由记录字段:path / name / component / children / meta / redirect / props / beforeEnter / keepAlive / dualPane
<RouterView />当前路由的挂载点;可传 loading / error 分支与 scope(显式作用域,一个窗口里放两套独立导航)
<RouterLink to="…" />导航链接;to 收路径串或 {name, params}(一律按绝对路径解析)
router.push / replace / back / forward / go导航,均返回 Promise({ok, route},被守卫拦下是 {ok:false, reason})
useRoute() / useRouter() / useRouteState()页面体内取当前路由 / 路由器 / 挂在历史栈项上的状态袋
lazy(() => import(…))懒加载页面模块。推荐显式包一层 —— 不包的话首次进入拿不到组件级守卫
import { createRouter, RouterView, RouterLink } from "gx/router";

const router = createRouter({
  routes: [
    { path: "/",           name: "home",   component: HomePage },
    { path: "/list",       name: "list",   component: ListPage, keepAlive: true },
    { path: "/detail/:id", name: "detail", component: DetailPage },
    { path: "*",           name: "nf",     component: NotFound },
  ],
  initial: "/",
});

render(
  <window title="app" width={480} height={360}>
    <column gap={8} padding={12}>
      <RouterLink to="/list"><text font={13}>列表</text></RouterLink>
      <RouterView />
    </column>
  </window>
);

gx/screen — 屏幕与折叠姿态

import {
  screens, primaryScreen, screen, screenOf,
  useScreen, useScreens, windowInfo, useWindowInfo,
  posture, usePosture, hinge, regions, platform,
  reportPosture, resetDisplays, onDisplayChange, offDisplayChange,
} from "gx/screen";
调用约定:useXxx 返回的是取值函数,要再调一次

screens() / posture() 这类是直接读数; 而 useScreen() / useScreens() / usePosture() / useWindowInfo() 返回一个取值函数,并且只有调用那个取值函数才会登记依赖:

const getPosture = usePosture();      // ← 拿到取值函数
<text>{() => getPosture()}</text>      // 姿态一变,这行文本跟着变

设计动机:显示器表结构较大,做成整表 signal 不划算,于是用"版本号 + 取值函数"的组合 —— 取值函数每次调用都重读当前状态并订阅版本号,与 useRoute() 同构。

导出签名 / 返回说明
screens() => Display[]全部显示器
primaryScreen() => Display主显示器
screen(id) => Display | null按 id 取一块屏;找不到返回 null
screenOf(win?) => Display | null窗口所在的显示器。win 省略 = 最近挂载的窗口;没有窗口时返回 null
useScreen(win?) => getterscreenOf 的响应式版
useScreens() => getterscreens() 的响应式版
windowInfo(win?) => object窗口尺寸 / 缩放 / 所属屏的直接读数,字段见下
useWindowInfo(win?) => getter同上,响应式
posture(win?) => string折叠姿态:"flat" / "half-open" / "folded" / "unknown"
usePosture(win?) => getter同上,响应式
hinge(win?) => object | null折痕矩形 {x, y, width, height, orientation};没有折痕时 null
regions(win?) => array折叠分段面板 [{id, x, y, width, height}]
platform() => string窗口后端名:"win32" / "x11" / "cocoa" / "headless"
reportPosture(opts) => undefined宿主 / 模拟器上报姿态。收 opts 对象、返回 undefined —— 与 posture() 是两条不同的路
resetDisplays() => undefined清掉上报覆盖,回退到后端枚举结果
onDisplayChange(fn) => off()订阅显示器 / 姿态变化;返回值就是注销函数(可重复调用),也可以用 offDisplayChange(fn)
offDisplayChange(fn) => undefined按回调函数注销

Display 对象的字段

字段说明
id / name显示器标识(如 \\.\DISPLAY1;上报的自定义屏就是上报时给的名字,如 "fold-0")
x / y / width / height整块屏的几何(虚拟桌面坐标,副屏可能是负数)
workX / workY / workWidth / workHeight工作区(扣掉任务栏)
scale每屏 DPI 缩放
primary是否主屏
foldable是否折叠设备
posture折叠姿态字符串
hinge折痕矩形或 null
regions分段面板数组

windowInfo() 的字段

// {width, height, scale, screenWidth, screenHeight, workWidth, workHeight, screenId, platform}
const info = windowInfo();
console.log(info.width, info.screenWidth, info.screenId, info.platform);

reportPosture(opts) 的字段

字段说明
display目标显示器 id。省略则作用于当前窗口所在的那块屏(再退化为第一块)
posture"flat" / "half-open" / "folded"。 大小写与空格不敏感,halfopen / half_open 也认; 不认识的字符串会被归一成 "unknown" 而不是报错
foldable是否折叠设备。不传但报了非 flat 姿态时自动置 true
width / height屏尺寸(上报自定义屏时用;已存在的屏不传则保持原值)
hinge{x, y, w, h, orientation} —— 注意这里是 w / h
regions[{id, x, y, width, height}]
写入用 w/h,读出是 width/height

reportPosture 的 hinge 读 w / h,而 hinge() 读出来的是 width / height。 把读出的对象直接喂回去会得到一块 0 宽的折痕 —— 这是最容易踩的一处命名不一致。

import { reportPosture, resetDisplays, screenOf, posture, hinge, usePosture } from "gx/screen";
import { createMemo } from "gx/solid";

// 宿主上报:先问"窗口在哪块屏",再报那块屏的姿态
const wa = render(<window title="A">...</window>);
reportPosture({
  display: screenOf(wa).id,
  foldable: true,
  width: 2000,
  posture: "half-open",
  hinge: { x: 980, y: 0, w: 40, h: 1400, orientation: "vertical" },   // ← w / h
});

console.log(posture(wa));        // "half-open"
console.log(hinge(wa));          // { x:980, y:0, width:40, height:1400, orientation:"vertical" }

// 响应式:useXxx() 先拿到取值函数,再放进函数 prop / 函数子节点
const getPosture = usePosture(wa);
const folded = createMemo(() => getPosture() === "half-open");

resetDisplays();                 // 撤销上报,回到后端枚举

gx/dialog — 原生系统对话框

import { alert, confirm, openFile } from "gx/dialog";
导出返回说明
alert(msg, title?)Promise<void>系统消息框,只有一个"确定"
confirm(msg, title?)Promise<boolean>确定 / 取消,返回用户选择
openFile({title, filter})Promise<string | null>系统"打开文件"对话框;取消返回 null,不抛异常

filter 是 {name, pattern} 数组, pattern 里多个通配符用 ; 分隔。

import { confirm, openFile } from "gx/dialog";

// 事件处理器的两种写法都可以: async function () {} 与 async () => {}
h("button", {
  onClick: async function () {
    const yes = await confirm("Proceed with the operation?", "Please confirm");
    log("confirm -> " + (yes ? "yes" : "no"));
  }
}, "Confirm");

h("button", {
  onClick: async function () {
    const p = await openFile({
      title: "Pick a file",
      filter: [
        { name: "Text files", pattern: "*.txt;*.md" },
        { name: "All files", pattern: "*.*" }
      ]
    });
    log(p === null ? "cancelled" : "picked " + p);
  }
}, "Open file");

gx/storage — 本地持久化

import {
  setAppName, appDataDir, setStorage, getStorage,
  removeStorage, clearStorage, getStorageInfo,
} from "gx/storage";
导出返回说明
setAppName(name)void指定应用名(数据目录的一段);推荐在任何 storage 调用前先调
appDataDir()string数据目录绝对路径(UserConfigDir/Gox/<appName>)
setStorage(key, value)void写入。value 只能是纯数据(对象 / 数组 / 标量);写穿透立即落盘
getStorage(key)value读回。不存在返回 undefined,并且没有"默认值参数" —— 要默认值自己写 ?? fallback
removeStorage(key)void删一个键
clearStorage()void清空
getStorageInfo(){keys, currentSize, limit}键列表与字节数;limit 恒 -1(v1 不做配额)
import { setAppName, setStorage, getStorage, getStorageInfo } from "gx/storage";

setAppName("my-app");              // → %APPDATA%/Gox/my-app (Linux: ~/.config/Gox/my-app)
setStorage("theme", "dark");
setStorage("profile", { name: "gox", level: 3 });   // 对象也行,序列化后整存整取

const t = getStorage("theme");         // "dark";首次运行为 undefined
const theme = t ?? "light";            // ← 默认值要自己兜,getStorage 没有第二参数
console.log(getStorageInfo());         // { keys, currentSize, limit }

gx/dev — 开发期快照

import { devSnapshot } from "gx/dev";
const snap = devSnapshot();
字段内容
snap.frame{count, full, partial, fullRatio} —— 帧数与整帧 / 局部占比
snap.imageCache{size, cap, hits, misses, evicts}
snap.glyphCache{size, cap, hits, misses, evicts}
snap.tree{windows, nodes, depth}
snap.solid{effects} —— 存活 effect 数;gx/solid 未注册时为 -1
snap.warnings[{at, text}] —— 最近若干条内核警告(含未知标签与指令误用的去重警告)
import { devSnapshot } from "gx/dev";

setInterval(() => {
  const s = devSnapshot();
  console.log(
    "frames:", s.frame.count,
    "整帧率:", Math.round(s.frame.fullRatio * 100) + "%",
    "字形缓存:", s.glyphCache.size + "/" + s.glyphCache.cap,
    "节点:", s.tree.nodes,
    "effect:", s.solid.effects,
  );
  if (s.warnings.length) console.log("最近警告:", s.warnings[s.warnings.length - 1].text);
}, 1000);

原生能力层 — gx/device · gx/app · gx/geo · gx/media · gx/permission · gx/viewport

六个模块(共 87 个导出)共用同一个宿主契约,不是六套机制。调用形态只有三种: 拉取型(同步读返回值)、动作型(await,失败 reject)、 上报型(宿主主动告知,useXxx() 响应式刷新)。

import { deviceInfo, battery, isOnline, canIUse } from "gx/device";
import { getLocation, watchLocation } from "gx/geo";
import { takePhoto } from "gx/media";

console.log(deviceInfo().platform, battery().level, isOnline());   // 拉取型 / 上报型

if (canIUse("camera")) {                     // 事前判断,不要靠 catch 兜底
  const photo = await takePhoto({ count: 1 });
}

const stop = watchLocation((loc) => console.log(loc.latitude, loc.longitude));
try {
  await getLocation({ highAccuracy: true });
} catch (e) {
  if (e.errCode === "permission-denied") console.warn(e.message);
}

缺能力时不软降级 —— 八个统一错误码

错误码含义
unsupported宿主没实现这个能力—— canIUse() 会是 false,应该事前判断而不是靠 catch 兜底
permission-denied用户或系统拒了权限(可提示去设置页开)
cancelled用户在系统 UI 里主动取消 —— 它不是失败
timeout / busy / unavailable宿主没回填 / 上一次还没结束 / 设备当前不可用(飞行模式下定位、没有相机硬件)
platform-error原生侧报错,细节在 errMsg 里(不要解析,只用于显示)
invalid-arg参数不合法(比如 count 为负)

gx/device — 设备信息与系统状态(24 个导出)

import {
  deviceInfo, useDeviceInfo, deviceId,
  battery, useBattery, isCharging, onBatteryChange, offBatteryChange,
  network, useNetwork, isOnline, onNetworkChange, offNetworkChange,
  vibrate, vibrateShort, vibrateLong,
  keepScreenOn, getBrightness, setBrightness, openSystemSettings,
  canIUse, capabilities, reportBattery, reportNetwork,
} from "gx/device";
导出说明
deviceInfo() / useDeviceInfo() / deviceId()平台 / 系统 / 机型 / 设备 ID / 区域 / 屏幕等;宿主未覆盖的字段取本机缺省值
battery() / useBattery() / isCharging()电量与充电状态。上报型 —— 没人上报时是 {supported: false} 这种明确的缺省值,不是错误
network() / useNetwork() / isOnline()连接类型与在线状态;同为上报型
vibrate(ms?) / vibrateShort() / vibrateLong()震动;桌面软降级(不报错)
keepScreenOn(on) / getBrightness() / setBrightness(v)屏幕常亮开关、亮度读写
openSystemSettings(kind)打开系统设置页;kind 词表共 11 项(含 privacy),桌面上 10 项有 URI 映射
canIUse(cap) / capabilities()能力判断与清单。判据依次是“宿主声明过 → 有对应内置模块 → 有对应原生注册”,因此声明与实现不一致时会说谎
onBatteryChange / onNetworkChange(fn)订阅变化,返回取消函数;offXxx(fn) 亦可
reportBattery(o) / reportNetwork(o)上报口(宿主 / 模拟器 / 测试):桌面没有真设备时靠它驱动响应式刷新

gx/app — 应用生命周期(14 个导出)

import {
  appState, useAppState, onAppStateChange, offAppStateChange,
  onMemoryWarning, offMemoryWarning, onBackPress, offBackPress,
  share, exitApp, setOrientation,
  reportAppState, reportMemoryWarning, reportBackPress,
} from "gx/app";

gx/geo — 定位(10 个导出)

import {
  getLocation, watchLocation, clearWatch, clearAllWatches,
  lastLocation, useLastLocation, hasLocation,
  distanceBetween, locationPlatform, reportLocation,
} from "gx/geo";

gx/media — 相机与相册(8 个导出)

import {
  takePhoto, chooseImage, chooseOneImage, chooseVideo,
  saveImage, previewImage, mediaInfo, humanSize,
} from "gx/media";

gx/permission — 权限(10 个导出)

import {
  checkPermission, authorize, requestPermissions, openAppSettings,
  getSetting, permissionState, permissionKinds,
  onPermissionChange, offPermissionChange, reportPermission,
} from "gx/permission";

gx/viewport — 安全区 / 键盘 / 分屏(21 个导出)

import {
  viewport, useViewport, insets, useInsets,
  keyboardHeight, useKeyboardHeight, keyboardVisible,
  contentArea, safeAreaStyle,
  widthClass, isCompactWidth, isTabletLayout,
  multiWindow, useMultiWindow, isSplit, splitInfo,
  onViewportChange, offViewportChange, reportViewport, resetViewport,
  viewportModes,
} from "gx/viewport";

桌面上的行为(不要把它当移动端用)

模块层常见误用速查

现象原因与解法
用了 JSX 但窗口起不来,报 h is not defined 已在框架里修掉(2026-09-22):JSX 仍是降级成 h(...) 调用,但文件里没有 h 时编译器会自动补 import { h } from "gx/gfx"。显式写 import { h, render } from "gx/gfx" 仍推荐、也仍优先,自己定义/导入的 h 不会被顶掉。老引擎上手动加那一行即可
alert is not a function / 拿到 undefined 从 gx/gfx 取了 —— alert / confirm / openFile 在 gx/dialog(或直接用 gox 聚合)。命名导入取不到时只会静默拿到 undefined,所以现在从内置模块 import 不存在的名字是编译期报错,并会指出它在哪个模块 / 是不是拼错
usePosture() 拿到的不是字符串 这是设计:所有 useXxx() 返回的都是取值函数(信号语义,放进函数 prop / 函数子节点才会跟着变),再调一次:const r = usePosture(); r()。只要"此刻的值"就用 posture(win)(返回字符串)。别把它直接当字符串比 —— 恒为 false 且不报错
each / show 从 gx/view 里 import 不到 这是设计:它们是元素级指令(写在 JSX 属性上、在 h() 里展开),不在任何模块的导出表里;gx/view 只导出 Switch / Match。误 import 现在编译期报错
const [data, {refetch}] = createResource(f) 不起作用 已在框架里修掉(2026-09-22):嵌套解构(数组里套对象)当年是 parser 的 bug,现在直接可写。等价写法 const [data, res] = createResource(f) + res.refetch() 照旧可用
折叠双栏不生效 这是设计:Windows / X11 没有折叠姿态查询 API,没人上报 ⇒ 姿态恒为 flat ⇒ 不分栏。宿主侧调 reportPosture;排查第一步用 posture(win) 确认读到的是 "half-open",三步排查见 GUI 路由手册 §9.2
折痕宽度读出来是 0 已在框架里修掉(2026-09-22):hinge() / regions() 的输出用 width/height,而 reportPosture 的入参历史上只读 w/h ⇒ 回填时静默读成 0(只影响分栏比例,什么都不报)。现在两种拼法都认(短名优先),reportPosture({ hinge: hinge() }) 可以直接写
标注"已在框架里修掉"的四条

JSX 缺省工厂、缺名导入、嵌套解构、折痕键名这四件事都修在了内核里(parser / compiler / gx/screen), 换成新版引擎后不必再按"解法"那栏绕行;文档与手册里其它地方若还写着"必须自己 import h""嵌套解构不支持",以本表为准。

8响应式全局 API

除 gx/solid 的信号体系外,全局还提供一套 Dart GetX 风格的响应式原语, 无需 import。

API签名说明
obs(value) => obsValue创建可观察值,读写走 .value
computed(fn) => obsValue由其它 obs 派生的计算值,依赖变化时自动重算
ever(obs, fn)持续订阅,每次变化都回调;订阅时立即以当前值回调一次
once(obs, fn)只在下一次变化时回调一次
let count = obs(0);
ever(count, v => console.log("count =", v));   // 先打印 count = 0

count.value = 1;
count.value = 2;
count.value = 2;    // 值未变化,不触发通知
count = 0
count = 1
count = 2
两套响应式怎么选

写界面用 gx/solid 的 createSignal —— 它与渲染层的 依赖追踪直接对接(组件参考 · 响应式)。 obs 这套更适合纯数据流的脚本,或在移植 Dart / GetX 代码时保持写法一致。

9与 Node / 浏览器差异

Gox 是从零实现的独立运行时,不是 Node 或浏览器的子集实现。以下差异是刻意的设计取舍。

语言层

项目Gox 的行为
var不支持。只用 let / const
import { x as y }不生效(且不报错):y 静默为 undefined。命名空间导入 import * as ns 与默认导出正常
Date没有。用 Temporal
Intl没有。数字与日期格式化要自己写
encodeURI / decodeURI没有。需要时自己用 String 方法拼
btoa / atob没有。二进制走 ArrayBuffer / TypedArray 或 fs.readBytesSync

与 Node.js 相比

项目说明
npm 生态不兼容。没有 require、没有 node_modules 解析、没有 C++ 原生插件
模块系统只有 ES 模块(import / export),没有 CommonJS
宿主模块范围只有 fs / path / process / http / fetch。没有 stream / child_process / os / crypto / net
process只有 argv / env / platform / pid / cwd / chdir / exit
事件循环单线程 VM + Go goroutine 捕获回调后回投,语义接近但不暴露 process.nextTick / setImmediate

与浏览器相比

项目说明
DOM没有 document / window / CSS。界面走自研的 gx/gfx 元素树
Web API没有 localStorage / XMLHttpRequest / WebSocket / Worker / Canvas2D / WebGL
持久化用 gx/storage(写入系统应用数据目录)代替 localStorage
网络fetch API 形似但只实现 text() / json() 两个读取方法
绘图<canvas> 提供 7 个绘制原语(矩形 / 圆 / 线 / 文本),没有路径、变换、渐变纹理
requestAnimationFrame由 gx/gfx 提供(16ms 定时器实现),不是全局函数

平台能力差异

能力WindowsLinux (X11)macOS
CLI 脚本✅✅✅
GUI 窗口✅✅(需实机验证)❌ 占位
输入法 IME✅❌—
剪贴板✅❌ 降级(读空串 / 写 false)—
原生对话框✅❌ 降级(confirm 取 true、openFile 取 null)—
显示器枚举 / 窗口归属✅未实机验证—
折叠姿态靠 reportPosture 上报靠上报—

10缺失 API 一览

便于从别的运行时迁移时快速排查 —— 下列名字在 Gox 里不存在,调用会得到 ReferenceError。

类别不存在的成员
日期时间Date、Intl
编码encodeURI、decodeURI、encodeURIComponent、decodeURIComponent、btoa、atob、TextEncoder、TextDecoder
结构化数据structuredClone、FormData、URL、URLSearchParams、Blob、File
网络XMLHttpRequest、WebSocket、EventSource、Request、Response(构造函数)
并发Worker、SharedArrayBuffer、Atomics
宿主对象document、window、navigator、localStorage、sessionStorage、location
Node 特有require、module、exports、__dirname、Buffer、process.nextTick、setImmediate、queueMicrotask
Node 模块stream、child_process、os、crypto、net、events、util、url、querystring
响应式(需 import)batch、createContext、useContext、createStore(untrack 有,已在 gx/solid 里)
内置模块gx/machine、gx/kit(状态机仍是用户态模式;gx/device / gx/app / gx/geo / gx/media / gx/permission / gx/viewport 六个原生能力模块已于 2026-09-21 落地,gx/router 与 gx/screen 同批落地,均不再是缺口)
模块里没有的gx/gfx.alert、gx/gfx.confirm、gx/gfx.openFile、gx/view.each、gx/view.show(前者去 gx/dialog,后者是元素级指令)
想确认某个 API 到底有没有

最直接的办法是在 REPL 里问一句:typeof someName —— 得到 "undefined" 就是没有。 想列一个模块的全部导出,用命名空间导入 + Object.keys: import * as s from "gx/solid"; Object.keys(s)。 完整的实现级说明见 JavaScript Runtime API 实现教程。