YkPywebview 26.1.6

A wrapper library for pywebview with enhanced features

YkPywebview

YkPywebview 是一个对 pywebview 的增强封装库，旨在简化其 API 使用并提供额外功能，提升 Python 桌面 Web 应用的开发效率。

功能特性

• 简化 API: 封装 pywebview 核心功能，提供更简洁易用的 API
• 多 API 组合支持: 支持将多个 API 类组合成一个统一的接口
• 配置管理: 支持应用和项目级别的 TOML 配置文件管理
• 窗口状态持久化: 自动保存和恢复窗口位置及大小
• 文件操作: 提供方便的文件打开、选择和保存对话框
• 登录信息存储: 支持本地存储用户登录信息
• 日志输出: 提供向浏览器控制台输出日志的功能
• 任务栏控制: 支持设置任务栏标题和进度条
• 全屏切换: 支持窗口全屏切换功能

安装

pip install YkPywebview

快速开始

基本使用

from YkPywebview.core import start, YkWebviewApi
import os


class MyApi(YkWebviewApi):
    def __init__(self):
        super().__init__()

    def hello(self, name):
        return f"Hello, {name}!"

    def get_current_directory(self):
        return os.getcwd()


if __name__ == "__main__":
    # 启动应用
    start(
        Api=MyApi,
        url="http://localhost:8080",  # 替换为您的网页URL
        title="我的应用",
        width=1000,
        height=700
    )

组合多个 API 类

from YkPywebview.core import start, YkWebviewApi
from YkPywebview.core import CombinedApi


class UserApi(YkWebviewApi):
    def get_user_info(self):
        return {"name": "John", "age": 30}


class FileApi(YkWebviewApi):
    def read_file(self, path):
        with open(path, 'r') as f:
            return f.read()


if __name__ == "__main__":
    # 组合多个API类
    # 在前端项目中可以通过window.pywebview.api.<api_name> 调用UserApi和FileApi的方法，如window.pywebview.api.get_user_info()
    apis = CombinedApi([UserApi, FileApi])
    
    start(
        Api=apis, 
        url="http://localhost:8080",
        title="组合API示例"
    )

核心功能详解

API 基础类 (YkWebviewApi)

所有自定义 API 类都应该继承自 YkWebviewApi，它提供了以下内置方法：

日志输出

def printToTerm(self, msg: str, kind='info'):
    """
    打印日志到终端
    :param msg: 输出的消息
    :param kind: 日志类型 (info, warning, success, error, system)
    """

将消息输出到前端控制台，支持不同类型的日志（info, warning, success, error, system）。

任务栏控制

def setTaskBar(self, title: str, progress: int = 0):
    """
    设置任务栏图标和进度条
    :param title: 任务栏标题
    :param progress: 任务栏进度
    """

设置任务栏标题和进度条。

文件操作

def openFile(self, params=None):
    """
    打开文件选择对话框
    :param params: 包含参数的字典
                   - defaultFolder: 默认文件夹路径
                   - fileTypes: 文件类型过滤器，如 ['.txt', '.png']
                   - suggestedName: 建议的文件名
    """

打开文件选择对话框，支持指定默认目录、文件类型过滤等。

参数说明：

• defaultFolder: 默认文件夹路径
• fileTypes: 文件类型过滤器，如 ['.txt', '.png']
• suggestedName: 建议的文件名

def saveFile(self, params=None):
    """
    打开文件保存对话框
    :param params: 包含参数的字典
                   - content: 要保存的内容
                   - defaultFolder: 默认文件夹路径
                   - fileTypes: 文件类型过滤器
                   - suggestedName: 建议的文件名
    """

打开文件保存对话框，支持保存文本和二进制文件。

参数说明：

• content: 要保存的内容
• defaultFolder: 默认文件夹路径
• fileTypes: 文件类型过滤器
• suggestedName: 建议的文件名

def selectFile(self, params=None):
    """
    弹出文件选择对话框
    :param params: 包含参数的字典
                   - title: 对话框标题，默认为"选择文件"
                   - defaultFolder: 默认文件夹路径
                   - fileTypes: 文件类型过滤器，格式为[('描述', '*.ext'), ...]或['.ext1', '.ext2', ...]
    """

弹出文件选择对话框，支持自定义对话框标题和文件类型过滤。与 openFile 不同的是，此方法只返回文件路径信息而不读取文件内容。

参数说明：

• title: 对话框标题，默认为"选择文件"
• defaultFolder: 默认文件夹路径
• fileTypes: 文件类型过滤器，格式支持 [('描述', '*.ext'), ...] 或 ['.ext1', '.ext2', ...]

返回值：

• filePath: 选中的文件路径，如果没有选择则为 None
• fileName: 文件名
• success: 是否成功选择文件

登录信息管理

def saveLoginInfo(self, userInfo: dict):
    """
    保存用户登录信息到本地文件
    :param userInfo: 用户信息字典
    """

保存用户登录信息到本地文件。

def getLoginInfo(self):
    """
    从本地文件读取用户登录信息
    :return: 用户信息或None
    """

从本地文件读取用户登录信息。

配置管理

def loadAppSettings(self):
    """加载应用配置"""


def loadProjectSettings(self):
    """加载项目配置"""


def saveAppSettings(self, settings: dict):
    """保存应用配置"""


def saveProjectSettings(self, settings: dict):
    """保存项目配置"""


def getAppSettings(self):
    """获取应用配置"""


def getProjectSettings(self):
    """获取项目配置"""


def setAppSettings(self, settings: dict):
    """设置应用配置"""


def setProjectSettings(self, settings: dict):
    """设置项目配置"""

支持应用级别（settings.app.toml）和项目级别（settings.project.toml）的配置管理。

窗口几何信息

def get_window_geometry(self):
    """获取窗口位置和大小信息"""


def save_window_geometry(self):
    """保存窗口位置和大小到配置文件"""


def load_window_geometry(self):
    """从配置文件加载窗口位置和大小"""

获取、保存和加载窗口的位置和大小信息，这些方法会在应用启动和关闭时自动调用。

启动函数

def start(Api, url: str, ssl=True, debug=False, localization=None, title='gf-ui',
          width=900, height=620, text_select=True, confirm_close=True):
    """
    启动 webview 窗口的主函数
    :param Api: 实现的 API 类或类列表
    :param url: 要加载的网页 URL
    :param ssl: 是否启用 SSL 验证
    :param debug: 是否启用调试模式
    :param localization: 本地化字典
    :param title: 窗口标题
    :param width: 窗口宽度
    :param height: 窗口高度
    :param text_select: 是否允许文本选择
    :param confirm_close: 关闭时是否需要确认
    """

启动 pywebview 应用的主要函数。

参数说明：

• Api: 实现的 API 类或类列表
• url: 要加载的网页 URL
• ssl: 是否启用 SSL 验证
• debug: 是否启用调试模式
• localization: 本地化字典
• title: 窗口标题
• width: 窗口宽度
• height: 窗口高度
• text_select: 是否允许文本选择
• confirm_close: 关闭时是否需要确认

配置文件

YkPywebview 支持两种配置文件：

1. settings.app.toml - 应用级别配置
2. settings.project.toml - 项目级别配置

这些文件应该放在项目的工作目录中。

依赖

• pywebview ~= 3.0
• toml ~= 0.10.2

许可证

MIT