Ghost Downloader

中文

English

中文

English

Appearance

API 接口说明 ​

注意

API 接口将在 Ghost Downloader v3.6 版本中正式推出。本文档为预览版，随着开发进展可能会有所变化。

本文档提供了 Ghost Downloader 插件系统的详细 API 参考，帮助开发者了解可用的接口、类和方法。

核心 API ​

GhostPlugin 类 ​

所有插件必须继承的基类，提供插件的基本功能和生命周期管理。

python
class GhostPlugin:
    def __init__(self, app):
        """
        初始化插件
        
        参数:
            app: 应用程序实例
        """
        pass
        
    def initialize(self):
        """
        插件初始化，在应用程序加载插件时调用
        
        返回:
            bool: 初始化是否成功
        """
        pass
        
    def shutdown(self):
        """
        插件关闭，在应用程序卸载插件时调用
        
        返回:
            bool: 关闭是否成功
        """
        pass
        
    def get_settings(self):
        """
        获取插件设置
        
        返回:
            PluginSettings: 插件设置实例
        """
        pass
        
    def on(self, event, callback):
        """
        注册事件监听器
        
        参数:
            event: 事件名称
            callback: 回调函数
        
        返回:
            int: 监听器ID
        """
        pass
        
    def off(self, event, listener_id):
        """
        移除事件监听器
        
        参数:
            event: 事件名称
            listener_id: 监听器ID
        
        返回:
            bool: 是否成功移除
        """
        pass
        
    def emit(self, event, *args, **kwargs):
        """
        触发事件
        
        参数:
            event: 事件名称
            *args, **kwargs: 传递给事件监听器的参数
        """
        pass

PluginSettings 类 ​

用于管理插件设置的类。

python
class PluginSettings:
    def get(self, key, default=None):
        """
        获取设置值
        
        参数:
            key: 设置键名
            default: 默认值，如果设置不存在则返回此值
        
        返回:
            设置值或默认值
        """
        pass
        
    def set(self, key, value):
        """
        设置值
        
        参数:
            key: 设置键名
            value: 设置值
        
        返回:
            bool: 是否成功设置
        """
        pass
        
    def has(self, key):
        """
        检查设置是否存在
        
        参数:
            key: 设置键名
        
        返回:
            bool: 设置是否存在
        """
        pass
        
    def remove(self, key):
        """
        移除设置
        
        参数:
            key: 设置键名
        
        返回:
            bool: 是否成功移除
        """
        pass
        
    def clear(self):
        """
        清除所有设置
        
        返回:
            bool: 是否成功清除
        """
        pass

Logger 类 ​

提供日志记录功能的类。

python
class Logger:
    def debug(self, message):
        """记录调试信息"""
        pass
        
    def info(self, message):
        """记录信息"""
        pass
        
    def warning(self, message):
        """记录警告"""
        pass
        
    def error(self, message):
        """记录错误"""
        pass
        
    def set_level(self, level):
        """
        设置日志级别
        
        参数:
            level: 日志级别 ("debug", "info", "warning", "error")
        """
        pass

下载 API ​

DownloadManager 类 ​

管理下载任务的类。

python
class DownloadManager:
    def create_task(self, url, save_path, options=None):
        """
        创建下载任务
        
        参数:
            url: 下载链接
            save_path: 保存路径
            options: 下载选项
        
        返回:
            DownloadTask: 下载任务实例
        """
        pass
        
    def start_task(self, task_id):
        """
        开始下载任务
        
        参数:
            task_id: 任务ID
        
        返回:
            bool: 是否成功开始
        """
        pass
        
    def pause_task(self, task_id):
        """
        暂停下载任务
        
        参数:
            task_id: 任务ID
        
        返回:
            bool: 是否成功暂停
        """
        pass
        
    def resume_task(self, task_id):
        """
        恢复下载任务
        
        参数:
            task_id: 任务ID
        
        返回:
            bool: 是否成功恢复
        """
        pass
        
    def cancel_task(self, task_id):
        """
        取消下载任务
        
        参数:
            task_id: 任务ID
        
        返回:
            bool: 是否成功取消
        """
        pass
        
    def get_task(self, task_id):
        """
        获取下载任务
        
        参数:
            task_id: 任务ID
        
        返回:
            DownloadTask: 下载任务实例
        """
        pass
        
    def get_all_tasks(self):
        """
        获取所有下载任务
        
        返回:
            list: 下载任务列表
        """
        pass
        
    def on(self, event, callback):
        """
        注册事件监听器
        
        支持的事件:
        - task_created: 任务创建时触发
        - task_started: 任务开始时触发
        - task_paused: 任务暂停时触发
        - task_resumed: 任务恢复时触发
        - task_cancelled: 任务取消时触发
        - task_completed: 任务完成时触发
        - task_failed: 任务失败时触发
        - task_progress: 任务进度更新时触发
        
        参数:
            event: 事件名称
            callback: 回调函数
        
        返回:
            int: 监听器ID
        """
        pass

