JSOS
开发指南

GUI 应用开发

开发带图形界面的 JSOS 应用

GUI 应用开发

GUI 应用通过 HTTP 提供服务,JSOS 用 iframe 加载显示。你可以使用任何能启动 HTTP 服务的 Node.js 框架。

生命周期

点击图标
  ↓
创建窗口 + 终端(后台)
  ↓
挂载文件到 WebContainer
  ↓
执行 installCommand(npm install)
  ↓
执行 startCommand(node server.js)
  ↓
服务就绪 → iframe 加载 URL
  ↓
关闭窗口 → 终止进程

启动过程中窗口显示 SplashScreen(应用图标 + 安装/启动状态);服务就绪后立即显示 iframe,页面在浏览器中渐进渲染。加载期间窗口底部状态栏显示 Loading page…,页面就绪后变为 Ready。

页面就绪以 DOMContentLoaded(而非全部资源加载完成)为准,因此图片、字体等仍在加载时不会阻塞界面显示。

窗口底部终端

GUI 窗口底部有一个可折叠的终端面板,显示应用的 stdout/stderr 输出。开发调试时可以展开查看 console.log 和错误信息。

可读写终端

如果应用需要交互式终端功能(如开发助手、IDE),可以在 manifest 中声明 "terminal": true 来启用可读写终端。

配置

{
  "jsos": {
    "id": "dev.jsos.editor",
    "terminal": true,
    "startCommand": "node server.js"
  }
}

启用后的效果

  • 窗口底部状态栏显示终端图标
  • 点击图标打开终端面板
  • 支持多 Tab,每个 Tab 独立运行进程
  • 可通过 window.JSOS.terminal.* API 控制终端

API 调用示例

// 启动应用时自动打开终端
async function handleStartApp() {
  await window.JSOS.terminal.show(true);
  await window.JSOS.terminal.spawn({
    command: 'node',
    args: ['server.js']
  });
}

// 安装依赖
async function handleInstall() {
  await window.JSOS.terminal.spawn({
    command: 'sh',
    args: ['-c', 'pnpm install']
  });
}

详细 API 参考请查看 JSOS API 参考 - 终端。

环境变量

应用启动时自动注入以下变量:

变量说明
PORT系统分配的端口号,用这个端口启动 HTTP 服务
DATA_DIR数据持久化目录,应用数据写在这里
APP_DIR应用代码目录
HOME用户主目录(wc.workdir)
LANG系统语言(zh-CN / en)
JSOS_VERSION系统版本号
PROXY_URLCORS 代理服务地址
PROXY_KEYCORS 代理 API Key(可选)

永远不要硬编码端口号,用 process.env.PORT 获取:

const port = process.env.PORT;
app.listen(port);

多开共享

同一 GUI 应用多次打开共享一个服务器。所有的窗口共享同一个 localStorage 和进程状态。

使用 JSOS API

GUI 应用的前端页面(iframe 中的浏览器环境)可以通过 window.JSOS 调用系统功能。参考 JSOS API 参考。

使用前端框架

你可以使用任何前端框架——React、Vue、Solid、Svelte,或者纯 HTML/CSS/JS。只需要确保构建产物能通过 HTTP 服务正确返回。

推荐: 使用 React + coss-ui 组件库可以让应用界面与系统 UI 更统一。coss-ui 与 JSOS 系统组件同源,提供按钮、对话框、菜单、输入框等组件,支持暗色/亮色主题自动切换。

框架构建产物(dist/ 目录)可以用 Express 静态文件中间件服务:

import express from 'express';
const app = express();
app.use(express.static('dist'));
app.listen(process.env.PORT);

也可以在 installCommand 中加入构建步骤:

"installCommand": "npm install && npm run build",
"startCommand": "node server.js"

自适应系统主题与语言

GUI 应用应监听系统的主题和语言变化,自动更新前端 UI,以保持与系统外观一致。

监听主题切换

window.JSOS.onThemeChange((theme) => {
  // theme: 'light' | 'dark'
  document.documentElement.classList.toggle('dark', theme === 'dark');
});

结合 coss-ui 时,主题切换会自动通过 CSS 变量生效,无需手动处理。

监听语言切换

window.JSOS.onLocaleChange((locale) => {
  // locale: 'zh-CN' | 'en'
  // 更新界面文案
});

应用启动时也可以通过 process.env.LANG 环境变量获取初始语言。建议在应用前端初始化时调用 getLocale() 获取当前语言,并通过 onLocaleChange 监听后续切换。

嵌入外部网页(COEP 限制)

应用页面由 WebContainer 提供,响应头带 Cross-Origin-Embedder-Policy: require-corp,因此普通 <iframe> 无法嵌入外部站点(浏览器会阻止加载)。

解决办法是给 iframe 加 credentialless 属性(Chrome 110+ 默认启用):

<iframe credentialless src="https://example.com"></iframe>
  • 该 iframe 会在全新的临时上下文中加载(无 Cookie / localStorage),卸载后清除,适合展示公开页面
  • 嵌套 iframe 会继承 credentialless 上下文
  • 站点自身的 X-Frame-Options / CSP frame-ancestors 仍会阻止嵌入,此时需要提供「在新标签页打开」的兜底入口
  • 内嵌的 JSOS 应用 URL(WebContainer 端口)本身带 Cross-Origin-Resource-Policy: cross-origin,可直接用普通 iframe 嵌入

内置浏览器(dev.jsos.browser)就是用这种方式嵌入外部页面的。

调试技巧

  • 窗口底部的终端面板会实时显示进程输出
  • 在应用代码中添加 console.log,输出会出现在终端面板
  • 检查 web 请求可以在应用代码中添加 express 中间件打印日志

On this page