PyWebView 跨平台桌面应用开发指南

在 index.html 中：

<script>
async function callPython() {
    // 调用 Python 的 greet 方法
    const result = await pywebview.api.greet("World");
    alert(result);
}
</script>
<button onclick="callPython()">点击调用 Python</button>

2. Python 调用 JS

你也可以在 Python 代码中执行 JavaScript 代码片段，例如修改网页标题或获取网页数据。

def execute_js(window):
    # 执行 JS 代码
    window.evaluate_js('document.body.style.backgroundColor = "#f0f0f0";')

window = webview.create_window('Python 调用 JS', 'https://example.com')
webview.start(execute_js, window)

开发模式建议

根据你的项目需求，通常有两种开发架构：

1. 无服务器架构 (Server-less)：
   • 直接加载本地的 HTML 文件或字符串。
   • 适合界面相对简单、不需要复杂路由的工具类软件。
2. Flask/FastAPI 集成架构：
   • 使用 Flask 或 FastAPI 作为后端 Web 服务器，PyWebView 作为'外壳'加载 localhost。
   • 适合界面复杂、逻辑多、或者原本就是 Web 项目的应用。
   • *注意：在生产环境中，建议使用 waitress 等 WSGI 服务器替代 Flask 自带的开发服务器，以获得更好的性能。

打包发布

开发完成后，可以使用 PyInstaller 将你的 Python 代码和 Web 资源打包成一个独立的可执行文件（如 Windows 下的 .exe），这样用户在没有安装 Python 环境的电脑上也能直接运行。

pyinstaller --onefile --windowed your_app.py

PyWebView 实际应用案例

PyWebView 因其轻量、跨平台和易上手的特性，非常适合用于构建各类中小型桌面工具。以下是 10 个典型且实用的应用案例：

1. 跨平台待办事项（To-Do）应用

• 描述：经典的任务管理器，支持添加、编辑、删除和标记完成任务。
• 技术亮点：使用 HTML/CSS/JS 构建现代化界面；Python 后端负责数据持久化（如 JSON 文件或 SQLite）；通过 js_api 实现前后端通信。
• 优势：一套代码在 Windows、macOS、Linux 上均能提供原生体验。

2. Flask/FastAPI 集成的桌面应用

• 描述：将现有的 Web 应用（如内部管理系统、数据看板）封装为桌面程序。
• 技术亮点：启动一个本地 HTTP 服务器（如 http://127.0.0.1:5000）；PyWebView 窗口加载该本地 URL；完全复用 Web 前端和后端逻辑。
• 应用场景：企业内部工具、数据分析仪表盘、原型快速验证。

3. 轻量级自定义浏览器

• 描述：一个功能精简的网页浏览器，可嵌入到其他应用中。
• 技术亮点：利用 create_window(url=...) 加载任意网页；可自定义地址栏、前进/后退按钮等；设置 webview.settings['ALLOW_DOWNLOADS'] = True 支持文件下载。
• 应用场景：应用内帮助文档、在线内容展示模块。

4. 文件对话框与系统集成工具

• 描述：调用操作系统原生的文件选择器，实现'打开'、'保存'功能。
• 应用场景：文本编辑器、图像处理工具、配置文件导入导出。
• 技术亮点：

# 在 Python API 中
def open_file(self):
    file_path = window.create_file_dialog(webview.OPEN_DIALOG)
    return file_path[0] if file_path else None

5. 多窗口管理应用

• 描述：支持同时打开多个窗口，例如主窗口 + 设置窗口，或类似 IDE 的多标签页。
• 技术亮点：通过 webview.create_window() 动态创建新窗口；使用 webview.windows 列表管理所有窗口实例。
• 应用场景：复杂的数据分析软件、多文档编辑器。

6. JavaScript 与 Python 双向通信演示

• 描述：专门用于展示如何建立稳固的双向通信机制。
• 技术亮点：JS 调用 Python 函数处理业务逻辑（如计算、文件操作）；Python 通过 evaluate_js() 或事件机制通知 JS 更新 UI。
• 应用场景：这是几乎所有 PyWebView 应用的核心基础。

7. 全屏与窗口状态控制（媒体播放器）

• 描述：控制应用窗口的全屏、最小化、最大化等状态。
• 应用场景：视频播放器、游戏启动器、沉浸式阅读器。
• 技术亮点：

# 进入全屏
window.toggle_fullscreen()
# 最小化窗口
window.minimize()

8. 文件拖放（Drag & Drop）应用

• 描述：用户可以直接将文件从桌面拖拽到应用窗口中。
• 技术亮点：在 HTML 中监听 drop 事件；获取文件路径后，通过 pywebview.api 传递给 Python 处理。
• 应用场景：图片批量处理器、日志分析工具、文件转换器。

9. 本地化（i18n）与多语言支持

• 描述：为应用提供多种语言界面。
• 技术亮点：Python 后端根据系统语言或用户设置加载对应的翻译文件（如 .json）；通过 API 将翻译后的文本传递给前端渲染。
• 应用场景：面向全球用户的软件产品。

10. 自定义菜单与系统托盘应用

• 描述：创建专业的应用菜单栏，并在系统托盘（通知区域）显示图标，支持后台运行。
• 技术亮点：使用 window.create_menu() 创建菜单；结合 pystray 等库实现系统托盘功能。
• 应用场景：网络监控工具、下载管理器、即时通讯客户端。