DownloadTask 类 ​

表示下载任务的类。

python
class DownloadTask:
    @property
    def id(self):
        """任务ID"""
        pass
        
    @property
    def url(self):
        """下载链接"""
        pass
        
    @property
    def save_path(self):
        """保存路径"""
        pass
        
    @property
    def file_name(self):
        """文件名"""
        pass
        
    @property
    def status(self):
        """
        任务状态
        
        可能的值:
        - "pending": 等待中
        - "downloading": 下载中
        - "paused": 已暂停
        - "completed": 已完成
        - "cancelled": 已取消
        - "failed": 失败
        """
        pass
        
    @property
    def progress(self):
        """下载进度 (0-100)"""
        pass
        
    @property
    def speed(self):
        """下载速度 (bytes/s)"""
        pass
        
    @property
    def size(self):
        """文件总大小 (bytes)"""
        pass
        
    @property
    def downloaded(self):
        """已下载大小 (bytes)"""
        pass
        
    @property
    def remaining(self):
        """剩余时间 (秒)"""
        pass
        
    @property
    def created_at(self):
        """创建时间"""
        pass
        
    @property
    def started_at(self):
        """开始时间"""
        pass
        
    @property
    def completed_at(self):
        """完成时间"""
        pass
        
    @property
    def error(self):
        """错误信息"""
        pass
        
    @property
    def options(self):
        """下载选项"""
        pass

ProtocolHandler 类 ​

自定义下载协议处理器的基类。

python
class ProtocolHandler:
    def can_handle(self, url):
        """
        检查是否可以处理指定URL
        
        参数:
            url: 下载链接
        
        返回:
            bool: 是否可以处理
        """
        pass
        
    def process(self, task):
        """
        处理下载任务
        
        参数:
            task: 下载任务实例
        
        返回:
            bool: 是否成功处理
        """
        pass

UI API ​

UIManager 类 ​

管理用户界面的类。

python
class UIManager:
    def create_action(self, text, callback, icon=None, shortcut=None, tooltip=None):
        """
        创建动作
        
        参数:
            text: 动作文本
            callback: 回调函数
            icon: 图标
            shortcut: 快捷键
            tooltip: 工具提示
        
        返回:
            Action: 动作实例
        """
        pass
        
    def add_menu_action(self, menu, action, before=None):
        """
        添加菜单动作
        
        参数:
            menu: 菜单名称
            action: 动作实例
            before: 插入位置
        
        返回:
            bool: 是否成功添加
        """
        pass
        
    def add_toolbar_action(self, action):
        """
        添加工具栏动作
        
        参数:
            action: 动作实例
        
        返回:
            bool: 是否成功添加
        """
        pass
        
    def register_settings_page(self, id, title, widget_class):
        """
        注册设置页面
        
        参数:
            id: 页面ID
            title: 页面标题
            widget_class: 设置页面控件类
        
        返回:
            bool: 是否成功注册
        """
        pass
        
    def show_message(self, title, message, type="info"):
        """
        显示消息对话框
        
        参数:
            title: 标题
            message: 消息内容
            type: 消息类型 ("info", "warning", "error", "question")
        """
        pass
        
    def show_notification(self, message, duration=3000):
        """
        显示通知
        
        参数:
            message: 通知内容
            duration: 显示时间 (毫秒)
        """
        pass

SettingsWidget 类 ​

用于创建设置页面的基类。

python
class SettingsWidget:
    def __init__(self, parent=None):
        """
        初始化设置控件
        
        参数:
            parent: 父控件
        """
        pass
        
    def save_settings(self):
        """
        保存设置
        
        返回:
            bool: 是否成功保存
        """
        pass
        
    def load_settings(self):
        """
        加载设置
        
        返回:
            bool: 是否成功加载
        """
        pass

