Skip to content

平台 API

微应用通过 this.spCtx.api 调用平台提供的各种能力。部分 API 是异步的(返回 Promise),部分 API 是同步的(直接返回值)。

IDE 类型提示

安装 @sun-panel/micro-app SDK 后,在 IDE 中输入 this.spCtx.api. 时会自动弹出类型提示和代码补全。

窗口管理

window.open

打开一个新窗口。

typescript
open(options: OpenWindowOptions): string

参数:

属性类型必填说明
componentNamestring组件名称(组件配置下 pages 的 key 名)
windowConfigWindowConfig-窗口配置,不填使用 默认配置
customParamany-自定义参数
titlestring-窗口标题

返回值: 窗口 ID(string 类型)

示例:

typescript
const windowId = this.spCtx.api.window.open({
  componentName: 'my-component',
  title: '天气详情',
  windowConfig: {
    width: 800,
    height: 600,
    isFullScreen: false
  },
  customParam: { cityId: 1001 }
});

主应用信息

获取主应用的基本信息,如版本号、PRO 状态等。后期可能扩展更多字段(如当前用户账号等)。

mainAppInfo.get

获取主应用基本信息。

typescript
get(): Promise<MainAppInfo>

返回值: MainAppInfo 对象

示例:

typescript
const info = await this.spCtx.api.mainAppInfo.get();
console.log('主应用版本:', info.version);      // 例如: "1.1.0"
console.log('是否为 PRO:', info.isPro);        // true 或 false

定时器

主应用提供的定时器接口,直接调用原生 setTimeout / setInterval。在微应用场景中,推荐使用此接口代替直接调用 setTimeout,以确保定时器运行在主应用的上下文中。

timer.setTimeout

创建一个定时器,在指定延迟后执行回调函数。

typescript
setTimeout(handler: TimerHandler, timeout?: number, ...args: any[]): number
参数类型必填说明
handlerTimerHandler定时器到期时执行的函数
timeoutnumber-延迟时间(毫秒),默认 0
...argsany[]-传递给回调函数的附加参数

返回值: 定时器 ID(number),用于 clearTimeout

示例:

typescript
const timerId = this.spCtx.api.timer.setTimeout(() => {
  console.log('2 秒后执行');
}, 2000);

// 取消定时器
this.spCtx.api.timer.clearTimeout(timerId);

timer.setInterval

创建一个定时器,每隔指定时间重复执行回调函数。

typescript
setInterval(handler: TimerHandler, timeout?: number, ...args: any[]): number
参数类型必填说明
handlerTimerHandler每次定时器到期时执行的函数
timeoutnumber-间隔时间(毫秒),默认 0
...argsany[]-传递给回调函数的附加参数

返回值: 定时器 ID(number),用于 clearInterval

示例:

typescript
const intervalId = this.spCtx.api.timer.setInterval(() => {
  console.log('每 5 秒轮询一次');
}, 5000);

// 停止轮询
this.spCtx.api.timer.clearInterval(intervalId);

timer.clearTimeout

取消由 setTimeout 创建的定时器。

typescript
this.spCtx.api.timer.clearTimeout(id: number): void

timer.clearInterval

取消由 setInterval 创建的定时器。

typescript
this.spCtx.api.timer.clearInterval(id: number): void

本地缓存

基于 IndexedDB,提供用户级和应用级的缓存功能。

用户级缓存 (localCache.user)

localCache.user.get

获取用户缓存值。

typescript
get(key: string): Promise<any>
参数类型必填说明
keystring缓存键

示例:

typescript
const value = await this.spCtx.api.localCache.user.get('userInfo');

localCache.user.set

设置用户缓存值。

typescript
set(key: string, value: any, expireSeconds?: number): Promise<void>
参数类型必填说明
keystring缓存键
valueany缓存值
expireSecondsnumber-过期时间(秒),0 表示不过期

示例:

typescript
await this.spCtx.api.localCache.user.set('userInfo', { name: '张三' }, 3600);

localCache.user.del

删除用户缓存。

typescript
del(key: string): Promise<void>
参数类型必填说明
keystring缓存键

示例:

typescript
await this.spCtx.api.localCache.user.del('userInfo');

localCache.user.clear

清空所有用户缓存。

typescript
clear(): Promise<void>

示例:

typescript
await this.spCtx.api.localCache.user.clear();

localCache.user.getKeys

获取所有用户缓存的键。

typescript
getKeys(): Promise<string[]>

