系统能力与 API 接口

接入方式

curl -b "wanos_session=你的会话" http://设备IP/api/status
curl -b "wanos_session=你的会话" "http://设备IP/api/list?path=/"

常用能力

悬浮窗口 API

WanOS 可以在桌面托管第三方应用的小窗口。应用不需要直接修改桌面 DOM，就能打开、更新、聚焦、列出或关闭一个系统悬浮 iframe。

window.WanOS.openFloatWindow({
  id: "download-tasks",
  title: "Download Tasks",
  url: "/apps/downloader/tasks",
  width: 420,
  height: 560,
  x: "right",
  y: "bottom",
  resizable: true
});

iframe 应用也可以用 postMessage 调用同一能力，消息类型为 wanos:float-window:open。结果消息为 wanos:float-window-result 或 wanos:float-window-error。

系统文件预览 API

第三方应用可以把 NAS 文件路径交给 WanOS，由系统统一打开图片预览、视频播放器、音频播放器、PDF 或文本预览。比如下载器下载完成后，可以直接调用系统视频预览播放视频。

window.parent.postMessage({
  type: "wanos:preview-file",
  requestId: "preview-1",
  path: "/mnt/wanos/mmcblk0p1-tf/downloads/demo.mp4",
  name: "demo.mp4"
}, "*");

桌面壁纸 API

第三方壁纸应用可以把已保存到 NAS 的图片交给 WanOS 设为桌面壁纸。接口会校验路径、文件存在和图片格式，支持 PNG、JPG、WebP、GIF。

window.parent.postMessage({
  type: "wanos:set-wallpaper",
  requestId: "wallpaper-1",
  path: "/mnt/wanos/mmcblk0p1-tf/wallpapers/demo.jpg"
}, "*");

应用商店详情打开 API

第三方页面、系统广告和壁纸应用可以直接打开 WanOS 应用商店，并定位到指定应用详情页。

window.WanOSAppStore.openAppDetail("wanos-wallpaper");

// 或直接访问：
http://设备IP/?store_app=wanos-wallpaper

应用公网访问能力

应用商店应用可以声明支持公网访问。用户在桌面或应用导航里右键应用时，WanOS 会显示“公网访问”；开启成功后系统保存公网地址，下次右键直接显示“复制公网链接”。

{
  "id": "demo-web-app",
  "name": "示例网页应用",
  "port": 8787,
  "path": "/",
  "public_access_supported": true,
  "public_access": true
}

fetch("/api/tunnel/app-domain", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    app_id: "demo-web-app",
    app_name: "示例网页应用",
    port: "8787"
  })
});

公网访问依赖 WanOS 远程访问能力。用户需要先在“远程访问”里开通内网穿透；未声明公网能力的普通应用不会显示右键公网菜单。

应用文件选择能力

第三方应用在 WanOS 弹窗 iframe 内可以通过 postMessage 调用系统 NAS 文件选择器，统一实现离线包导入、保存目录选择、媒体目录选择等能力。

window.parent.postMessage({
  type: "wanos:pick-file",
  requestId: "pick-video-1",
  title: "选择视频文件",
  hint: "请选择要处理的视频文件",
  startPath: "/mnt",
  fileType: "video"
}, "*");

window.addEventListener("message", event => {
  const data = event.data || {};
  if (data.type === "wanos:pick-result" && data.requestId === "pick-video-1") {
    console.log("用户选择的文件：", data.path);
  }
});

window.parent.postMessage({
  type: "wanos:open-file-location",
  requestId: "open-location-1",
  path: "/mnt/wanos/mmcblk0p1-tf/downloads/demo.mp4"
}, "*");

回调消息为 wanos:open-location-result 或 wanos:open-location-error。路径会限制在 /mnt、/media、/.vol、/srv、/opt/wanos-data/apps 等 WanOS 安全目录内。

完整接口清单

以下列表由当前 WanOS 后端路由生成。带 /api/remote/ 的远程兼容别名未重复列出，对应短路径接口可直接在本机使用。