组件参考

0先读:五个共同约定

下面每个组件只说自己的差异,但这五条对所有组件都成立。先理解它们,后面的表格会好读很多。

① 导入方式

JSX 需要 h 在作用域里,所以每个 GUI 脚本都要从 gx/gfx 引入它; 响应式信号来自 gx/solid:

import { createSignal } from "gx/solid";
import { h, render } from "gx/gfx";

JSX 标签在编译期被降级成 h(tag, props, ...children) 调用,所以 h 是必须导入的 —— 哪怕你一次都没显式调用它。也可以用 h() 手写树,与 JSX 完全等价。

② 响应式:传函数就是绑定

任何 prop 或文本子节点,只要传函数,就会被包成 effect:函数体里读到的 signal 变化时, 这个值自动重新求值并标脏该区域。

<text>{"静态文本"}</text>                 // 固定值,永不更新
<text>{() => `count: ${count()}`}</text>   // 函数 → 响应式绑定

<rect width={200} />                      // 固定宽
<rect width={() => count() * 20} />       // 宽度跟随 count

③ 受控组件:显示只看 prop,编辑只派发事件

所有输入类组件(input / textarea / select / slider / checkbox / radio / switch / progress / dialog)都不存自己的状态。 它们显示什么完全由 prop 决定,用户操作只派发回调。

// 正确:onInput 里把值写回 signal,显示才会变
<input value={() => name()} onInput={(e) => setName(e.value)} />

// 错误:不回写 → 敲键盘没反应(显示永远来自 value prop)
<input value={() => name()} onInput={(e) => console.log(e.value)} />

滑块不回写会"弹回原位",显示"拖不动";输入框不回写则"打字没反应"。这与 DOM 受控组件的语义一致。

④ 尺寸与颜色的写法

尺寸只接受整数像素,没有百分比、没有 min/max-width (滑块自己的 min/max 是取值范围,不是 CSS 尺寸)。 颜色支持命名色与 #rgb / #rgba / #rrggbb / #rrggbbaa / rgb() / rgba(),其中 alpha 可写 0~255 或 0~1。

⑤ 未知标签会被警告

h() 对标签名做白名单校验,集合外的标签会往 stderr 打印一次警告并渲染成普通盒子:

gfx: unknown tag "foo" (rendered as a plain box; see docs/gui-component-status.md)

这是刻意设计的 —— 没登记的组件此前会静默渲染成空白,最难排查。看到这行警告就说明标签名拼错了或用了未实现的组件。

1布局容器

布局原语只有两个方向,加上滚动、分隔与占位,共 4 组。

唯一的两个真布局容器。子元素按主轴依次排列(column 纵排、row 横排), 交叉轴可按 alignItems 对齐。尺寸未显式给出时按内容自适应。

子元素可写 flexGrow(number)吃主轴的富余空间 —— 配合 <spacer flexGrow={1}/> 可以把两侧元素推到两端。注意 stretch 会让无固有尺寸的子元素占满交叉轴,而内置控件(按钮、输入框等)保持自己的内容尺寸。

<column gap={12} padding={16}>
  <text font={18}>标题</text>

  <!-- 横向排列,垂直居中 -->
  <row gap={8} alignItems="center">
    <rect width={10} height={10} background="#27ae60" />
    <text>一行内容</text>
  </row>

  <!-- 两端对齐:spacer 吃掉中间所有空余 -->
  <row>
    <rect width={80} height={24} background="#c0392b" />
    <spacer flexGrow={1} />
    <rect width={80} height={24} background="#27ae60" />
  </row>
</column>

• 无 flexWrap、alignSelf、flexShrink、order。
• 没有 grid:复杂栅格要靠嵌套 row + 固定宽度模拟。

纵向滚动容器:内容超出视口时可滚轮滚动,右侧自动出现 8px 轨道 + 比例滑块。 绘制裁剪与命中裁剪共用同一个视口 —— 滚出视口的行既画不出来也点不中,不会出现"看不见却点得到"的幽灵点击。

const rows = [];
for (let i = 0; i < 20; i++) {
  rows.push(
    h("rect", { height: 36, background: i % 2 ? "#eef2f7" : "#ffffff" },
      h("text", { font: 13 }, `row ${i}`))
  );
}

<scroll width={240} height={120} onWheel={(e) => log(`overscroll ${e.deltaY}`)}>
  {rows}