返回值: 缓存键数组

示例:

typescript
const keys = await this.spCtx.api.localCache.user.getKeys();

应用级缓存 (localCache.app)

应用级缓存提供与用户级缓存相同的接口,但数据范围为应用级别,所有用户共享。

接口方法与 localCache.user 完全一致,调用时将 localCache.user 改为 localCache.app

示例:

typescript
await this.spCtx.api.localCache.app.set('appConfig', { theme: 'dark' });
const config = await this.spCtx.api.localCache.app.get('appConfig');

数据节点

提供用户级和应用级的数据节点管理功能。详细的权限说明请参阅 数据节点,本文档仅说明API的使用方法。需要在 权限配置 中声明 dataNode 权限。

用户数据节点 (dataNode.user)

dataNode.user.getByKey

根据键获取用户数据节点中 指定key 的数据。

typescript
getByKey<T = any>(node: string, key: string): Promise<T>
参数类型必填说明
nodestring节点名称
keystring数据键

示例:

javascript
try {
  const theme = await this.spCtx.api.dataNode.user.getByKey('preferences', 'theme');
  console.log(theme) // "dark"
} catch (e) {
  console.error(e.message);
}

dataNode.user.getByKeys

根据多个键获取用户数据节点中 填入所有的key 的数据。

typescript
getByKeys<T = Record<string, any>>(node: string, keys: string[]): Promise<T>
参数类型必填说明
nodestring节点名称
keysstring[]数据键数组

示例:

javascript
try {
  const config = await this.spCtx.api.dataNode.user.getByKeys('config', ['token', 'location']);
  console.log(config)
  // 示例打印内容:
  // {
  //   "location": {
  //     "city": "北京"
  //   },
  //   "token": 12345678
  // }
} catch (e) {
  console.error('批量获取失败: ' , e.message);
}

dataNode.user.setByKey

在用户数据节点中设置数据。

typescript
setByKey(node: string, key: string, value: any): Promise<void>
参数类型必填说明
nodestring节点名称
keystring数据键
valueany数据值

示例:

javascript
await this.spCtx.api.dataNode.user.setByKey('preferences', 'theme', { mode: 'dark' });

dataNode.user.setByKeys

批量设置用户数据节点中的数据。

typescript
setByKeys(node: string, items: Record<string, any>): Promise<void>
参数类型必填说明
nodestring节点名称
itemsRecord<string, any>数据键值对对象,键为数据键,值为对应数据

示例:

javascript
await this.spCtx.api.dataNode.user.setByKeys('config', {
  token: 'abc123',
  location: { city: '北京' }
});

dataNode.user.delByKey

删除用户数据节点中的数据。

typescript
delByKey(node: string, key: string): Promise<void>
参数类型必填说明
nodestring节点名称
keystring数据键

示例:

javascript
await this.spCtx.api.dataNode.user.delByKey('preferences', 'theme');

应用数据节点 (dataNode.app)

应用级数据节点提供与用户级数据节点相同的接口,但数据范围为应用级别,所有用户共享。接口方法与 dataNode.user 完全一致,调用时将 dataNode.user 改为 dataNode.app

错误处理

错误需要使用 try{...}catch{...} 进行捕获,所有的数据节点API都支持,错误类型参考:SpDataNodeError

示例:

javascript
try {
  const exampleData = {
    token: 'abc123',
    location: { city: '北京' }
  };
  await this.spCtx.api.dataNode.user.setByKeys("userConfig", exampleData);
  // this._showMessage('批量储存示例数据成功');
} catch (e) {
  console.error(e.code); // 错误代码 
  // this._showMessage('批量储存失败: ' + e.message, true);
}

网络透传

发送网络请求,支持模板变量替换(用于安全地传递敏感信息)。需要在 权限配置 中声明 network 权限。

network.request

typescript
request<T = any>(options: RequestOptions): Promise<T>

参数:

  • options: 请求参数对象,类型为 RequestOptions
属性类型必填说明
requestRequestParams请求参数对象
templateReplacementsTemplateReplacementRule[]-数据节点模板替换规则(替换敏感数据)
cookieDataNodeKeystring-Cookie 数据节点键,格式 "nodeName.key",详见下方说明

旧版(v2.0.0-dev-6及之前版本)兼容说明

旧版参数 targetUrlmethodheadersbody 已移入 request 属性,虽做了兼容处理,但新开发请直接使用 request 传值。

