桌面开放能力调用说明

概述

应用能力调用是 UGOS 桌面系统提供的一套标准化公共能力接口,允许各个应用通过统一的方式调用桌面级的功能和服务。这些能力包括文件操作、任务中心、系统信息获取、用户界面交互等,极大地简化了应用开发流程。

模块来源

• 调用模块: cloudWindow (来自 ugos-core)

核心特性

• 标准化接口: 所有能力调用均采用统一的 Promise 方式
• 类型安全: 提供完整的 TypeScript 类型定义
• 错误处理: 统一的错误处理机制
• 跨应用通信: 支持应用间的能力共享

基本使用

引入依赖

// 或者
import cloudWindow from '@ugreen-nas/core/cloudWindow'

标准调用方式

// 基本调用模式
cloudWindow.useCapacity(能力名称, {
    // 能力所需参数
}).then((result) => {
    // 处理能力调用的返回结果
    console.log('调用成功:', result)
}).catch((error) => {
    // 统一错误处理
    console.error('调用失败:', error)
})

使用 async/await

async function callCapacity() {
    try {
        const result = await cloudWindow.useCapacity(能力名称, {
            // 参数
        })
        console.log('调用成功:', result)
    } catch (error) {
        console.error('调用失败:', error)
    }
}

错误处理

当调用不存在的能力时,系统会返回标准错误对象:

cloudWindow.useCapacity(不存在的能力)
    .catch((error) => {
        // 返回标准错误对象: "xxxx not found"
        console.error(error.message)
    })

基础能力

openApp

通过 appId 打开应用或者链接，支持 Docker 应用等。

参数：options（data），完整属性列表如下。

参数名	类型	必填	说明
appId	string	是	应用 ID
data	any	否	传递给应用的数据。data.routerParamsPath 为字符串时会拼接到窗口 URL 后面
config	cloudWindowConfig	否	自定义窗口配置，参见 窗口配置说明
noAssembly	boolean	否	传入 WindowServer.wake 的第四参数，控制是否组data包裹

返回值：由 WindowServer.wake 解析成功结果或进入 catch 的错误。

addApiEncryptIgnore

添加包体加密 uglink 多通道白名单。

参数：string[]（需要加入白名单的接口路径列表）

返回值：boolean，false 表示该项已存在于白名单中

openAppCenterDetail

打开应用中心管理 / 详情（WindowServer.wakeToAppCenterManage）。

参数：

参数名	类型	必填	说明
appId	string	否	默认取调用方应用 ID
appCenterType	—	是	应用中心类型，与桌面实现一致

返回值：由 wakeToAppCenterManage 的 Promise 决议或拒绝。

令牌相关

getThirdToken

获取与账号/用户配置相关的第三方令牌及展示类配置

参数：无

返回值：对象，字段包括：

字段	说明
dateFormat	用户日期格式
timeFormat	用户时间格式
temperatureUnit	温度单位
third_token	本地配置的 third_token
lang	当前 i18n.locale

调用示例：

await cloudWindow.useCapacity('getThirdToken')

文件操作

getLocalPath

获取本地路径子目录。

参数：目录路径（string）

返回值：子目录列表

openLocalPath

打开本地路径。

参数：

参数名	类型	必填	说明
path	string	是	本地路径
openType	'openPath' | 'showFile'	是	'openPath' 直接打开；'showFile' 在文件管理器中显示

说明：也可直接传入路径字符串（不传 openType）。

返回值：boolean，表示操作是否成功

系统信息

getComputerUserFolder

获取本地电脑当前用户文件夹路径。

参数：无

返回值：用户主目录路径（string）

getComputerName

获取计算机名称。

参数：无

返回值：计算机名称（string）

getDeviceLocation

获取设备位置。

参数：无

返回值：设备位置（string），默认为 'China'

checkComputerPathExists

检查计算机路径是否存在。

参数：

参数名	类型	必填	说明
path	string	是	需要检查的路径

返回值：boolean，表示路径是否存在

实用示例

示例 1: 打开其他应用并传递数据

import { AppCapacity } from 'ugos-pro-types/capacity'

// 打开文件管理器并定位到指定路径
async function openFileManager(path: string) {
  try {
    const result = await cloudWindow.useCapacity('openApp', {
      appId: 'com.ugreen.filemgr',
      data: { path }
    })
    console.log('文件管理器已打开')
  } catch (error) {
    console.error('打开失败:', error)
  }
}

示例 2: 获取令牌

// 获取 NAS 令牌并调用 API
async function fetchNasData(endpoint: string) {
  try {
    const token = await cloudWindow.useCapacity('getThirdToken')
  } catch (error) {
    console.error('获取失败:', error)
    throw error
  }
}

注意事项

1. 权限检查: 某些能力需要特定的权限,调用前请确保应用具有相应权限
2. 错误处理: 始终使用 try-catch 或 .catch() 处理可能的错误
3. 超时控制: 可以通过第三个参数设置超时时间,避免长时间等待
4. 类型安全: 建议使用 TypeScript 并导入正确的类型定义
5. 平台兼容: 部分能力可能仅在特定平台（Windows/Mac）可用
6. 版本依赖: 某些新增能力需要特定版本的客户端/固件支持