</scroll>

• 只支持纵向滚动;横向滚动与滚动条鼠标拖拽 v1 未实现(只能滚轮或脚本改 offsetY)。
• 没有虚拟化:20 行就挂 20 个节点,长列表请自行只挂可见区间。
• 滚轮遵循 DOM 滚动链语义:先在容器内消费,到边界才冒泡。

1px 分隔线。横向时高度固定 1px、宽度由容器 stretch 拉满;加 vertical 后变成 1px 宽的竖线。

<text>上半区</text>
<separator />
<text>下半区</text>

弹性占位:零固有尺寸、零绘制,专门用来吃主轴的富余空间。最常见的用法是"把两个元素推到两端"。

<row>
  <text>左</text>
  <spacer flexGrow={1} />
  <text>右</text>
</row>

矩形色块,也是最通用的"盒子":填充 background、描边 border, 宽高常用来做色条、分隔块、仪表底色。点击区域、右键菜单等交互常直接挂在它上面。

<rect width={80} height={24} background="#c0392b" />

{/* 宽度绑定信号 → 做进度色条 */}
<rect height={12} background="#c0392b" width={() => vol() * 1.6} />

{/* 带事件的面板 */}
<rect width={340} height={140} background="#e8eef7"
      onContextMenu={(e) => openContextMenu(e.x, e.y, items)} />

2表单控件

全部是受控组件,显示只看 prop,交互只派发回调(见第 0 节约定 ③)。

按钮。尺寸按内容自适应(文本 + 8px 左右内边距),文本垂直居中;自带悬停提亮与按压压暗反馈。

<button onClick={() => setCount(c => c + 1)}>默认按钮</button>

<button
  background="#1a5fb4"
  border="#1a5fb4"
  color="#ffffff"
  onClick={() => setCount(c => c + 1)}
>自定义配色</button>

<button disabled={true} onClick={() => setCount(c => c + 100)}>禁用按钮</button>

三个布尔开关控件。勾选框 18×18,开关 36×20(方形轨道 + 16×16 滑块),单选框是 1px 圆环 + 中心实心点。 三者都不自带任何状态 —— 勾上还是不勾,完全由 checked prop 决定。

const [agree, setAgree] = createSignal(false);
const [size, setSize] = createSignal("S");
const [notify, setNotify] = createSignal(true);

<row gap={8} alignItems="center">
  <checkbox checked={() => agree()} onClick={() => setAgree(v => !v)} />
  <text>{() => (agree() ? "Agreed" : "Not agreed")}</text>
</row>

<!-- 互斥靠"共享 signal + 比较值" -->
<row gap={14} alignItems="center">
  <row gap={4} alignItems="center">
    <radio checked={() => size() === "S"} onClick={() => setSize("S")} />
    <text>S</text>
  </row>
  <row gap={4} alignItems="center">
    <radio checked={() => size() === "M"} onClick={() => setSize("M")} />
    <text>M</text>
  </row>
</row>

<row gap={8} alignItems="center">
  <switch checked={() => notify()} onClick={() => setNotify(v => !v)} />
  <text>{() => (notify() ? "Notifications on" : "Notifications off")}</text>
</row>

单行文本输入。获焦时边框转蓝并出现闪烁竖线光标;点击框内任意位置可把光标落到最近的字符边界。 支持 Backspace / Delete / ← / → / Home / End, 以及 Windows 上的中文输入法整批提交。

键盘归属

输入框只消费编辑类按键;其余一律放行给上层,这样"输入框放在对话框里按 Esc 关掉"能照常工作。

const [name, setName] = createSignal("");
const [enters, setEnters] = createSignal(0);

<input
  width={260}
  placeholder="Type your name"
  value={() => name()}
  onInput={(e) => setName(e.value)}
  onKeyDown={(e) => {
    if (e.key === "Enter") setEnters((n) => n + 1);
  }}
/>

function tick() { requestAnimationFrame(tick); }
tick();

• 无选区/拖选/复制粘贴按键(剪贴板要走 gx/gfx 的同步 API 手动接)。
• 单字符直输路径只认 BMP;中文等需经输入法提交通道(Windows 已支持,X11 暂无 IME)。
• 输入法提交不产生 onKeyDown —— 统计"敲了几次键盘"不能用它代替。