Cookie 自动管理

因安全考虑和受浏览器限制,可设置 cookieDataNodeKey 用于自动管理第三方站点的 Cookie,每个请求接口/域名单独分配一个数据节点的key来储存不同站点的cookie

  • 配置后会自动保存目标站点设置的 Cookie 到指定数据节点
  • 后续请求会自动携带保存的 Cookie
  • 可通过 数据节点 API 读取或修改
  • 注意:不管理过期时间、路径等,仅储存和传递

命名建议:以域名为基础,并添加 cookie 后缀,如 exampleComCookie,最终: config.exampleComCookie

cookie 数据节点键的内容

使用标准api调用 this.spCtx.api.dataNode.user.getByKey('config','example_com_cookie')

打印内容:

json
{
  // 之后请求读取此参数传递给请求站
  "cookies": "debug_session=session_88881; debug_token=test123456", 
  "meta": {
    "debug_session": {
      "path": "/"
    },
    "debug_token": {
      "httpOnly": true,
      "path": "/"
    }
  },
  "updatedAt": "2026-03-01T11:16:32+08:00"
}

示例:

typescript
const response = await this.spCtx.api.network.request({
  // 实际请求参数
  request: {
    targetUrl: 'https://{{domain}}/api/data',
    method: 'GET',
    headers: {
      "Authorization": "Bearer {{token}}"
    }
  },

  // 模版参数替换
  templateReplacements: [
    {
      placeholder: '{{token}}',
      fields: ['headers'],
      dataNodeKey: 'config.token'
    },
    {
      placeholder: '{{domain}}',
      fields: ['targetUrl'],
      dataNodeKey: 'config.domain'
    }
  ],

  // 用于储存和读取本站cookie的数据节点键名
  // 命名建议:以域名作为内容(需自行将域名中的.改为下划线),cookie作为后缀
  cookieDataNodeKey:'config.example_com_cookie' 
});

错误处理:

typescript
try {
  const response = await this.spCtx.api.network.request(options);
  console.log(response);
} catch (error) {
  switch (error.type) {
    case 'microApp':
      // 微应用错误(权限不足等)
      break;
    case 'targetUrl':
      // 目标站点返回的错误
      break;
    default:
      console.error(error);
  }
}

小部件管理

widget.save

保存小部件配置信息。

typescript
save<T = any>(data: WidgetInfo): Promise<T>
参数类型必填说明
dataWidgetInfo小部件信息对象

示例:

javascript
await this.spCtx.api.widget.save({
  ...this.spCtx.widgetInfo,
  config: {
    showLogo: this.showLogo,
    customText: this.customText
  },
});

系统监控

此API目前仅限官方微应用可用 获取服务器系统资源监控数据(CPU、内存、磁盘、网络)。支持两种使用方式:轮询订阅主动获取。需要在 权限配置 中声明 systemMonitor 权限。

systemMonitor.register

注册监控数据订阅,系统会按照指定间隔自动获取数据并通过回调函数返回。

typescript
register(config: MonitorRegistrationConfig): string
参数类型必填说明
configMonitorRegistrationConfig注册配置

返回值: 订阅 ID(string),用于后续取消订阅。

示例:

javascript
// 注册监控,每 5 秒获取一次,同时监控 CPU、内存、磁盘、网络
const subscriptionId = this.spCtx.api.systemMonitor.register({
  types: ['cpu', 'memory', 'disk', 'network'],
  interval: 5000,
  diskPaths: ['/'],  // 磁盘监控需要指定挂载路径数组
  callback: (data) => {
    // CPU 信息
    if (data.cpu) {
      console.log('CPU 使用率:', data.cpu.usages);
    }
    // 内存信息
    if (data.memory) {
      console.log('内存使用率:', data.memory.usedPercent + '%');
    }
    // 磁盘信息(可能有多个分区)
    if (data.disk) {
      data.disk.forEach(disk => {
        console.log(`磁盘 ${disk.mountpoint}: ${disk.usedPercent.toFixed(1)}%`);
      });
    }
    // 网络信息(可能有多个接口)
    if (data.network) {
      data.network.forEach(net => {
        console.log(`网络 ${net.name}: 发送 ${net.bytesSent}, 接收 ${net.bytesRecv}`);
      });
    }
  }
});

systemMonitor.unregister

取消监控数据订阅。

typescript
unregister(id: string): void
参数类型必填说明
idstring订阅 ID(register 返回的值)

