1运行时与全局作用域
Gox 是单线程的字节码虚拟机。一个脚本从词法分析一路走到栈式帧执行,期间 不会在多线程之间迁移 —— 网络回调在 Go 的 goroutine 上被捕获后,会被重新调度回 这条唯一的脚本线程上执行。所以你的 JS 代码永远单线程,不需要锁。
四种执行方式
| 方式 | 命令 | 说明 |
|---|---|---|
| REPL | gox | 交互式,: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.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 标准一致的部分不重复展开。
基础与集合
| 对象 | 要点 |
|---|---|
| Object | keys / 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) 等 |
| Number | MAX_VALUE / MIN_VALUE / EPSILON / MAX_SAFE_INTEGER 等常量 + Number.parseInt / isInteger / toFixed |
| Boolean / Symbol / BigInt | Symbol("x") 创建唯一符号;BigInt(1n) 任意精度整数 |
| Map / Set | 完整方法族:set / get / has / delete / size / keys / values / entries / forEach |
| WeakMap / WeakSet | 弱引用集合,键必须是对象 |
| WeakRef / FinalizationRegistry | 弱引用与终结回调 |
| Iterator | 迭代器助手(ES2025),配合 for...of 与展开语法 |
数值与数学
| 对象 | 要点 |
|---|---|
| Math | abs / floor / ceil / round / max / min / pow / sqrt / hypot / random / trunc / sign / 三角函数,以及 PI / E 等常量 |
| Number | 见上;数值字面量支持 0x / 0b / 0o / 指数 / 下划线分隔 |
| BigInt | 后缀 n 字面量(10n);与 Number 不能混算 |
字符串与正则
| 对象 | 要点 |
|---|---|
| String | 模板字符串(`a${b}`)是语言层能力;原型方法见上表 |
| RegExp | test / exec / 命名捕获组 / 标志 gimsuy;String.prototype.replace 支持替换函数 |
| JSON | stringify(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
异步
| 对象 | 要点 |
|---|---|
| Promise | new Promise(fn)、then / catch / finally,静态 resolve / reject / all / allSettled / race / any |
| async / await | 语法层支持。async function 与 async 箭头(async () => {} / async x => x)都可以;顶层不能 await |
| delay | Gox 特有的便捷函数: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);
};
二进制
| 对象 | 要点 |
|---|---|
| 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");
元编程
| 对象 | 要点 |
|---|---|
| Proxy | 拦截对象操作:get / set / has / deleteProperty / apply / construct 等 |
| Reflect | 与 Proxy 陷阱一一对应的函数式 API |
| eval | 在当前作用域求值字符串源码 |
错误类型
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");
}
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?) => Promise | Gox 便捷函数:延时 resolve 指定值,写示例与测试很方便 |
严格定时器
常规定时器会在事件循环空闲时才跑,实际间隔可能被拖长。对时间敏感的场景用严格定时器家族:
| API | 说明 |
|---|---|
| setStrictTimeout | 严格版单次定时器,按目标时刻调度而非"排队" |
| setStrictInterval | 严格版周期定时器 |
| clearStrictTimeout | 取消 |
| clearStrictInterval | 取消 |
| setStrictIntervalMode | 调整周期定时器的补偿模式 |
脚本不会在有未完成定时器或异步回调时立刻退出 —— 事件循环会把它们全部驱动完, 这也就是"顶层调用了 async 函数,过一会儿还能看到它打印结果"的原因。
窗口既没有事件也没有定时器时,事件泵会睡着,输入框光标就冻住。需要持续闪烁的应用挂一个空转的
requestAnimationFrame 循环即可。
6宿主模块
全部是全局对象,无需 import,风格与 Node.js 对齐。
fs 的每个方法都提供同步与异步两态。
console
| 方法 | 说明 |
|---|---|
| console.log | 标准输出 |
| console.info | 信息(输出同 log) |
| console.warn | 警告,写入 stderr |
| console.error | 错误,写入 stderr |
fs — 文件系统
每个 xxxSync 都有对应的异步版本。异步版本同时支持
错误优先回调(Node 语义)与 await 两种写法。
| 同步 | 异步 | 说明 |
|---|---|---|
| readFileSync | readFile | 读文本(默认 UTF-8;传 "base64" 返回 base64) |
| readBytesSync | — | 读原始字节,返回字节数组 |
| writeFileSync | writeFile | 写入(覆盖) |
| appendFileSync | appendFile | 追加 |
| existsSync | — | 路径是否存在 |
| statSync | stat | 文件信息:size / isFile() / isDirectory() |
| readdirSync | readdir | 列出目录项 |
| mkdirSync | mkdir | 创建目录,支持 { recursive: true } |
| unlinkSync | unlink | 删除文件 |
| 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 / 字符串 / 打包产物,没有所在目录这个概念)。
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
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);
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 上,被调度回脚本单线程执行 —— 无需加锁。
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))。
模块地图与导入路径
| 模块 | 导出数 | 管什么 | 平台 |
|---|---|---|---|
gox | 139 | 聚合入口:下列 14 个模块导出的并集 | — |
gx/solid | 8 | 响应式原语(信号 / 副作用 / 派生值 / 异步资源 / 生命周期) | 全平台 |
gx/gfx | 7 | 元素树构造、窗口挂载、帧回调、补间动画、剪贴板、右键菜单 | 需要窗口后端 |
gx/view | 2 | 多分支条件(Switch / Match) | 全平台 |
gx/router | 7 | 路由:路由表 / 参数匹配 / 守卫 / 历史栈 / 懒加载 / 多窗口作用域 | 全平台 |
gx/screen | 17 | 显示器枚举、窗口几何、折叠姿态与折痕 | 枚举需后端;姿态靠上报 |
gx/dialog | 3 | 原生系统对话框 | 仅 Windows 原生 |
gx/storage | 7 | 应用级键值持久化 | 全平台 |
gx/dev | 1 | 开发期只读快照(帧 / 缓存 / 树 / 警告) | 全平台 |
gx/device | 24 | 设备信息、电量、网络、震动、屏幕亮度与常亮、打开系统设置页 | 部分需宿主 |
gx/app | 14 | 前后台状态、内存告警、返回键、分享、退出、屏幕方向 | 需宿主 |
gx/geo | 10 | 定位(取一次 / 持续监听)、两点距离 | 需宿主;桌面报 unavailable |
gx/media | 8 | 拍照、选图 / 选视频、保存图片、预览 | 需宿主;桌面报 unsupported |
gx/permission | 10 | 权限查询 / 申请 / 打开应用设置页 | 需宿主 |
gx/viewport | 21 | 安全区、软键盘、分屏与多窗口形态、宽度档 | 靠宿主上报 |
选哪条导入路径
// 应用代码:一行拿到常用的那批
import { h, render, createSignal, createRouter, RouterView } from "gox";
// 库代码 / 想精确表达依赖:用细分模块
import { h, render } from "gx/gfx";
import { createSignal } from "gx/solid";
gox不是一个新模块,只是并集 —— 每个名字的实现唯一(来自它所属的细分模块), 混用两种写法不会产生两个副本,也不会冲突(导出名跨模块无重名)。- 拆出细分模块的意义是可读性与分层:一眼看出这个文件依赖界面、响应式还是存储。
- 无头宿主(没链接 GUI 后端的构建)里
gx/gfx之类不存在,gox的并集会自动退化成宿主实际提供的那部分,不会因此报错。
不在 gx/* 里的东西(最容易找错的地方)
| 你想找的 | 实际在哪 | 怎么用 |
|---|---|---|
model / each / show | h() 层的元素级指令 | 写在元素上,如 <input model={draft} />、<view each={rows}>。不 import,也不在任何导出表里 |
obs / computed / ever / once | 全局函数(GetX 风格) | 直接调用,见 §8 |
fs / path / process / http / fetch / console | 全局宿主模块 | 直接调用,见 §6 |
alert / confirm / openFile | gx/dialog | import { 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) |
- controls 必须写成第二个元素:
const [data, res] = createResource(f)。 引擎不支持数组解构里嵌对象模式,所以不要照抄 Solid 的const [data, { refetch }] = …。 - error 态下
data()不抛异常:返回上一次的值(从未成功过则undefined),错误只从res.error()读。 这样做是因为 v1 没有 ErrorBoundary,抛出去会冒泡进任意 effect。 state()/error()不挂在data函数上 (本引擎函数值不带属性),都在res上。- fetcher 返回非 Promise(同步值)时按"立即可用"处理;不做 source signal 自动重取,需要联动就用
createEffect手动串。 - 连续性有保证:每次取数递增 token,回来的响应 token 不符直接丢弃(latest-wins),快速连点 refetch 不会让旧响应盖掉新状态。
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 的 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>
);
- 没有 URL,也没有 history 模式:桌面应用没有地址栏,"历史"是内存里的一个栈;deep-link 用
process.argv解析后传给initial。 - 正则路径约束 /
alias不做,参数校验写在beforeEnter里。 - 状态保留两档:路由记录
keepAlive: true保住整棵子树(滚动位置 / 焦点 / 草稿),useRouteState()只存值。保活页常驻内存,只给真正需要的页开。 - 默认绑定
Alt+←/Alt+→;实现是包装根节点脚本自己的onKeyDown(两层都跑),backKeys: false可关。 - 多窗口是作用域:窗口自动作用域是
win:N;<RouterView scope="x">用具名作用域,此时句柄指认不到它,要用router.sync([wa, "x"])。 - 完整手册:docs/gui-router.md(含
createRouter全部选项与守卫表)。
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?) => getter | screenOf 的响应式版 |
| useScreens | () => getter | screens() 的响应式版 |
| 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 宽的折痕 —— 这是最容易踩的一处命名不一致。
- 桌面后端没有姿态查询 API(Windows 无 WinRT ⇒ 零 cgo 不可达),框架不猜姿态: 只提供上报通道,没人上报就恒为平展。
- 折痕不随姿态清除:折痕是设备几何,不是姿态的属性。回到
flat时折痕留着, 否则"折回去再折回来"分栏比例会变成 0.5。是否分栏由姿态决定,折痕只决定"怎么分"。 - 上报一块表里没有的屏时:第一次上报且后端枚举为空 ⇒ 换掉整张表(宿主的显示环境由它定义); 已经有过上报或后端能枚举 ⇒ 追加一块。
- 分割比例的分母是显示器长度,不是折痕长度。
- 半折时
<RouterView>自动变双栏(左栏放历史的上一条),见 gx/router。
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");
- 只有这三个 API:无自定义按钮、无多选、无选目录。
- 模态期间界面仍会重绘(系统替我们泵消息),但不派发任何 JS 回调。
- 非 Windows 后端会降级:内容打到 stderr 并立即返回 ——
confirm取 true、openFile取 null(视作已取消)。 - 这个模块不依赖元素树,只依赖"当前有没有窗口",所以从
gx/gfx拆了出来。
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 }
- 全部同步 API,无 Promise —— 本地小文件读写,不需要异步仪式。
- 单文件
storage.json整读整写,临时文件 + rename 原子替换;文件损坏按空存储处理并打告警,应用照常起。 - 存函数 / 循环引用会在写入时抛
TypeError(而不是静默存成 null 读不回来)。 GOX_STORAGE_DIR环境变量可整体替换根目录(测试隔离 / 便携部署)。
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}] —— 最近若干条内核警告(含未知标签与指令误用的去重警告) |
- 拉取式:不推送,面板自己用
setInterval拉(示例 1s)。 别用requestAnimationFrame—— 会和真实渲染抢帧。 - 一次调用返回整棵 JSON 形状的纯对象,构建在调用线程内联完成(脚本线程就是 GUI 线程)。
- 字段名是 API,结构有专门用例锁住,可以放心当数据源用。
- 生产零成本:不 import 就没有这条代码路径(模块惰性构建)。
- 可运行的调试面板见演示脚本
testdata/dev_panel_demo.js。
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 为负) |
- 异常对象同时带
errCode+errMsg(判断用)与name+message(打印用),都是普通对象(当Error用也能读.message)。 - 拉取型对象名是
<能力>.<动作>(例如camera.takePhoto),能力 ID 就是第一个点之前那段 ——canIUse的判据也是它。
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";
appState()/useAppState():"active"/"background"/"inactive"(词表已归一化)。onBackPress(fn):返回键。回调返回真值 = 已处理,宿主据此决定要不要关界面。share(opts)/exitApp()/setOrientation(o):分享、退出、屏幕方向(桌面宿主未实现后者)。- 三个
reportXxx是上报口;onBackPress在“脚本返回真值”与“宿主主动上报”两种通道下的优先级有专用用例锁住。
gx/geo — 定位(10 个导出)
import {
getLocation, watchLocation, clearWatch, clearAllWatches,
lastLocation, useLastLocation, hasLocation,
distanceBetween, locationPlatform, reportLocation,
} from "gx/geo";
getLocation(opts)取一次,watchLocation(fn)持续监听并返回停止函数(宿主进程级会话,clearAllWatches()一次清完)。lastLocation()/hasLocation()读最近一次得到的位置;distanceBetween(a, b)走 haversine,返回米。- 桌面上“没有定位”是诚实的缺失:
getLocation()报unavailable,而不是编一个坐标出来。
gx/media — 相机与相册(8 个导出)
import {
takePhoto, chooseImage, chooseOneImage, chooseVideo,
saveImage, previewImage, mediaInfo, humanSize,
} from "gx/media";
takePhoto({count})/chooseImage({count})多张时返回数组,chooseOneImage()只要一张(返回单个对象)。- 用户取消走
cancelled错误码( 不是null),与gx/dialog.openFile的取消语义不同的原因在这里。 mediaInfo()列举当前平台可用的能力;humanSize(bytes)是纯函数(字节数 → 可读字符串)。
gx/permission — 权限(10 个导出)
import {
checkPermission, authorize, requestPermissions, openAppSettings,
getSetting, permissionState, permissionKinds,
onPermissionChange, offPermissionChange, reportPermission,
} from "gx/permission";
checkPermission(kind)查状态,authorize(kind)申请单个,requestPermissions(kinds)批量,openAppSettings()跳到应用设置页。permissionKinds()给出平台词表(宿主可报的权限类型)。onPermissionChange(fn)订阅状态变化(用户去设置页开完回来会触发)。
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";
- 与
gx/screen分工:前者答“我这台设备是什么样”(显示器 / 姿态 / 折痕),后者答“我这个窗口被怎么摆”(安全区 / 键盘 / 分屏)。 insets()/keyboardHeight()/splitInfo()全部靠宿主上报,桌面拿不到这些值(默认全 0 / 非分屏)。useInsets()/useViewport()同样返回取值函数,要再调一次。safeAreaStyle(v, withKeyboard?)直接给出可用于padding的四边值;第二个参数为true时把键盘高度也算进下边距。
桌面上的行为(不要把它当移动端用)
- 能真实给出的就给真值:电量、网络、亮度、屏幕常亮、打开系统设置页、震动(软降级)。
- 给不出的一律明说:相机 / 定位 / 相册 / 权限
reject报unsupported或unavailable,不返回假数据。 - 移动端接入时只需实现同一个宿主契约(新增能力 = 内核加一个方法名 + 宿主加一个分支),不必改内核。语义与用法详见 GUI 开发指南 §9.6。
模块层常见误用速查
| 现象 | 原因与解法 |
|---|---|
用了 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 定时器实现),不是全局函数 |
平台能力差异
| 能力 | Windows | Linux (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,后者是元素级指令) |
最直接的办法是在 REPL 里问一句:typeof someName
—— 得到 "undefined" 就是没有。
想列一个模块的全部导出,用命名空间导入 + Object.keys:
import * as s from "gx/solid"; Object.keys(s)。
完整的实现级说明见
JavaScript Runtime API 实现教程。