多行文本编辑。光标是二维的 {行, 列},内容超出可视高度时纵向滚动,并且滚动跟随光标 (在最后一行回车时不会把光标顶出框外)。

const [text, setText] = createSignal("");

<textarea
  rows={4}
  width={260}
  placeholder="Type here..."
  value={() => text()}
  onInput={(e) => setText(e.value)}
  onKeyDown={(e) => {
    if (e.key === "Escape") closeDialog();
  }}
/>

• 不做软换行:超长行被右侧裁掉,而不是折到下一行 —— 换行只由 \n 决定,这样"光标行号"与文本严格一一对应。
• 无选区、无撤销栈、无横向滚动。

下拉框。点击展开选项弹层(自带逃逸裁剪,不会被 28px 的字段盒裁剪,也不会被后面的兄弟节点盖住), 支持键盘开合与移动高亮。

键盘操作:获焦后 Enter / Space 展开, ↑ / ↓ 移动高亮(环绕),Enter 选中, Esc 收起。

const CITIES = [
  { value: "sh", label: "Shanghai" },
  { value: "bj", label: "Beijing" },
  { value: "sz", label: "Shenzhen" },
];

const [city, setCity] = createSignal("sh");

<select
  width={220}
  options={CITIES}
  value={() => city()}
  onChange={(e) => setCity(e.value)}
/>

<!-- 也支持纯字符串数组 + placeholder -->
<select
  width={220}
  placeholder="Pick a fruit"
  options={["apple", "banana", "cherry"]}
  value={() => fruit()}
  onChange={(e) => setFruit(e.value)}
/>

滑块。拖动滑块或单击轨道任意位置跳值都会更新;拖动期间鼠标捕获由后端提供,拖出窗口仍然跟手。

const [vol, setVol] = createSignal(40);

h("slider", {
  width: 200, min: 0, max: 100, step: 5,
  value: () => vol(),
  onInput: (e) => setVol(e.value),     // e.value 直接当数字用,不用 parseFloat
}),

// 数值只会落在 0/2/4/6/8/10 上
h("slider", { width: 200, min: 0, max: 10, step: 2,
  value: () => zoom(), onInput: (e) => setZoom(e.value) }),

// 禁用态
h("slider", { width: 200, min: 0, max: 100, step: 5, value: 70, disabled: true })

• 无纵向滑块、无双端 range、无刻度/数值标签、无键盘微调(←/→)。
• 拖动是独占手势:期间鼠标划过别的控件不会给它们加悬停高亮。
• 量程异常值会被安全处理:max < min 塌缩到 min,NaN 不污染几何。

3内容展示

文本。它是文本块唯一载体 —— JSX 里的裸字符串子节点会变成隐式的 #text 节点, 而 #text 永远是单行的。想折行必须用 <text> 并开 wrap。

<text font={20}>{() => `count: ${count()}`}</text>

<!-- 折行:给宽度,或者放在 column 里靠 stretch -->
<text wrap width={260} font={12}>
  {() => `value = "${text()}"`}
</text>

<!-- 最多两行,超出显示省略号 -->
<text wrap ellipsis={2} width={200}>{longDescription}</text>

图片显示。用 Go 标准库解码 PNG / JPEG / GIF(不引入新依赖),挂载时同步解码并带 16 项 LRU 缓存。

<image src="testdata/image_demo.png" />                    {/* 自然尺寸 */}
<image src="testdata/image_demo.png" width={96} height={96} />  {/* 最近邻放大 */}
<image src="testdata/missing.png" width={96} height={48} />     {/* 失败:灰底 + 交叉线 */}

• 路径按进程工作目录解释,不是"脚本所在目录"(脚本可能来自 stdin / 字符串 / 打包产物,没有所在目录这个概念)。从仓库根运行演示脚本时可写 testdata/xxx.png。
• 不支持网络 URL、无异步加载、无缩放质量选项(总是最近邻)。
• 加载失败画灰底 + 45° 交叉线占位,并每个路径只往 stderr 警告一次,不影响其它内容。

进度条。value 取 0~1(自动钳位),缺省 200×8,轨道浅灰 + 前景绿。

// 用整数步进(0..10)而不是浮点累加,避免 0.30000000000000004 这类误差
const [step, setStep] = createSignal(0);
setInterval(() => setStep(s => (s >= 10 ? 0 : s + 1)), 400);

