前端 SDK 文档

一、概述

xiaowo-sdk 已集成在插件模板中，无需单独安装。直接导入即可使用：

import { PluginSDK } from "xiaowo-sdk"

二、快速开始

import { PluginSDK } from "xiaowo-sdk"

// 等待 SDK 准备好
await PluginSDK.waitReady()

// 调用后端方法
const result = await PluginSDK.callBackend('hello', { name: '小蜗' })

三、API 参考

3.1 后端通信

方法	说明
`waitReady()`	等待 SDK 初始化完成
`callBackend(method, params)`	调用后端方法
`getBackendState()`	获取后端状态
`onBackendEvent(eventName, handler)`	监听后端推送的事件
`offBackendEvent(eventName)`	取消监听后端事件
`onBackendReady(handler)`	监听后端就绪事件
`onBackendExit(handler)`	监听后端进程退出事件
`restartBackend()`	重启后端进程

// 调用后端方法
const result = await PluginSDK.callBackend('hello', { name: '小蜗' })

// 监听后端事件
PluginSDK.onBackendEvent('progress', (data) => {
  console.log('进度:', data.percent)
})

// 监听后端就绪（返回 unlisten 函数）
const unlistenReady = PluginSDK.onBackendReady(() => {
  console.log('后端已就绪')
})

// 监听后端退出（返回 unlisten 函数）
const unlistenExit = PluginSDK.onBackendExit((info) => {
  console.warn('后端已退出:', info)
})

// 取消监听
unlistenReady()
unlistenExit()

3.2 窗口控制

方法	说明
`close()`	关闭窗口
`minimize()`	最小化窗口
`toggleMaximize()`	切换最大化状态
`showWindow()`	显示窗口

PluginSDK.minimize()
PluginSDK.toggleMaximize()
PluginSDK.close()

3.3 插件信息

方法	说明
`getInfo()`	获取插件信息（manifest 配置）
`createDesktopShortcut(name)`	创建桌面快捷方式

const info = await PluginSDK.getInfo()
console.log(info.manifest.title)   // 插件标题
console.log(info.manifest.version) // 插件版本

await PluginSDK.createDesktopShortcut("我的插件")

3.4 文件拖放

方法	说明
`onFileDrop(handler)`	监听文件拖放
`onFileDropHover(handler)`	监听文件悬停
`onFileDropCancelled(handler)`	监听拖放取消

PluginSDK.onFileDrop((files) => {
  console.log('拖入文件:', files)
})

3.5 文件路径转换

方法	说明
`convertFileSrc(filePath)`	将本地文件路径转换为可加载的 URL

const url = PluginSDK.convertFileSrc('D:\\music\\test.mp3')
// 可用于 audio/video/img 标签

3.6 对话框

方法	说明
`dialog.open(options)`	打开文件选择对话框
`dialog.save(options)`	打开保存文件对话框

3.7 剪贴板

方法	说明
`clipboard.readText()`	读取剪贴板文本
`clipboard.writeText(text)`	写入剪贴板文本

3.8 路径操作

方法	说明
`path.appDataDir()`	应用数据目录
`path.homeDir()`	用户主目录
`path.desktopDir()`	桌面目录
`path.downloadDir()`	下载目录
`path.tempDir()`	临时目录
`path.join(...paths)`	拼接路径
`path.basename(p)`	获取文件名
`path.dirname(p)`	获取目录名
`path.extname(p)`	获取扩展名

3.9 Shell

方法	说明
`shell.open(path)`	使用系统默认程序打开文件或 URL

3.10 文件管理

PluginSDK.fs 提供了一组前端可直接调用的文件管理接口，适合处理插件自己的输出文件、缓存文件、导出文件等场景。

方法	说明
`fs.createFile(path, overwrite = false)`	创建文件，`overwrite` 为 `true` 时允许覆盖已有文件
`fs.createDir(path, recursive = true)`	创建目录，默认递归创建
`fs.writeTextFile(path, content, append = false)`	写入文本文件，可选追加写入
`fs.writeBase64File(path, base64Data, append = false)`	将 Base64 内容写入文件，可用于图片、音频等二进制内容
`fs.readTextFile(path)`	读取文本文件内容
`fs.removeFile(path)`	删除文件
`fs.removeDir(path, recursive = true)`	删除目录，默认递归删除
`fs.getInfo(path)`	获取路径信息
`fs.exists(path)`	判断路径是否存在
`fs.isFile(path)`	判断路径是否为文件
`fs.isDir(path)`	判断路径是否为目录
`fs.copyFile(src, dest)`	复制文件

