# YkPywebview

**Repository Path**: yangke02/yk-pywebview

## Basic Information

- **Project Name**: YkPywebview
- **Description**: pywebview封装库，与typescript开源工具ykvue配合使用，可快速创建web项目和app应用项目。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-25
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YkPywebview

YkPywebview 是一个对 [pywebview](https://gitee.com/yangke02/yk-pywebview) 的增强封装库，旨在简化其 API 使用并提供额外功能，提升 Python 桌面 Web 应用的开发效率。

## 功能特性

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

## 安装

```bash
pip install YkPywebview
```

## 快速开始

### 基本使用

```python
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 类

```python
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](https://gitee.com/yangke02/yk-pywebview/blob/main/YkPywebview/core.py)，它提供了以下内置方法：

#### 日志输出

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

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

#### 任务栏控制

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

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

#### 文件操作

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

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

参数说明：
- `defaultFolder`: 默认文件夹路径
- `fileTypes`: 文件类型过滤器，如 ['.txt', '.png']
- `suggestedName`: 建议的文件名

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

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

参数说明：
- `content`: 要保存的内容
- `defaultFolder`: 默认文件夹路径
- `fileTypes`: 文件类型过滤器
- `suggestedName`: 建议的文件名

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

弹出文件选择对话框，支持自定义对话框标题和文件类型过滤。与 [openFile](file://E:\repos\yk-pywebview\YkPywebview\core.py#L356-L498) 不同的是，此方法只返回文件路径信息而不读取文件内容。

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

返回值：
- `filePath`: 选中的文件路径，如果没有选择则为 None
- `fileName`: 文件名
- `success`: 是否成功选择文件

#### 登录信息管理

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

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

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

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

#### 配置管理

```python
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）的配置管理。

#### 窗口几何信息

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


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


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

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

### 启动函数

```python
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](https://gitee.com/yangke02/yk-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](https://gitee.com/yangke02/yk-pywebview) ~= 3.0
- toml ~= 0.10.2

## 许可证

MIT