<progress value={() => step() / 10} />
<text>{() => `value: ${step() * 10}%`}</text>

4反馈与弹层

这一类的标签自带弹层层级基线(overlayZBase),会自动逃逸祖先裁剪,不需要手动写 escapeClipping。

模态对话框:40% 黑遮罩铺满窗口 + 居中卡片。流内子节点就是卡片内容, 卡片之外的区域属于遮罩。遮罩存在时会吞掉其下所有点击。

const [open, setOpen] = createSignal(false);

<button onClick={() => setOpen(true)}>Open dialog</button>

<dialog open={() => open()} onClose={() => setOpen(false)}>
  <column gap={8} padding={14}>
    <text font={16}>Confirm</text>
    <text>Click the mask or press Esc to close.</text>
    <button onClick={() => setOpen(false)}>Close</button>
  </column>
</dialog>

轻提示:固定在窗口右上角,非模态(它下面的内容照常可点)。挂在树上就显示,挂载/卸载完全由 JS 控制, 内核不管定时器。

const [showToast, setShowToast] = createSignal(false);

const notify = () => {
  setShowToast(true);
  setTimeout(() => setShowToast(false), 3000);   // 自动消失靠 JS 定时器
};

{() => (showToast() ? <toast message="Saved successfully" level="success" /> : null)}

调起操作系统原生的消息框与文件选择框,而不是自绘弹层。三个 API 都返回 Promise。

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

import { alert, 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 path = await openFile({
      title: "Pick a file",
      filter: [
        { name: "Text files", pattern: "*.txt;*.md" },
        { name: "All files", pattern: "*.*" }
      ]
    });
    log(path === null ? "cancelled" : "picked " + path);
  }
}, "Open file")

• 只有这三个 API:无自定义按钮、无多选、无选目录。
• 模态期间界面仍会重绘(系统替我们泵消息),但不派发任何 JS 回调。
• 非 Windows 后端会降级:内容打到 stderr 并立即返回 —— confirm 取 true、openFile 取 null(视作已取消)。

5导航与菜单

自绘菜单栏 + 下拉菜单 + 子菜单。支持互斥展开、点击外部关闭、键盘导航,菜单项可挂全局快捷键。

<column>
  <menubar>
    <menu label="File">
      <menuitem label="New"  shortcut="Ctrl+N" onClick={() => say("New")} />
      <menuitem label="Open" shortcut="Ctrl+O" onClick={() => say("Open")} />
      <separator />
      <menuitem label="Save As" disabled={true} onClick={() => say("不该被触发")} />
    </menu>

    <menu label="View">
      <menuitem label="Zoom In" onClick={() => say("Zoom In")} />
      <!-- 子菜单:在 menuitem 里再嵌一个 menu -->
      <menuitem label="Theme">
        <menu>
          <menuitem label="Dark"  onClick={() => say("Dark")} />
          <menuitem label="Light" onClick={() => say("Light")} />
        </menu>
      </menuitem>
    </menu>

    <text>ready</text>    {/* menubar 是普通容器,右侧放什么都行 */}
  </menubar>

  <column gap={12} padding={16}>
    {/* 窗口主体内容 */}
  </column>
</column>

快捷键规则

快捷键表在 Go 侧(Pump 层)匹配 —— 因为 JS 看不到已被输入框消费的按键。规则:

• 只认带 Ctrl / Alt 的组合。shortcut="S" 这种裸字母键不会被受理(否则全应用都打不出 s)。
• 修饰键全等比较:Ctrl+S 不会被 Ctrl+Shift+S 触发。
• Cmd 自动归一到 Ctrl。
• 菜单项没有 onClick 也可以挂 shortcut,只是命中后无事发生。

键盘导航

焦点在菜单栏时:← / → 在标题间循环切换(换过去就展开), ↓ / Enter / Space 展开, Esc 收起当前层。

• 无鼠标滑过切换标题、无悬停自动展开子菜单、无勾选项(checked menu item)。
• 分隔线本身也能命中(命中测试只认带处理器的节点,所以每一行都挂了内置处理器)。

在指定坐标就地弹出右键菜单。这是数据式 API,不是 contextMenu prop —— 理由见下方提示。

import { h, render, openContextMenu } from "gx/gfx";