import { PluginSDK } from 'xiaowo-sdk'

await PluginSDK.waitReady()

const outputDir = await PluginSDK.path.join(await PluginSDK.path.appDataDir(), 'my-plugin')
await PluginSDK.fs.createDir(outputDir)

const outputFile = await PluginSDK.path.join(outputDir, 'result.txt')
await PluginSDK.fs.writeTextFile(outputFile, '处理完成')

const exists = await PluginSDK.fs.exists(outputFile)
const content = await PluginSDK.fs.readTextFile(outputFile)
const info = await PluginSDK.fs.getInfo(outputFile)

console.log(exists, content, info)

const imagePath = await PluginSDK.path.join(outputDir, 'cover.png')
await PluginSDK.fs.writeBase64File&#40;imagePath, base64Image&#41;

说明：

这些接口都是异步方法，调用前建议先执行 await PluginSDK.waitReady()
path 建议优先通过 PluginSDK.path.join() 拼接，避免手写分隔符
适合管理插件运行时文件，不建议直接依赖硬编码的绝对路径
如果前端只是为了在页面中预览本地文件，可配合 convertFileSrc() 一起使用

四、框架示例

4.1 Vue 示例

import { ref, onMounted, onUnmounted } from 'vue'
import { PluginSDK } from 'xiaowo-sdk'

const result = ref('')
const progress = ref(0)
const backendReady = ref(false)

let unlistenReady
let unlistenExit

onMounted(async () => {
  await PluginSDK.waitReady()

  // 监听后端就绪
  unlistenReady = PluginSDK.onBackendReady(() => {
    backendReady.value = true
  })

  // 监听后端退出
  unlistenExit = PluginSDK.onBackendExit((info) => {
    console.warn('后端已退出:', info)
    backendReady.value = false
  })

  // 监听进度事件
  PluginSDK.onBackendEvent('progress', (data) => {
    progress.value = data.percent
  })
})

onUnmounted(() => {
  unlistenReady?.()
  unlistenExit?.()
  PluginSDK.offBackendEvent('progress')
})

async function callHello() {
  const res = await PluginSDK.callBackend('hello', { name: 'Vue' })
  result.value = res.message
}


<template>
  <div v-if="!backendReady">后端加载中...</div>
  <div v-else>
    <button @click="callHello">调用后端</button>
    <p>{{ result }}</p>
    <p>进度: {{ progress }}%</p>
  </div>
</template>

4.2 React 示例

import { useState, useEffect } from 'react'
import { PluginSDK } from 'xiaowo-sdk'

export default function App() {
  const [result, setResult] = useState('')
  const [progress, setProgress] = useState(0)
  const [backendReady, setBackendReady] = useState(false)

  useEffect(() => {
    let unlistenReady: (() => void) | undefined
    let unlistenExit: (() => void) | undefined

    PluginSDK.waitReady().then(() => {
      // 监听后端就绪
      unlistenReady = PluginSDK.onBackendReady(() => {
        setBackendReady(true)
      })

      // 监听后端退出
      unlistenExit = PluginSDK.onBackendExit((info) => {
        console.warn('后端已退出:', info)
        setBackendReady(false)
      })

      // 监听进度事件
      PluginSDK.onBackendEvent('progress', (data) => {
        setProgress(data.percent)
      })
    })

    return () => {
      unlistenReady?.()
      unlistenExit?.()
      PluginSDK.offBackendEvent('progress')
    }
  }, [])

  async function callHello() {
    const res = await PluginSDK.callBackend('hello', { name: 'React' })
    setResult(res.message)
  }

  if (!backendReady) {
    return <div>后端加载中...</div>
  }

  return (
    <div>
      <button >调用后端</button>
      <p>{result}</p>
      <p>进度: {progress}%</p>
    </div>
  )
}

还没有回答~

请先登录