flash-send/document/05-API文档.md

API 文档

本文档详细介绍 Flash Send 的 Tauri 命令 API 和事件系统。

Tauri 命令

所有命令通过 @tauri-apps/api/core 的 invoke 函数调用。

设备发现

start_discovery

启动设备发现服务，开始广播本机信息并监听其他设备。

invoke('start_discovery')

返回: Promise<void>

---

stop_discovery

停止设备发现服务。

invoke('stop_discovery')

返回: Promise<void>

---

get_online_devices

获取当前在线的设备列表。

invoke<DeviceInfo[]>('get_online_devices')

返回: Promise<DeviceInfo[]>

interface DeviceInfo {
  deviceId: string      // 设备唯一标识
  deviceName: string    // 设备名称
  ip: string            // IP 地址
  wsPort: number        // WebSocket 端口
  httpPort: number      // HTTP 端口
  lastSeen: number      // 最后在线时间戳
}

---

get_local_device

获取本机设备信息。

invoke<DeviceInfo>('get_local_device')

返回: Promise<DeviceInfo>

---

聊天通信

start_ws_server

启动 WebSocket 服务端，接收其他设备的连接。

invoke('start_ws_server')

返回: Promise<void>

---

connect_to_device

连接到指定设备的 WebSocket 服务。

invoke('connect_to_device', { deviceId: string })

参数:

参数	类型	说明
deviceId	string	目标设备 ID

返回: Promise<void>

---

send_chat_message

发送聊天消息。

invoke<ChatMessage>('send_chat_message', {
  deviceId: string,
  content: string,
  messageType?: string
})

参数:

参数	类型	默认值	说明
deviceId	string	-	目标设备 ID
content	string	-	消息内容
messageType	string	'text'	消息类型：text/image/file

返回: Promise<ChatMessage>

interface ChatMessage {
  id: string
  fromDevice: string
  toDevice: string
  content: string
  messageType: 'text' | 'image' | 'file' | 'system'
  timestamp: number
  isRead: boolean
}

---

get_chat_history

获取与指定设备的聊天历史。

invoke<ChatMessage[]>('get_chat_history', {
  deviceId: string,
  limit?: number,
  offset?: number
})

参数:

参数	类型	默认值	说明
deviceId	string	-	目标设备 ID
limit	number	50	返回条数限制
offset	number	0	偏移量

返回: Promise<ChatMessage[]>

---

delete_chat_history

删除与指定设备的聊天历史。

invoke('delete_chat_history', { deviceId: string })

参数:

参数	类型	说明
deviceId	string	目标设备 ID

返回: Promise<void>

---

文件传输

start_http_server

启动 HTTPS 文件服务，接收文件上传。

invoke('start_http_server')

返回: Promise<void>

---

select_file

打开文件选择对话框。

invoke<FileMetadata | null>('select_file')

返回: Promise<FileMetadata | null>

interface FileMetadata {
  name: string      // 文件名
  path: string      // 文件完整路径
  size: number      // 文件大小（字节）
  mimeType?: string // MIME 类型
}

---

send_file

发送文件到指定设备。

invoke<FileTransfer>('send_file', {
  deviceId: string,
  fileId: string,
  filePath: string
})

参数:

参数	类型	说明
deviceId	string	目标设备 ID
fileId	string	文件传输 ID（UUID）
filePath	string	本地文件路径

返回: Promise<FileTransfer>

interface FileTransfer {
  fileId: string
  name: string
  size: number
  progress: number           // 0.0 - 1.0
  status: TransferStatus
  mimeType?: string
  fromDevice: string
  toDevice: string
  localPath?: string
  createdAt: number
  completedAt?: number
  transferredBytes: number
}

type TransferStatus = 'pending' | 'transferring' | 'completed' | 'failed' | 'cancelled'

---

cancel_transfer

取消文件传输。

invoke('cancel_transfer', { fileId: string })

参数:

参数	类型	说明
fileId	string	传输 ID

返回: Promise<void>

---

get_transfer_history

获取与指定设备的文件传输历史。

invoke<FileTransfer[]>('get_transfer_history', {
  deviceId: string,
  limit?: number
})

参数:

参数	类型	默认值	说明
deviceId	string	-	目标设备 ID
limit	number	50	返回条数限制

返回: Promise<FileTransfer[]>

---

open_file_location

在系统文件管理器中打开文件所在位置。

invoke('open_file_location', { path: string })

参数:

参数	类型	说明
path	string	文件路径

返回: Promise<void>

平台行为:

• Windows: explorer /select, <path>
• macOS: open -R <path>
• Linux: xdg-open <dir>

---

配置管理

get_app_config

获取应用配置。

invoke<AppConfig>('get_app_config')

返回: Promise<AppConfig>

interface AppConfig {
  deviceId: string      // 本机设备 ID
  deviceName: string    // 设备名称
  downloadDir: string   // 下载目录
  wsPort: number        // WebSocket 端口
  httpPort: number      // HTTP 端口
}

---

update_device_name

更新设备名称。

invoke('update_device_name', { name: string })

参数:

参数	类型	说明
name	string	新的设备名称

返回: Promise<void>

---

update_download_dir

更新文件下载目录。

invoke('update_download_dir', { path: string })

参数:

参数	类型	说明
path	string	新的下载目录路径

返回: Promise<void>

---

事件系统

通过 @tauri-apps/api/event 的 listen 函数监听后端事件。

device:found

发现新设备时触发。

import { listen } from '@tauri-apps/api/event'

listen<DeviceInfo>('device:found', (event) => {
  console.log('发现设备:', event.payload)
})

Payload: DeviceInfo

---

device:lost

设备离线时触发。

listen<string>('device:lost', (event) => {
  console.log('设备离线:', event.payload)  // device_id
})

Payload: string (device_id)

---

chat:message

收到聊天消息时触发。

listen<ChatMessage>('chat:message', (event) => {
  console.log('收到消息:', event.payload)
})

Payload: ChatMessage

---

file:progress

文件传输进度更新时触发。

listen<TransferProgressEvent>('file:progress', (event) => {
  console.log('传输进度:', event.payload)
})

Payload: TransferProgressEvent

interface TransferProgressEvent {
  fileId: string           // 传输 ID
  progress: number         // 进度 0.0 - 1.0
  transferredBytes: number // 已传输字节数
  totalBytes: number       // 总字节数
  status: TransferStatus   // 传输状态
  fileName?: string        // 文件名（接收方）
  localPath?: string       // 本地路径（接收方）
}

---

错误处理

所有命令在出错时会抛出 CommandError：

interface CommandError {
  code: string     // 错误代码
  message: string  // 错误信息
}

常见错误代码:

代码	说明
DB_ERROR	数据库操作错误
IO_ERROR	文件 IO 错误
WS_ERROR	WebSocket 错误
DEVICE_NOT_FOUND	设备不存在
NOT_CONNECTED	未建立连接
TRANSFER_ERROR	传输错误

使用示例：

try {
  await invoke('send_chat_message', { deviceId, content })
} catch (error) {
  const err = error as CommandError
  if (err.code === 'NOT_CONNECTED') {
    // 尝试重新连接
    await invoke('connect_to_device', { deviceId })
  }
}

---

完整示例

设备发现与聊天

import { invoke } from '@tauri-apps/api/core'
import { listen } from '@tauri-apps/api/event'

// 1. 监听设备发现事件
const unlistenDevice = await listen<DeviceInfo>('device:found', (event) => {
  console.log('发现设备:', event.payload.deviceName)
})

// 2. 监听消息事件
const unlistenMessage = await listen<ChatMessage>('chat:message', (event) => {
  console.log('收到消息:', event.payload.content)
})

// 3. 启动服务
await invoke('start_ws_server')
await invoke('start_discovery')

// 4. 获取在线设备
const devices = await invoke<DeviceInfo[]>('get_online_devices')

// 5. 连接设备并发送消息
if (devices.length > 0) {
  const device = devices[0]
  await invoke('connect_to_device', { deviceId: device.deviceId })
  await invoke('send_chat_message', {
    deviceId: device.deviceId,
    content: 'Hello!'
  })
}

// 清理
unlistenDevice()
unlistenMessage()
await invoke('stop_discovery')

文件传输

import { invoke } from '@tauri-apps/api/core'
import { listen } from '@tauri-apps/api/event'

// 1. 监听传输进度
const unlisten = await listen<TransferProgressEvent>('file:progress', (event) => {
  const { fileId, progress, status } = event.payload
  console.log(`${fileId}: ${(progress * 100).toFixed(1)}% - ${status}`)
})

// 2. 启动文件服务
await invoke('start_http_server')

// 3. 选择文件
const file = await invoke<FileMetadata | null>('select_file')
if (!file) return

// 4. 发送文件
const fileId = crypto.randomUUID()
const transfer = await invoke<FileTransfer>('send_file', {
  deviceId: targetDeviceId,
  fileId,
  filePath: file.path
})

console.log('开始传输:', transfer.name)

// 清理
unlisten()