<rect
  width={340}
  height={140}
  background="#e8eef7"
  onContextMenu={(e) =>
    openContextMenu(e.x, e.y, [
      <menuitem label="Copy"    shortcut="Ctrl+C" onClick={() => say("Copy")} />
      <menuitem label="Paste"   shortcut="Ctrl+V" onClick={() => say("Paste")} />
      <separator />
      <menuitem label="Inspect" onClick={() => say("Inspect")} />
    ])
  }
/>

行为:靠近屏幕右下角时会自动向左上翻折保证整块可见;点选项或点外部关闭;在菜单上再点右键会被吞掉(不会误关)。

6媒体与自绘

自绘画布。在 onDraw(ctx) 里用 7 个原语直接落笔,坐标是画布局部坐标 (0,0 就是画布左上角),越界部分自动裁掉,不会溢出到界面其它地方。 在 onDraw 里读到的 signal 变化会自动触发重绘。

ctx 提供的能力

const [tick, setTick] = createSignal(0);
const DATA = [4, 7, 3, 8, 5, 9, 6, 2];

const chart = h("canvas", {
  width: 246, height: 110,
  onDraw: (ctx) => {
    // 读到 tick() → 订阅它,变化时自动重绘
    const cur = tick() % DATA.length;
    ctx.fillRect(0, 0, ctx.width, ctx.height, "#fafafa");
    ctx.line(0, 96, ctx.width - 1, 96, "#cccccc");
    ctx.drawText("bars " + DATA.length, 4, 2, 12, "#555555");
    for (let i = 0; i < DATA.length; i++) {
      const bh = DATA[i] * 8;
      const x = 6 + i * 30;
      ctx.fillRect(x, 96 - bh, 24, bh, i === cur ? "#c0392b" : "#7f8c8d");
    }
  },
});

setInterval(() => setTick(tick() + 1), 500);

onDraw 每次依赖变化会执行两遍(一遍用空操作 ctx 收集依赖、一遍用真 ctx 落笔), 所以它必须是纯绘制函数 —— 别在里面改状态、别做耗时计算、也别把 signal 读取藏在 if (ctx.width > 0) 之后(依赖收集时尺寸可能还是 0,那条分支不跑就收不到订阅)。

• 无路径 / 变换 / 渐变 / 抗锯齿开关 / 可调线宽 / drawImage。
• 无内置帧循环:动画要自己挂 requestAnimationFrame。
• 7 个原语都是"最后一笔覆盖"的即时绘制,没有图层与合成模式。

7横切能力与模块 API

来自 gx/solid 的三个 API,是"界面为什么会更新"的答案。

函数子节点是列表渲染与条件渲染的统一入口:求值结果可以是元素、数组、标量或 null/false(渲染为空)。

const [items, setItems] = createSignal(["alpha", "beta"]);
const [tab, setTab] = createSignal(0);

// 列表渲染:函数返回数组,逐元素挂载
<column gap={6}>
  {() => items().map((t) => <text>{t}</text>)}
</column>

// 条件渲染:函数返回元素 或 null
{() => (tab() === 0 ? <text>面板 A</text> : <text>面板 B</text>)}

// 静态数组子节点也支持:直接写 {rows} 会逐个展开成兄弟节点
<scroll height={120}>{rows}</scroll>

所有事件都是"沿祖先链找第一个处理器",找到就停 —— 不冒泡、无捕获、无 stopPropagation。

useWindowSize:拖窗口自适应

// onResize 只认布局根;断点是脚本里的普通 memo,不烧进内核
const [win, setWin] = createSignal({ width: 520, height: 360 });
const wide = createMemo(() => win().width >= 480);

<window title="app" width={520} height={360}>
  <column onResize={(e) => setWin({ width: e.width, height: e.height })}>
    {() => (wide() ? <Sidebar /> : <text font={12}>(narrow)</text>)}
  </column>
</window>

焦点模型:点击任意节点即成为键盘焦点,焦点节点会画 1px 蓝色虚线框。 disabled 子树不响应任何事件、也不参与焦点切换。Tab 键遍历 v1 未实现,焦点只能靠鼠标点击切换。

<rect
  width={380} height={110} background="#eef3f8"
  onClick={() => setLast("click")}
  onMouseMove={(e) => setPos(`${e.x}, ${e.y}`)}
  onWheel={(e) => setLast(`wheel deltaY=${e.deltaY}`)}
  onContextMenu={(e) => setLast(`context menu at ${e.x}, ${e.y}`)}
  onKeyDown={(e) => setLast(`keydown ${e.key}`)}