示例:

javascript
// 取消订阅
this.spCtx.api.systemMonitor.unregister(subscriptionId);

systemMonitor.fetchData

主动获取指定类型的监控数据(一次性请求,不创建订阅)。

typescript
fetchData(config: { types?: MonitorType[], type?: MonitorType, diskPaths?: string[] }): Promise<MonitorDataResp | null>
参数类型必填说明
config.typesMonitorType[]-监控类型数组
config.typeMonitorType-单个监控类型(与 types 二选一)
config.diskPathsstring[]-磁盘挂载路径数组(仅查询 disk 类型时需要)

返回值: MonitorDataRespnull

示例:

javascript
// 主动获取 CPU 和网络数据
const data = await this.spCtx.api.systemMonitor.fetchData({
  types: ['cpu', 'network']
});

if (data) {
  console.log('CPU:', data.cpu);
  console.log('网络:', data.network);
}

// 获取磁盘数据(需要指定挂载路径数组)
const diskData = await this.spCtx.api.systemMonitor.fetchData({
  type: 'disk',
  diskPaths: ['/']
});

if (diskData && diskData.disk) {
  diskData.disk.forEach(disk => {
    console.log(`磁盘 ${disk.mountpoint}:`);
    console.log(`  总容量: ${(disk.total / 1024 / 1024 / 1024).toFixed(2)} GB`);
    console.log(`  已使用: ${(disk.used / 1024 / 1024 / 1024).toFixed(2)} GB`);
    console.log(`  使用率: ${disk.usedPercent.toFixed(1)}%`);
  });
}

// 通过订阅方式监控磁盘(每 10 秒更新)
const diskSubId = this.spCtx.api.systemMonitor.register({
  types: ['disk'],
  interval: 10000,
  diskPaths: ['/'],
  callback: (data) => {
    if (data.disk) {
      data.disk.forEach(disk => {
        console.log(`[${disk.mountpoint}] 使用率: ${disk.usedPercent.toFixed(1)}%`);
      });
    }
  }
});

// 同时监控多个磁盘分区
const multiDiskSubId = this.spCtx.api.systemMonitor.register({
  types: ['disk'],
  interval: 5000,
  diskPaths: ['/', '/home', '/data'],  // 监控多个挂载点
  callback: (data) => {
    if (data.disk) {
      data.disk.forEach(disk => {
        console.log(`磁盘 ${disk.mountpoint}: ${disk.usedPercent.toFixed(1)}%`);
      });
    }
  }
});

systemMonitor.getSystemInfo

获取系统基础信息(主机名、操作系统、架构、运行时长、系统负载)。此接口为一次性获取,不创建订阅。

typescript
getSystemInfo(): Promise<SystemInfo | null>

返回值: SystemInfonull

示例:

javascript
// 获取系统信息
const sysInfo = await this.spCtx.api.systemMonitor.getSystemInfo();

if (sysInfo) {
  console.log('主机名:', sysInfo.hostname);
  console.log('操作系统:', sysInfo.os);
  console.log('平台:', sysInfo.platform, sysInfo.platformVer);
  console.log('架构:', sysInfo.arch);
  console.log('运行时长:', Math.floor(sysInfo.uptime / 86400), '天');
  console.log('系统负载:', sysInfo.load1, sysInfo.load5, sysInfo.load15);
}

数据类型

以下类型定义均来自 @sun-panel/micro-app SDK,可在 IDE 中自动补全。

MainAppInfo

主应用基本信息。

属性类型说明
versionstring主应用版本号(后端版本)
isProboolean主应用是否为 PRO 状态

WindowConfig

窗口配置选项。

属性类型默认值说明
widthnumber | string800窗口宽度,数字时单位为 px
heightnumber | string600窗口高度,数字时单位为 px
backgroundstring页面配置的 background背景颜色
backgroundDarkstring页面配置的 backgroundDark暗色模式下的背景颜色
headerTextColorstring页面配置的 headerTextColor标题栏文字颜色
headerTextColorDarkstring页面配置的 headerTextColorDark暗色模式下的标题栏文字颜色
showFullscreenBtnbooleanfalse是否显示全屏按钮
resizebooleanfalse是否允许调整窗口大小
movebooleanfalse是否允许移动窗口

OpenWindowOptions

打开窗口的参数。

属性类型必填说明
componentNamestring组件名称
windowConfigWindowConfig-窗口配置
customParamany-自定义参数
titlestring-窗口标题

