@sun-panel/micro-app-api

Sun Panel 微应用插件开发 SDK

简介

这是 Sun Panel 平台的官方微应用开发工具包，提供了完整的 API 能力，让开发者可以轻松开发跨框架的微应用插件。

特性

✅ 完整的 API 能力

• HTTP 请求（支持域名白名单）
• 窗口管理（打开/关闭应用窗口）
• 小部件管理（创建/删除卡片）
• 数据存储（数据节点 + 本地存储）

✅ 丰富的事件系统

• 生命周期事件（激活/停用/挂载/卸载）
• 主题切换事件（深色/浅色模式）
• 语言切换事件（多语言支持）
• 网络切换事件（内网/外网）
• 应用内消息通信

✅ 框架无关

• 支持任何前端框架（Vue、React、原生 JS 等）
• 基于 Web Components 和 CustomEvent
• 完整的 TypeScript 类型定义

安装

npm install @sun-panel/micro-app-api

或

pnpm add @sun-panel/micro-app-api

快速开始

1. 初始化

import { init, notifyReady } from '@sun-panel/micro-app-api'
import appConfig from './app.json'

// 初始化 API
await init({
  appId: 'my-app',
  appConfig
})

// 通知平台插件已就绪
notifyReady('my-app', '1.0.0')

2. HTTP 请求

import { get, post } from '@sun-panel/micro-app-api'

// GET 请求
const data = await get('https://api.example.com/data')

// POST 请求
const result = await post('https://api.example.com/submit', {
  name: 'test'
})

注意：请求的域名必须在 app.json 的 network_domain 中声明。

3. 窗口管理

import { openMain, openConfig, closeWindow } from '@sun-panel/micro-app-api'

// 打开主窗口并传参
openMain({ userId: 123 })

// 打开配置窗口
openConfig()

// 关闭当前窗口
closeWindow()

4. 创建小部件

import { createWidget } from '@sun-panel/micro-app-api'

// 创建一个卡片
const widgetId = await createWidget({
  config: {
    title: '天气',
    size: 'medium'
  },
  position: { x: 0, y: 0 }
})

5. 数据存储

数据节点（与后端同步）

import { dataNode } from '@sun-panel/micro-app-api'

// 创建数据
await dataNode.create('settings', { theme: 'dark' })

// 读取数据
const data = await dataNode.read('settings')

// 更新数据
await dataNode.update('settings', { theme: 'light' })

// 删除数据
await dataNode.delete('settings')

本地存储

import { localStorage } from '@sun-panel/micro-app-api'

// 保存数据
localStorage.set('userPrefs', { fontSize: 14 })

// 读取数据
const prefs = localStorage.get('userPrefs')

// 删除数据
localStorage.remove('userPrefs')

// 清空所有数据
localStorage.clear()

6. 事件监听

生命周期事件

import { onActivate, onDeactivate, onMount, onUnmount } from '@sun-panel/micro-app-api'

// 插件激活时
const unsubscribe = onActivate(() => {
  console.log('插件已激活')
})

// 插件停用时
onDeactivate(() => {
  console.log('插件已停用')
})

// 取消监听
unsubscribe()

主题切换

import { onThemeChange, getCurrentTheme, isDarkMode } from '@sun-panel/micro-app-api'

// 监听主题切换
onThemeChange((theme) => {
  console.log('当前主题:', theme) // 'light' | 'dark'
})

// 获取当前主题
const theme = getCurrentTheme()

// 判断是否深色模式
if (isDarkMode()) {
  // 应用深色样式
}

语言切换

import { onLanguageChange, getCurrentLanguage } from '@sun-panel/micro-app-api'

// 监听语言切换
onLanguageChange((lang) => {
  console.log('当前语言:', lang)
})

// 获取当前语言
const lang = getCurrentLanguage()

网络切换

import { onNetworkChange, isInternalNetwork } from '@sun-panel/micro-app-api'

// 监听网络切换
onNetworkChange((networkType) => {
  console.log('网络类型:', networkType) // 'internal' | 'external'
})

// 判断是否内网
if (isInternalNetwork()) {
  // 使用内网 API
}

应用内消息

import { onMessage, sendMessage } from '@sun-panel/micro-app-api'

