|
|
# API 文档
|
|
|
|
|
|
本文档详细介绍 Flash Send 的 Tauri 命令 API 和事件系统。
|
|
|
|
|
|
## Tauri 命令
|
|
|
|
|
|
所有命令通过 `@tauri-apps/api/core` 的 `invoke` 函数调用。
|
|
|
|
|
|
### 设备发现
|
|
|
|
|
|
#### start_discovery
|
|
|
|
|
|
启动设备发现服务，开始广播本机信息并监听其他设备。
|
|
|
|
|
|
```typescript
|
|
|
invoke('start_discovery')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### stop_discovery
|
|
|
|
|
|
停止设备发现服务。
|
|
|
|
|
|
```typescript
|
|
|
invoke('stop_discovery')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### get_online_devices
|
|
|
|
|
|
获取当前在线的设备列表。
|
|
|
|
|
|
```typescript
|
|
|
invoke<DeviceInfo[]>('get_online_devices')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<DeviceInfo[]>`
|
|
|
|
|
|
```typescript
|
|
|
interface DeviceInfo {
|
|
|
deviceId: string // 设备唯一标识
|
|
|
deviceName: string // 设备名称
|
|
|
ip: string // IP 地址
|
|
|
wsPort: number // WebSocket 端口
|
|
|
httpPort: number // HTTP 端口
|
|
|
lastSeen: number // 最后在线时间戳
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
#### get_local_device
|
|
|
|
|
|
获取本机设备信息。
|
|
|
|
|
|
```typescript
|
|
|
invoke<DeviceInfo>('get_local_device')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<DeviceInfo>`
|
|
|
|
|
|
---
|
|
|
|
|
|
### 聊天通信
|
|
|
|
|
|
#### start_ws_server
|
|
|
|
|
|
启动 WebSocket 服务端，接收其他设备的连接。
|
|
|
|
|
|
```typescript
|
|
|
invoke('start_ws_server')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### connect_to_device
|
|
|
|
|
|
连接到指定设备的 WebSocket 服务。
|
|
|
|
|
|
```typescript
|
|
|
invoke('connect_to_device', { deviceId: string })
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| deviceId | string | 目标设备 ID |
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### send_chat_message
|
|
|
|
|
|
发送聊天消息。
|
|
|
|
|
|
```typescript
|
|
|
invoke<ChatMessage>('send_chat_message', {
|
|
|
deviceId: string,
|
|
|
content: string,
|
|
|
messageType?: string
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 默认值 | 说明 |
|
|
|
|------|------|--------|------|
|
|
|
| deviceId | string | - | 目标设备 ID |
|
|
|
| content | string | - | 消息内容 |
|
|
|
| messageType | string | 'text' | 消息类型：text/image/file |
|
|
|
|
|
|
**返回**: `Promise<ChatMessage>`
|
|
|
|
|
|
```typescript
|
|
|
interface ChatMessage {
|
|
|
id: string
|
|
|
fromDevice: string
|
|
|
toDevice: string
|
|
|
content: string
|
|
|
messageType: 'text' | 'image' | 'file' | 'system'
|
|
|
timestamp: number
|
|
|
isRead: boolean
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
#### get_chat_history
|
|
|
|
|
|
获取与指定设备的聊天历史。
|
|
|
|
|
|
```typescript
|
|
|
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
|
|
|
|
|
|
删除与指定设备的聊天历史。
|
|
|
|
|
|
```typescript
|
|
|
invoke('delete_chat_history', { deviceId: string })
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| deviceId | string | 目标设备 ID |
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
### 文件传输
|
|
|
|
|
|
#### start_http_server
|
|
|
|
|
|
启动 HTTPS 文件服务，接收文件上传。
|
|
|
|
|
|
```typescript
|
|
|
invoke('start_http_server')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### select_file
|
|
|
|
|
|
打开文件选择对话框。
|
|
|
|
|
|
```typescript
|
|
|
invoke<FileMetadata | null>('select_file')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<FileMetadata | null>`
|
|
|
|
|
|
```typescript
|
|
|
interface FileMetadata {
|
|
|
name: string // 文件名
|
|
|
path: string // 文件完整路径
|
|
|
size: number // 文件大小（字节）
|
|
|
mimeType?: string // MIME 类型
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
#### send_file
|
|
|
|
|
|
发送文件到指定设备。
|
|
|
|
|
|
```typescript
|
|
|
invoke<FileTransfer>('send_file', {
|
|
|
deviceId: string,
|
|
|
fileId: string,
|
|
|
filePath: string
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| deviceId | string | 目标设备 ID |
|
|
|
| fileId | string | 文件传输 ID（UUID） |
|
|
|
| filePath | string | 本地文件路径 |
|
|
|
|
|
|
**返回**: `Promise<FileTransfer>`
|
|
|
|
|
|
```typescript
|
|
|
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
|
|
|
|
|
|
取消文件传输。
|
|
|
|
|
|
```typescript
|
|
|
invoke('cancel_transfer', { fileId: string })
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| fileId | string | 传输 ID |
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### get_transfer_history
|
|
|
|
|
|
获取与指定设备的文件传输历史。
|
|
|
|
|
|
```typescript
|
|
|
invoke<FileTransfer[]>('get_transfer_history', {
|
|
|
deviceId: string,
|
|
|
limit?: number
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 默认值 | 说明 |
|
|
|
|------|------|--------|------|
|
|
|
| deviceId | string | - | 目标设备 ID |
|
|
|
| limit | number | 50 | 返回条数限制 |
|
|
|
|
|
|
**返回**: `Promise<FileTransfer[]>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### open_file_location
|
|
|
|
|
|
在系统文件管理器中打开文件所在位置。
|
|
|
|
|
|
```typescript
|
|
|
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
|
|
|
|
|
|
获取应用配置。
|
|
|
|
|
|
```typescript
|
|
|
invoke<AppConfig>('get_app_config')
|
|
|
```
|
|
|
|
|
|
**返回**: `Promise<AppConfig>`
|
|
|
|
|
|
```typescript
|
|
|
interface AppConfig {
|
|
|
deviceId: string // 本机设备 ID
|
|
|
deviceName: string // 设备名称
|
|
|
downloadDir: string // 下载目录
|
|
|
wsPort: number // WebSocket 端口
|
|
|
httpPort: number // HTTP 端口
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
#### update_device_name
|
|
|
|
|
|
更新设备名称。
|
|
|
|
|
|
```typescript
|
|
|
invoke('update_device_name', { name: string })
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| name | string | 新的设备名称 |
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
#### update_download_dir
|
|
|
|
|
|
更新文件下载目录。
|
|
|
|
|
|
```typescript
|
|
|
invoke('update_download_dir', { path: string })
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
| 参数 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| path | string | 新的下载目录路径 |
|
|
|
|
|
|
**返回**: `Promise<void>`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 事件系统
|
|
|
|
|
|
通过 `@tauri-apps/api/event` 的 `listen` 函数监听后端事件。
|
|
|
|
|
|
### device:found
|
|
|
|
|
|
发现新设备时触发。
|
|
|
|
|
|
```typescript
|
|
|
import { listen } from '@tauri-apps/api/event'
|
|
|
|
|
|
listen<DeviceInfo>('device:found', (event) => {
|
|
|
console.log('发现设备:', event.payload)
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**Payload**: `DeviceInfo`
|
|
|
|
|
|
---
|
|
|
|
|
|
### device:lost
|
|
|
|
|
|
设备离线时触发。
|
|
|
|
|
|
```typescript
|
|
|
listen<string>('device:lost', (event) => {
|
|
|
console.log('设备离线:', event.payload) // device_id
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**Payload**: `string` (device_id)
|
|
|
|
|
|
---
|
|
|
|
|
|
### chat:message
|
|
|
|
|
|
收到聊天消息时触发。
|
|
|
|
|
|
```typescript
|
|
|
listen<ChatMessage>('chat:message', (event) => {
|
|
|
console.log('收到消息:', event.payload)
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**Payload**: `ChatMessage`
|
|
|
|
|
|
---
|
|
|
|
|
|
### file:progress
|
|
|
|
|
|
文件传输进度更新时触发。
|
|
|
|
|
|
```typescript
|
|
|
listen<TransferProgressEvent>('file:progress', (event) => {
|
|
|
console.log('传输进度:', event.payload)
|
|
|
})
|
|
|
```
|
|
|
|
|
|
**Payload**: `TransferProgressEvent`
|
|
|
|
|
|
```typescript
|
|
|
interface TransferProgressEvent {
|
|
|
fileId: string // 传输 ID
|
|
|
progress: number // 进度 0.0 - 1.0
|
|
|
transferredBytes: number // 已传输字节数
|
|
|
totalBytes: number // 总字节数
|
|
|
status: TransferStatus // 传输状态
|
|
|
fileName?: string // 文件名（接收方）
|
|
|
localPath?: string // 本地路径（接收方）
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 错误处理
|
|
|
|
|
|
所有命令在出错时会抛出 `CommandError`：
|
|
|
|
|
|
```typescript
|
|
|
interface CommandError {
|
|
|
code: string // 错误代码
|
|
|
message: string // 错误信息
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**常见错误代码**:
|
|
|
|
|
|
| 代码 | 说明 |
|
|
|
|------|------|
|
|
|
| `DB_ERROR` | 数据库操作错误 |
|
|
|
| `IO_ERROR` | 文件 IO 错误 |
|
|
|
| `WS_ERROR` | WebSocket 错误 |
|
|
|
| `DEVICE_NOT_FOUND` | 设备不存在 |
|
|
|
| `NOT_CONNECTED` | 未建立连接 |
|
|
|
| `TRANSFER_ERROR` | 传输错误 |
|
|
|
|
|
|
**使用示例**：
|
|
|
|
|
|
```typescript
|
|
|
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 })
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 完整示例
|
|
|
|
|
|
### 设备发现与聊天
|
|
|
|
|
|
```typescript
|
|
|
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')
|
|
|
```
|
|
|
|
|
|
### 文件传输
|
|
|
|
|
|
```typescript
|
|
|
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()
|
|
|
```
|