JSOS
参考

清单配置参考

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 顶层字段继承。

必填字段

字段类型说明
idstring应用唯一标识符(如 my-app)
namestring / object显示名称(详见下方多语言说明)
startCommandstring启动命令(如 node server.js)

可选字段

字段类型默认值说明
type"gui" | "cli""gui"应用类型
versionstring"1.0.0"版本号。按日期设置(如 2026.11.20,同日多次更新用 2026.11.20.1),详见版本规范
descriptionstring / object""应用描述
iconstring自动生成见下方图标说明
installCommandstring""安装命令
permissionsstring[][]权限声明
defaultWidthnumber900窗口初始宽度
defaultHeightnumber600窗口初始高度
minWidthnumber400窗口最小宽度
minHeightnumber300窗口最小高度
allowMaximizebooleantrue是否允许最大化
terminalbooleanfalse是否启用可读写终端 API(见下方说明)
widgetsarray[]小组件配置数组

多语言(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 URIdata: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"
  }
}

On this page