工具 API ​

FileSystem 类 ​

提供文件系统操作的类。

python
class FileSystem:
    def read_file(self, path, encoding="utf-8"):
        """
        读取文件内容
        
        参数:
            path: 文件路径
            encoding: 编码
        
        返回:
            str: 文件内容
        """
        pass
        
    def write_file(self, path, content, encoding="utf-8"):
        """
        写入文件内容
        
        参数:
            path: 文件路径
            content: 文件内容
            encoding: 编码
        
        返回:
            bool: 是否成功写入
        """
        pass
        
    def file_exists(self, path):
        """
        检查文件是否存在
        
        参数:
            path: 文件路径
        
        返回:
            bool: 文件是否存在
        """
        pass
        
    def dir_exists(self, path):
        """
        检查目录是否存在
        
        参数:
            path: 目录路径
        
        返回:
            bool: 目录是否存在
        """
        pass
        
    def create_dir(self, path):
        """
        创建目录
        
        参数:
            path: 目录路径
        
        返回:
            bool: 是否成功创建
        """
        pass
        
    def list_dir(self, path):
        """
        列出目录内容
        
        参数:
            path: 目录路径
        
        返回:
            list: 目录内容列表
        """
        pass

Network 类 ​

提供网络操作的类。

python
class Network:
    async def http_get(self, url, headers=None, params=None, timeout=30):
        """
        发送HTTP GET请求
        
        参数:
            url: 请求URL
            headers: 请求头
            params: 请求参数
            timeout: 超时时间 (秒)
        
        返回:
            Response: 响应对象
        """
        pass
        
    async def http_post(self, url, data=None, json=None, headers=None, timeout=30):
        """
        发送HTTP POST请求
        
        参数:
            url: 请求URL
            data: 表单数据
            json: JSON数据
            headers: 请求头
            timeout: 超时时间 (秒)
        
        返回:
            Response: 响应对象
        """
        pass
        
    async def download_file(self, url, save_path, progress_callback=None, headers=None, timeout=30):
        """
        下载文件
        
        参数:
            url: 下载链接
            save_path: 保存路径
            progress_callback: 进度回调函数
            headers: 请求头
            timeout: 超时时间 (秒)
        
        返回:
            bool: 是否成功下载
        """
        pass

Response 类 ​

表示HTTP响应的类。

python
class Response:
    @property
    def status_code(self):
        """状态码"""
        pass
        
    @property
    def headers(self):
        """响应头"""
        pass
        
    @property
    def cookies(self):
        """Cookie"""
        pass
        
    async def text(self):
        """
        获取响应文本
        
        返回:
            str: 响应文本
        """
        pass
        
    async def json(self):
        """
        获取JSON响应
        
        返回:
            dict: JSON数据
        """
        pass
        
    async def bytes(self):
        """
        获取二进制响应
        
        返回:
            bytes: 二进制数据
        """
        pass

事件系统 ​

Ghost Downloader 使用事件系统进行组件间通信。以下是主要的事件：

应用程序事件 ​

  • app:startup: 应用程序启动时触发
  • app:shutdown: 应用程序关闭时触发
  • app:settings_changed: 应用程序设置更改时触发
  • app:theme_changed: 主题更改时触发
  • app:language_changed: 语言更改时触发

下载管理器事件 ​

  • download_manager:task_created: 任务创建时触发
  • download_manager:task_started: 任务开始时触发
  • download_manager:task_paused: 任务暂停时触发
  • download_manager:task_resumed: 任务恢复时触发
  • download_manager:task_cancelled: 任务取消时触发
  • download_manager:task_completed: 任务完成时触发
  • download_manager:task_failed: 任务失败时触发
  • download_manager:task_progress: 任务进度更新时触发

插件管理器事件 ​

  • plugin_manager:plugin_loaded: 插件加载时触发
  • plugin_manager:plugin_unloaded: 插件卸载时触发
  • plugin_manager:plugin_enabled: 插件启用时触发
  • plugin_manager:plugin_disabled: 插件禁用时触发

自定义事件 ​

插件可以发出自定义事件，建议使用以下格式：

plugin_id:event_name

例如：

python
# 发出事件
self.emit("my_plugin:data_ready", data)

# 监听事件
self.app.plugin_manager.on("my_plugin:data_ready", self.on_data_ready)

常量 ​

