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_URL | CORS 代理服务地址 |
PROXY_KEY | CORS 代理 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/ CSPframe-ancestors仍会阻止嵌入,此时需要提供「在新标签页打开」的兜底入口 - 内嵌的 JSOS 应用 URL(WebContainer 端口)本身带
Cross-Origin-Resource-Policy: cross-origin,可直接用普通 iframe 嵌入
内置浏览器(dev.jsos.browser)就是用这种方式嵌入外部页面的。
调试技巧
- 窗口底部的终端面板会实时显示进程输出
- 在应用代码中添加
console.log,输出会出现在终端面板 - 检查 web 请求可以在应用代码中添加 express 中间件打印日志