>
  <text>click to focus, then move / scroll / right-click / type</text>
</rect>

控制谁盖在谁上面、以及元素脱离常规流。三组 prop 各管一件事。

{/* 覆盖层:绝对定位于父内容区左上角 */}
<rect position="absolute" left={12} top={8} width={100} height={20} background="#f2c94c" />

{/* 自定义弹层:溢出父盒显示必须加 escapeClipping */}
<column position="absolute" top={30} escapeClipping={true}>
  <text>浮在外面</text>
</column>

动画不是某个组件,而是一条可以挂在任何节点上的横切能力:值变化时在给定时长内按 ease-out 平滑逼近。

声明式 transition 只认这五个数值属性: width / height / left / top / opacity。

// 宽度过渡:切换时在 400ms 内平滑伸展/收缩
h("rect", {
  height: 18,
  background: "#2f80ed",
  transition: { width: 400 },
  width: () => (wide() ? 300 : 60)
}),

// 成组淡出:父节点半透明 = 整棵子树一起淡
h("row", {
  gap: 6, height: 28,
  transition: { opacity: 350 },
  opacity: () => (visible() ? 1 : 0.15)
},
  h("rect", { width: 24, height: 24, background: "#c0392b" }),
  h("text", { font: 12, width: 80, height: 24 }, "fading")
),

// 命令式:自己拿插值,onUpdate 每帧(~60fps)调用
h("button", {
  onClick: () => {
    animate(0, 100, 600,
      (v) => setStatus("progress " + Math.round(v) + "%"),
      () => setStatus("done"));
  }
}, "bounce")

• 缓动曲线固定为 ease-out,不可自定义;无 keyframes、无 transition-delay。
• 颜色过渡 v1 不做。
• value / padding / gap / margin / flexGrow 刻意排除:前者的过渡会与脚本自己的受控写回打架,后者半像素中间值会让文字穿透。
• 静止时零开销(没有活动动画就不续表)。

除组件标签外,gx/gfx 还导出这些函数。

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"));

剪贴板(同步 API)

import { clipboardReadText, clipboardWriteText } from "gx/gfx";

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

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

应用级 kv 存储:值经 JSON 序列化落盘到用户配置目录,下次启动还在。

import { setAppName, setStorage, getStorage } 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
if (t === undefined) setStorage("theme", "light");

• 全部同步 API,无 Promise —— 本地小文件读写,不需要异步仪式。
• 单文件 storage.json 整读整写,临时文件 + rename 原子替换;文件损坏按空存储处理并打告警,应用照常起。
• 存函数 / 循环引用会在写入时抛 TypeError(而不是静默存成 null 读不回来)。
• GOX_STORAGE_DIR 环境变量可整体替换根目录(测试隔离 / 便携部署)。

render() 可以调用多次,每次都开一个独立窗口,返回句柄用于关闭。

const makeCounter = (title) => {
  const [n, setN] = createSignal(0);
  let self = null;

  self = render(
    <window title={`Multi-window ${title}`} width={380} height={340}>
      <column gap={12} padding={16}>
        <text font={22}>{() => `${title} count = ${n()}`}</text>
        <button onClick={() => setN(n() + 1)}>+1</button>
        <button onClick={() => self.close()}>Close this window</button>
      </column>
    </window>
  );
  return self;
};

const a = makeCounter("A");   // 两个窗口各有独立元素树、焦点与快捷键表
const b = makeCounter("B");

• 关掉其中一个,其余继续正常响应;全部关闭后进程才退出。
• 窗口之间不共享节点。想同步状态就共享同一个 createSignal(在脚本顶层建),不要指望 prop 自动串起来。
• 每个窗口是独立的 app 实例:悬停链、按压态、键盘焦点、快捷键表、弹层状态互不干扰。
• 关了"最近 Mount 的窗口"之后,剪贴板 / 原生对话框这类没有节点上下文的 API 会自动改指到幸存窗口。
• 无运行中改标题 / 尺寸、无窗口位置控制、无模态子窗口。

8全局限制与常见误区

语法层面的坑

行为层面的坑

未实现的组件(可用现有能力模拟)

平台差异一览