// 监听消息
onMessage('data-update', (payload) => {
  console.log('收到数据更新:', payload)
})

// 发送消息
sendMessage('data-update', { id: 1, value: 'new' })

API 文档

Request API

| 方法 | 说明 | 参数 | |------|------|------| | request(url, options) | 发起 HTTP 请求 | url: string, options: RequestOptions | | get(url, options) | GET 请求 | url: string, options?: RequestOptions | | post(url, data, options) | POST 请求 | url: string, data: any, options?: RequestOptions | | put(url, data, options) | PUT 请求 | url: string, data: any, options?: RequestOptions | | del(url, options) | DELETE 请求 | url: string, options?: RequestOptions |

Window API

| 方法 | 说明 | 参数 | |------|------|------| | openWindow(options) | 打开应用窗口 | options: WindowOptions | | openMain(params, windowOptions) | 打开主窗口 | params?: object, windowOptions?: object | | openConfig(params, windowOptions) | 打开配置窗口 | params?: object, windowOptions?: object | | closeWindow() | 关闭当前窗口 | - |

Widget API

| 方法 | 说明 | 参数 | |------|------|------| | createWidget(options) | 创建小部件 | options: WidgetOptions | | removeWidget(widgetId) | 删除小部件 | widgetId: string | | updateWidgetConfig(widgetId, config) | 更新配置 | widgetId: string, config: object |

Storage API

dataNode（数据节点）

| 方法 | 说明 | 参数 | |------|------|------| | create(nodeName, data) | 创建数据节点 | nodeName: string, data: any | | read(nodeName) | 读取数据节点 | nodeName: string | | update(nodeName, data) | 更新数据节点 | nodeName: string, data: any | | delete(nodeName) | 删除数据节点 | nodeName: string |

localStorage（本地存储）

| 方法 | 说明 | 参数 | |------|------|------| | set(key, value) | 保存数据 | key: string, value: any | | get(key, defaultValue) | 读取数据 | key: string, defaultValue?: any | | remove(key) | 删除数据 | key: string | | clear() | 清空所有数据 | - |

Event API

生命周期

| 方法 | 说明 | 参数 | |------|------|------| | onActivate(handler) | 监听激活事件 | handler: Function | | onDeactivate(handler) | 监听停用事件 | handler: Function | | onMount(handler) | 监听挂载事件 | handler: Function | | onUnmount(handler) | 监听卸载事件 | handler: Function | | onConfigUpdate(handler) | 监听配置更新 | handler: Function |

主题

| 方法 | 说明 | 参数 | |------|------|------| | onThemeChange(handler) | 监听主题切换 | handler: Function | | getCurrentTheme() | 获取当前主题 | - | | isDarkMode() | 是否深色模式 | - | | requestThemeChange(theme) | 请求切换主题 | theme: 'light' | 'dark' |

语言

| 方法 | 说明 | 参数 | |------|------|------| | onLanguageChange(handler) | 监听语言切换 | handler: Function | | getCurrentLanguage() | 获取当前语言 | - | | requestLanguageChange(lang) | 请求切换语言 | lang: string |

网络

| 方法 | 说明 | 参数 | |------|------|------| | onNetworkChange(handler) | 监听网络切换 | handler: Function | | getCurrentNetworkType() | 获取网络类型 | - | | isInternalNetwork() | 是否内网 | - | | isExternalNetwork() | 是否外网 | - |

消息

| 方法 | 说明 | 参数 | |------|------|------| | onMessage(type, handler) | 监听应用消息 | type: string, handler: Function | | sendMessage(type, payload) | 发送应用消息 | type: string, payload: any | | onPlatformMessage(type, handler) | 监听平台消息 | type: string, handler: Function | | sendPlatformMessage(type, payload) | 发送平台消息 | type: string, payload: any |

TypeScript 支持

本包提供完整的 TypeScript 类型定义：

import { 
  init, 
  get, 
  createWidget, 
  onThemeChange,
  type AppConfig,
  type WindowOptions 
} from '@sun-panel/micro-app-api'

// 类型推断和检查
const config: AppConfig = {
  id: 'my-app',
  // ...
}

开发示例

查看 micro-app-demo 目录中的示例项目：

• clock-plugin - 时钟插件示例
• vue-demo - Vue 3 计数器示例

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！