RequestParams

请求参数对象。

属性类型必填说明
targetUrlstring目标 URL,支持模板变量
methodstring-请求方法,默认 GET
headersobject-请求头
bodystring-请求体,如果传对象请 JSON.stringify(xxx) 转换为字符串

TemplateReplacementRule

模板替换规则,用于将占位符替换为数据节点中的数据,避免敏感数据泄漏在前端。

属性类型必填说明
placeholderstring要替换的占位符,如 {{token}}
fieldsstring[]替换参数的目标字段,可选:targetUrlmethodheadersbody
dataNodeKeystring数据节点键,如 "config.token"

旧版(v2.0.0-dev-6及之前版本)兼容说明

旧版参数 dataNode 已删除,虽做了兼容处理,但新开发请直接使用 dataNodeKey

WidgetInfo

小部件信息对象。

属性类型必填说明
widgetIdstring小部件 ID
configRecord<string, any>小部件配置对象,自定义配置数据,不可填写敏感数据,敏感数据可以储存在数据节点。
backgroundstring-卡片背景颜色,为空跟随系统默认颜色
gridSizestring-卡片网格尺寸,此项微应用只可读取不可设置
titlestring-卡片底部标题,只读不可设置

MonitorType

监控数据类型。

说明
'cpu'CPU 使用率
'memory'内存使用情况
'disk'磁盘使用情况
'network'网络流量统计

MonitorRegistrationConfig

监控订阅配置。

属性类型必填说明
typesMonitorType[]监控类型数组
callback(data: MonitorDataResp) => void数据回调函数
intervalnumber更新间隔(毫秒),最小 1000
diskPathsstring[]-磁盘挂载路径数组(仅查询 disk 类型时需要)

MonitorDataResp

监控数据响应。

属性类型说明
cpuCPUInfoCPU 信息(请求包含 cpu 时返回)
memoryMemoryInfo内存信息(请求包含 memory 时返回)
diskDiskInfo[]磁盘信息数组(请求包含 disk 时返回)
networkNetIOCountersInfo[]网络流量数组(请求包含 network 时返回)

CPUInfo

属性类型说明
coreCountnumberCPU 核心数
cpuNumnumberCPU 逻辑处理器数
modelstringCPU 型号
usagesnumber[]各核心使用率(百分比)

MemoryInfo

属性类型说明
totalnumber总内存(字节)
usednumber已使用内存(字节)
freenumber空闲内存(字节)
usedPercentnumber使用率(百分比)

DiskInfo

属性类型说明
titlestring磁盘标题
mountpointstring挂载路径
totalnumber总容量(字节)
usednumber已使用(字节)
freenumber空闲(字节)
usedPercentnumber使用率(百分比)

NetIOCountersInfo

属性类型说明
namestring网络接口名称
bytesSentnumber发送字节数
bytesRecvnumber接收字节数

SystemInfo

系统基础信息。

属性类型说明
hostnamestring主机名
osstring操作系统
platformstring平台 (ubuntu, centos 等)
platformVerstring平台版本
archstring架构 (amd64, arm64 等)
uptimenumber运行时长(秒)
bootTimenumber启动时间(Unix 时间戳)
load1number1分钟负载
load5number5分钟负载
load15number15分钟负载
fetchedAtnumber数据获取时间(Unix 时间戳)

错误类型

SpNetworkRequestError

网络请求错误。

属性类型说明
namestring固定为 'SpNetworkRequestError'
type'microApp' | 'targetUrl' | 'unknown'错误类型
responseHttpResponse | AxiosResponse响应对象

SpDataNodeError

数据节点错误。

属性类型说明
namestring固定为 'SpDataNodeError'
codestring | number错误码:NO_PERMISSION, UNKNOWN

HttpResponse

HTTP 响应类型,兼容 AxiosResponse 结构。

属性类型说明
dataany响应数据
statusnumberHTTP 状态码
statusTextstring状态文本
headersRecord<string, any>响应头
configany请求配置(可选)
requestany原始请求对象(可选)

注意事项

  1. 异步操作:大部分 API 都是异步的,建议使用 async/await 处理
  2. 错误处理:使用 try-catch 捕获异常,并根据 error.type 区分错误来源
  3. 用户级与应用级:用户级数据仅对当前用户可见,应用级数据对所有用户共享
  4. 权限要求:使用网络和数据节点功能需在 app.config.js 中声明相应权限

Released under the MIT License.