清单配置参考
package.json#jsos 字段完整说明
清单配置参考
应用清单存储在 package.json 的 jsos 字段中。
完整示例
{
"name": "my-app",
"version": "1.0.0",
"type": "module",
"dependencies": { "express": "^4.18.0" },
"jsos": {
"id": "my-app",
"name": { "en": "My App", "zh-CN": "我的应用" },
"description": { "en": "Description", "zh-CN": "应用描述" },
"type": "gui",
"icon": "data:image/svg+xml,...",
"startCommand": "node server.js",
"installCommand": "npm install",
"permissions": ["network"],
"defaultWidth": 900,
"defaultHeight": 600,
"minWidth": 400,
"minHeight": 300,
"allowMaximize": true,
"widgets": [...]
}
}
name和version未设置时自动从package.json顶层字段继承。
必填字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 应用唯一标识符(如 my-app) |
name | string / object | 显示名称(详见下方多语言说明) |
startCommand | string | 启动命令(如 node server.js) |
可选字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | "gui" | "cli" | "gui" | 应用类型 |
version | string | "1.0.0" | 版本号。按日期设置(如 2026.11.20,同日多次更新用 2026.11.20.1),详见版本规范 |
description | string / object | "" | 应用描述 |
icon | string | 自动生成 | 见下方图标说明 |
installCommand | string | "" | 安装命令 |
permissions | string[] | [] | 权限声明 |
defaultWidth | number | 900 | 窗口初始宽度 |
defaultHeight | number | 600 | 窗口初始高度 |
minWidth | number | 400 | 窗口最小宽度 |
minHeight | number | 300 | 窗口最小高度 |
allowMaximize | boolean | true | 是否允许最大化 |
terminal | boolean | false | 是否启用可读写终端 API(见下方说明) |
widgets | array | [] | 小组件配置数组 |
多语言(i18n)
name 和 description 支持国际化。widgets 数组中的 name 和 description 也同样支持:
{
"name": { "en": "File Manager", "zh-CN": "文件管理器" },
"description": { "en": "Browse and manage files", "zh-CN": "浏览和管理文件" },
"widgets": [
{
"id": "disk-info",
"name": { "en": "Shared Data", "zh-CN": "共享目录" },
"description": { "en": "Shared directory statistics", "zh-CN": "显示共享目录统计信息" }
}
]
}- 传字符串 → 所有语言显示相同
- 传对象 → 根据系统语言自动选择,fallback
en→ 第一个值
系统语言切换时,桌面图标、任务栏、窗口标题、小组件标题栏和添加弹窗等位置自动更新显示内容。
图标
| 方式 | 示例 | 说明 |
|---|---|---|
| 不设置 | — | 自动生成首字母彩色方块图标 |
| SVG Data URI | data:image/svg+xml,... | 推荐,直接嵌入 SVG |
| 本地文件 | icon.svg / icon.png | 引用应用包内文件 |
不支持网络链接(https://...)。由于安全策略限制,外部图片无法加载。
SVG Data URI 编码规则:
- 空格 →
%20 #→%23<→%3C>→%3E
小组件
详见 小组件开发。
{
"widgets": [
{
"id": "todo-list",
"name": "Todo List",
"description": "显示待办事项",
"cols": 3,
"rows": 5,
"url": "/#/widget/todo-list",
"icon": "icon.svg"
}
]
}
cols和rows是标准格式。旧格式"width": 320, "height": 480(像素值)和"size": "3x5"字符串仍受兼容支持,但不推荐在新应用中使用。
url可以是 hash 路径或普通路径,由应用的路由设计决定。
background字段控制小组件背景外观:"frosted"(磨砂玻璃,默认)、"transparent"(全透明)、"solid"(实色),或{ type, opacity, blur }完整对象格式。详见 小组件开发。
应用类型
GUI(默认)
"type": "gui"启动 Web 服务,iframe 显示界面。多开共享服务器和端口。
CLI
"type": "cli"直接在终端中运行。每次打开创建独立进程,关闭即终止。
可读写终端(terminal)
GUI 应用如需交互式终端能力(IDE、开发助手等),在 manifest 中声明 "terminal": true:
{
"jsos": {
"id": "dev.jsos.editor",
"terminal": true,
"startCommand": "node server.js"
}
}启用后窗口底部状态栏显示终端图标,可通过 window.JSOS.terminal.* API 创建、写入、关闭终端。详见 JSOS API 参考 - 终端。
未声明
terminal: true时调用 Terminal API 会返回错误。
端口分配
- GUI 应用从 4000 开始递增分配端口
- 同一应用每次启动使用相同端口
- 通过
process.env.PORT获取 - 端口分配持久化存储,跨 session 不变
示例
GUI 应用
{
"name": "todo-app",
"type": "module",
"dependencies": { "express": "^4.18.0" },
"jsos": {
"id": "todo-app",
"name": { "en": "Todo List", "zh-CN": "待办事项" },
"type": "gui",
"icon": "data:image/svg+xml,...",
"startCommand": "node server.js",
"installCommand": "npm install",
"defaultWidth": 800,
"defaultHeight": 500,
"widgets": [
{ "id": "todo-list", "name": "Todo List", "cols": 3, "rows": 5, "url": "/#/widget/todo-list" }
]
}
}CLI 应用
{
"name": "my-cli",
"type": "module",
"jsos": {
"id": "my-cli",
"name": { "en": "CLI Tool", "zh-CN": "命令行工具" },
"type": "cli",
"startCommand": "node index.js"
}
}