@pigman17/task-manager

基于 Vue 3 + naive-ui 的下载管理脚手架，提供完整的下载任务管理 UI。 样式模拟 https://gitee.com/leeke98/transmission-web

快速开始

安装

npm install @pigman17/task-manager

完整 Demo（含后端演示）

# 启动后端演示服务
npm run demo

# 新开终端，启动前端开发服务器
npm run dev

浏览器打开 http://localhost:5173 即可。

前端集成

基础用法

<script setup lang="ts">
import { ref, provide } from 'vue'
import { TaskManager } from '@pigman17/task-manager'
import '@pigman17/task-manager/style.css'
import type { TaskItem, StatusDef } from '@pigman17/task-manager'

const tasks = ref<TaskItem[]>([])

  <TaskManager
    :tasks="tasks"
    @add="handleAdd"
    @remove="handleRemove"
    @start="handleStart"
    @pause="handlePause"
  />
</template>

事件说明

| 事件 | 参数 | 说明 | |------|------|------| | @add | payload: Record<string, any> | 用户提交添加任务表单，数据结构由 #add-form 插槽决定 | | @remove | ids: number[], deleteFiles: boolean | 删除指定的任务，deleteFiles 表示是否同时删除本地文件 | | @start | ids: number[] | 恢复（开始）已暂停的任务 | | @pause | ids: number[] | 暂停正在下载的任务 |

插槽

#add-form — 添加任务的表单

通过 scoped slot prop submit 提交数据、close 关闭弹窗：

<TaskManager ...>
  <template #add-form="{ submit, close }">
    <!-- 自定义表单 -->
    <n-input v-model:value="myId" placeholder="输入资源 ID" />
    <n-button @click="submit({ id: myId })">提交</n-button>
  </template>
  </TaskManager>

#add-footer — 表单底部按钮

<template #add-footer="{ submit, close }">
  <n-button @click="close">取消</n-button>
  <n-button @click="submit(formData)">确认添加</n-button>
</template>

Props

| 属性 | 类型 | 说明 | |------|------|------| | tasks | TaskItem[] | 下载任务列表（必填） | | selectedKeys (v-model) | number[] | 当前选中的任务 ID 列表 | | statusFilter (v-model) | string | 当前状态筛选，'all' 或状态 key | | labelFilter (v-model) | string | 当前标签筛选，'all' 或标签名 |

数据结构

/** 下载任务 */
interface TaskItem {
  id: number
  name: string
  url: string
  status: TaskStatus        // 'waiting' | 'downloading' | 'paused' | 'completed' | 'error' | 'removed'
  progress: number          // 0 ~ 1
  speed: number             // 字节/秒
  downloadedSize: number
  totalSize: number
  labels?: string[]
  dir?: string
  error?: string
  addedDate: number
  completedDate?: number
}

/** 状态定义（由后端下发，前端据此渲染） */
interface StatusDef {
  status: string    // 状态标识，如 'downloading'
  label: string     // 显示文本，如 '下载中'
  icon: string      // 图标名称，如 'CloudDownloadOutline'
  color: string     // 图标颜色，如 '#1BA784'
}

状态定义

组件不硬编码状态列表，而是通过 provide('statuses', statusDefs) 从父组件注入。状态定义由后端在 WebSocket init 消息中下发，或通过 GET /api/statuses 获取。

后端协议

TaskManager 通过 WebSocket 与后端通信。以下是必须实现的协议：

WebSocket 消息

服务端 → 客户端

| type | 数据 | 说明 | |------|------|------| | init | { tasks: TaskItem[], statuses: StatusDef[] } | 初始化，连接时下发 | | added | { task: TaskItem } | 新任务创建 | | progress | { id: number, task: Partial<TaskItem> } | 下载进度更新 | | completed | { id: number, task: { name, status } } | 下载完成 | | error | { id: number, error: string } | 下载出错 | | paused | { id: number } | 任务已暂停 | | started | { id: number } | 任务已恢复 |

客户端 → 服务端

| type | 数据 | 说明 | |------|------|------| | add | { url, name?, dir?, labels?, ... } | 添加下载任务（字段由前端表单决定） | | remove | { id, deleteFiles?: boolean } | 删除任务 | | start | { id } | 恢复暂停的任务 | | pause | { id } | 暂停下载中的任务 |

HTTP 接口

| 路径 | 说明 | |------|------| | GET /health | 健康检查，返回 { ok, tasks } | | GET /api/statuses | 获取状态定义列表 StatusDef[] |

数据持久化

任务列表需持久化。demoServer.cjs 以 downloads/tasks.json 存储：

[
  {
    "id": 1,
    "name": "file.zip",
    "url": "https://example.com/file.zip",
    "status": "paused",
    "progress": 0.45,
    "speed": 0,
    "downloadedSize": 450000,
    "totalSize": 1000000,
    "labels": ["文档"],
    "dir": "",
    "filePath": "C:/downloads/file.zip",
    "customName": "",
    "addedDate": 1717000000000
  }
]

本地开发

# 安装依赖
npm install

# 启动演示后端
npm run demo

# 启动前端开发服务器
npm run dev

# 构建库
npm run build:lib

# 发布到 npm
npm run pub