PyWebView 文件操作实现

在 PyWebView 中实现文件操作是构建桌面应用的核心能力之一。由于 Web 前端（HTML/JS）本身受限于浏览器安全沙箱，无法直接访问本地文件系统，因此必须通过 Python 后端 来完成实际的文件读写、选择、保存等操作，并通过 js_api 双向通信机制 与前端交互。

场景一：让用户选择并打开一个文件（如文本编辑器）

原理

前端触发 → 调用 Python API → 弹出系统原生'打开文件'对话框 → 返回文件路径 → Python 读取内容 → 返回给前端显示。

Python 后端代码

import webview

class FileHandler:
    def __init__(self):
        self.window = None  # 将在 start 时注入

    def open_file(self):
        # 弹出系统原生的'打开文件'对话框
        file_paths = self.window.create_file_dialog(
            webview.OPEN_DIALOG,
            file_types=('Text Files (*.txt)', 'All Files (*.*)')
        )
        if file_paths and len(file_paths) > 0:
            file_path = file_paths[0]
            try:
                with open(file_path, 'r', encoding='utf-8') as f:
                    content = f.read()
                return {'success': True, 'content': content, 'path': file_path}
            except Exception as e:
                return {'success': False, 'error': str(e)}
        return {'success': False, 'error': 'No file selected'}

前端 JavaScript 代码 (index.html)

<script>
async function openFile() {
    const result = await pywebview.api.open_file();
    if (result.success) {
        document.getElementById('editor').value = result.content;
        console.log('Opened:', result.path);
    } else {
        alert('Error: ' + result.error);
    }
}
</script>
<button onclick="openFile()">打开文件</button>
<textarea id="editor"></textarea>

启动应用

if __name__ == '__main__':
    handler = FileHandler()
    window = webview.create_window(
        '文件编辑器', 'index.html', js_api=handler, width=800, height=600
    )
    handler.window = window  # 注入窗口引用
    webview.start(debug=True)

✅ 优势：使用 create_file_dialog 调用的是操作系统原生对话框，用户体验一致且安全。

场景二：将内容保存到用户指定位置（'另存为'）

Python 后端新增方法

def save_file_as(self, content):
    file_path = self.window.create_file_dialog(
        webview.SAVE_DIALOG,
        save_filename='untitled.txt',
        file_types=('Text Files (*.txt)', 'All Files (*.*)')
    )
    if file_path:
        try:
            with open(file_path, 'w', encoding='utf-8') as f:
                f.write(content)
            return {'success': True, 'path': file_path}
        except Exception as e:
            return {'success': False, 'error': str(e)}
    return {'success': False, 'error': 'Save cancelled'}

前端调用

async function saveFile() {
    const content = document.getElementById('editor').value;
    const result = await pywebview.api.save_file_as(content);
    if (result.success) {
        alert('Saved to: ' + result.path);
    } else {
        alert('Save failed: ' + result.error);
    }
}

场景三：直接读写应用私有目录（无需用户选择）

适用于配置文件、缓存、日志等场景。

import os
import json

APP_DATA_DIR = os.path.join(os.path.expanduser("~"), ".myapp")

def ensure_app_dir():
    os.makedirs(APP_DATA_DIR, exist_ok=True)

def save_config(self, config_dict):
    ensure_app_dir()
    config_path = os.path.join(APP_DATA_DIR, "config.json")
    with open(config_path, 'w') as f:
        json.dump(config_dict, f)
    return {'success': True}

def load_config(self):
    config_path = os.path.join(APP_DATA_DIR, "config.json")
    if os.path.exists(config_path):
        with open(config_path, 'r') as f:
            return json.load(f)
    return {}

⚠️ 注意：这类操作不涉及用户交互，但需确保路径权限正确。

场景四：处理拖放（Drag & Drop）的文件

前端监听拖放事件

<div id="drop-zone">拖拽文件到这里</div>
<script>
const dropZone = document.getElementById('drop-zone');
dropZone.addEventListener('dragover', (e) => {
    e.preventDefault();
    dropZone.style.backgroundColor = '#f0f0f0';
});
dropZone.addEventListener('drop', async (e) => {
    e.preventDefault();
    dropZone.style.backgroundColor = '';
    const files = e.dataTransfer.files;
    if (files.length > 0) {
        // 注意：Web 端只能获取文件名，不能直接读取内容！
        const fileName = files[0].name;
        // 将文件名传给 Python，由 Python 决定是否处理
        const result = await pywebview.api.handle_dropped_file(fileName);
        console.log(result);
    }
});
</script>

❗ 重要限制：出于安全原因，JavaScript 无法从拖放事件中获取文件的完整路径，只能拿到文件名。因此，真正的文件处理仍需用户通过 create_file_dialog 选择，或结合其他机制（如 Flask 临时上传）。

安全建议

1. 永远不要信任前端传来的路径：所有文件路径应由 Python 通过 create_file_dialog 获取，避免路径遍历攻击。
2. 限制文件类型：在 file_types 参数中明确允许的扩展名。
3. 异常处理：对 open()、write() 等操作进行 try-except，防止程序崩溃。
4. 编码统一：建议统一使用 utf-8 编码读写文本文件。