下载状态常量 ​

python
DOWNLOAD_STATUS = {
    "PENDING": "pending",
    "DOWNLOADING": "downloading",
    "PAUSED": "paused",
    "COMPLETED": "completed",
    "CANCELLED": "cancelled",
    "FAILED": "failed"
}

消息类型常量 ​

python
MESSAGE_TYPE = {
    "INFO": "info",
    "WARNING": "warning",
    "ERROR": "error",
    "QUESTION": "question"
}

日志级别常量 ​

python
LOG_LEVEL = {
    "DEBUG": "debug",
    "INFO": "info",
    "WARNING": "warning",
    "ERROR": "error"
}

辅助函数 ​

python
def format_size(size, precision=2):
    """
    格式化文件大小
    
    参数:
        size: 文件大小 (bytes)
        precision: 精度
    
    返回:
        str: 格式化后的大小
    """
    pass
    
def format_time(seconds):
    """
    格式化时间
    
    参数:
        seconds: 时间 (秒)
    
    返回:
        str: 格式化后的时间
    """
    pass
    
def format_speed(bytes_per_second):
    """
    格式化速度
    
    参数:
        bytes_per_second: 速度 (bytes/s)
    
    返回:
        str: 格式化后的速度
    """
    pass
    
def parse_url(url):
    """
    解析URL
    
    参数:
        url: URL
    
    返回:
        dict: 解析结果
    """
    pass
    
def generate_id():
    """
    生成唯一ID
    
    返回:
        str: 唯一ID
    """
    pass

使用示例 ​

以下是一些 API 使用示例：

创建下载任务 ​

python
# 创建下载任务
async def create_download(self):
    url = "https://example.com/file.zip"
    save_path = "downloads/file.zip"
    
    # 创建任务
    task = self.app.download_manager.create_task(url, save_path, {
        "threads": 8,
        "use_ai": True,
        "headers": {
            "User-Agent": "Ghost Downloader/3.6"
        }
    })
    
    # 启动任务
    self.app.download_manager.start_task(task.id)
    
    # 监听任务完成事件
    def on_task_completed(task_id, task_data):
        if task_id == task.id:
            self.logger.info(f"Task completed: {task_data['file_name']}")
            # 移除监听器
            self.app.download_manager.off("task_completed", listener_id)
    
    # 注册监听器
    listener_id = self.app.download_manager.on("task_completed", on_task_completed)

添加菜单项 ​

python
def add_menu_item(self):
    # 创建动作
    action = self.app.ui_manager.create_action(
        "我的插件选项",
        self.on_menu_item_clicked,
        icon="path/to/icon.png",
        shortcut="Ctrl+Shift+M",
        tooltip="打开我的插件选项"
    )
    
    # 添加到工具菜单
    self.app.ui_manager.add_menu_action("tools", action)
    
def on_menu_item_clicked(self):
    # 显示消息
    self.app.ui_manager.show_message(
        "我的插件",
        "您点击了菜单项！",
        "info"
    )

使用文件系统 API ​

python
async def process_file(self):
    # 检查文件是否存在
    if not self.app.file_system.file_exists("data.json"):
        # 创建目录
        self.app.file_system.create_dir("data")
        
        # 写入文件
        self.app.file_system.write_file(
            "data/data.json",
            '{"version": "1.0.0", "data": []}'
        )
    
    # 读取文件
    content = self.app.file_system.read_file("data/data.json")
    
    # 解析 JSON
    data = json.loads(content)
    
    # 修改数据
    data["data"].append({"timestamp": time.time()})
    
    # 写回文件
    self.app.file_system.write_file(
        "data/data.json",
        json.dumps(data, indent=2)
    )

使用网络 API ​

python
async def fetch_data(self):
    try:
        # 发送 GET 请求
        response = await self.app.network.http_get(
            "https://api.example.com/data",
            headers={
                "Authorization": "Bearer token"
            }
        )
        
        # 检查状态码
        if response.status_code == 200:
            # 解析 JSON 响应
            data = await response.json()
            return data
        else:
            self.logger.error(f"API error: {response.status_code}")
            return None
    except Exception as e:
        self.logger.error(f"Network error: {e}")
        return None

更多信息 ​

有关 API 的更多信息，请参考：

如果您发现任何问题或有改进建议，请在 GitHub 上提交 issue。

© XiaoYouChR 2025. 保留所有权利。