PPX一键生成macOS和Windows平台客户端

介绍

PPX 是一款基于 pywebview 和 PyInstaller 框架,构建 macOS 和 Windows 平台客户端的应用。本应用的视图层支持 Vue、React、Angular、HTML 等,业务层支持 Python 脚本。考虑到某些生物计算场景数据量大,数据私密,因此将数据上传到服务器计算,并不一定是最优解,采用本地 Python 也是一种不错的选择。不过,如果需要调用远程 API,本应用也是支持的。

GitHub:https://github.com/pangao1990/PPX

应用优势

现如今,要说比较火的编程语言当属 JavaScript 和 Python 了,这两门语言都可以独立编写前端页面、后端服务器、手机 APP、电脑客户端等等,无所不能。不过,不同的编程语言有不同的侧重点。比如 JavaScript 写网页得心应手,Python 处理大数据信手拈来。这不,PPX 就是一款结合 JavaScript 和 Python 二者的优点,构建跨平台客户端的框架。

  • 视图层可使用任意前端框架,比如 Vue、React、Angular、HTML 等,迁移无压力
  • 采用 Python 编程语言开发业务层,基于海量模块,开发无限可能
  • 本应用已经封装打包环节,一键生成 macOS 和 Windows 平台的客户端应用。开发者只需关注视图效果和业务逻辑本身,将繁重复杂的打包环节交给本应用处理即可

适用场景

  • 对软件的用户界面有一定美感要求
  • 需要用到 Python 中的人工智能、生信分析等模块
  • 考虑搭建本地应用,使用本机计算和存储资源

适用人群

熟悉 Python3 和 任意一款前端框架,如 Vue、React、Angular、HTML 编程的程序员。

快速上手

应用安装

运行环境

应用下载

利用 git(git 安装教程) 下载应用,如下所示:

shell

1
git clone https://github.com/pangao1990/PPX.git

或者,直接在 github 下载。

shell

1
2
# 进入项目
cd PPX

进入项目,项目清单如下所示:

Jav1

初始化

下载完毕后,运行初始化命令,程序会自动下载安装对应操作平台的所需依赖软件,如下所示:

shell

1
2
# 初始化
pnpm run init

没报错信息,则初始化完成,如下所示:

Jav

Java3

项目根目录多了一个 node_modules 文件夹和 pnpm-lock.yaml 文件,用于存放 pnpm 下载的包。

应用运行

输入如下命令,即可启动应用:

shell

1
pnpm run start

终端显示如下:

JavaScript和Pytho4

同时,启动一个客户端程序,如下:

JavaScript和Python打造跨平台客户端应用——vue-pywebview-pyinstaller-5

整体效果如下所示(gif 图片加载可能有点慢):

JavaScript和Python打造跨平台客户端应用——vue-pywebview-pyinstaller-6

高级用法

客户端引擎介绍

本应用基于 pywebview 构建客户端。而 pywebview 构架构建客户端的原理是利用本地电脑自带的浏览器引擎驱动,模拟生成客户端。本质上还是网页,或者说是一个浏览器,但是感官上和本地客户端没有差别。

那么,基于 pywebview 构架构建客户端的成败或质量,就与本地电脑的浏览器引擎息息相关了。

Windows 系统

在 Windows 系统上,大体上分为两类客户端引擎:正常模式和兼容模式。

  • 正常模式

正常模式下,按照 edgechromium ,edgehtml, mshtml 的客户端引擎依次检索。如果本地电脑 edge 浏览器支持这些引擎,则客户端可以正常启动。否则,请安装对应的 EdgeWebView2Runtime 浏览器引擎。

  • 兼容模式

如果本地电脑 edge 浏览器不支持这些引擎,同时也不想下载 EdgeWebView2Runtime ,那么就可以使用兼容模式。兼容模式的原理就是利用 CEFPython,嵌入 Chromium 的 Web 浏览器控件。也就是只要本地电脑安装了谷歌浏览器 V66 版及其以上版本,即可正常启动客户端。缺点就是生成的安装包体积会增加大约 60M 左右。

macOS 系统

macOS 系统的浏览器引擎就没有那么多版本了,由于 macOS 系统的封闭性,在 macOS 系统就只有一种 WebKit 引擎可用。

不过,在 macOS 系统却存在另一个问题。那就是苹果自主研发的 M 系列芯片。用 x86_64 芯片打包的应用可以在 x86_64 和 M 芯片电脑上运行,用 M 芯片打包的应用只能在 M 芯片电脑上运行。

构建客户端 API

构建客户端的主程序是 main.py ,如下所示:

65

main.py 里面主要是依靠 webview.create_window 和 webview.start 这两个 API 来构建客户端。其他的一些 API,我也会在后面的教程中详细介绍。或者可以直接查看 pywebview 官网 了解详情。

webview.create_window

1
2
3
4
5
6
7
webview.create_window(title, url=None, html=None, js_api=None, width=800,
height=600, x=None, y=None, screen=None, resizable=True, fullscreen=False,
min_size=(200, 100), hidden=False, frameless=False, easy_drag=True,
focus=True, minimized=False, maximized=False, on_top=False,
confirm_close=False, background_color='#FFFFFF', transparent=False,
text_select=False, zoomable=False, draggable=False,
server=http.BottleServer, server_args={}, localization=None)

创建一个新的客户端窗口并返回其实例。在 GUI 循环启动之前,窗口不会显示。如果在 GUI 循环期间调用该函数,则会立即显示该窗口。

  • title 窗口标题。
  • url 要加载的 URL。如果 URL 没有协议前缀,则将其解析为相对于应用程序入口点的路径。或者,可以传递 WSGI 服务器对象来启动本地 Web 服务器。
  • html 要加载的 HTML 代码。如果同时指定了 URL 和 HTML,则 HTML 优先。
  • js_api 将 Python 对象暴露给当前应用窗口的 DOM。即可在 Javascript 代码中通过调用 window.pywebview.api.<methodname>(<parameters>) 执行 Python 对象的方法。调用 Javascript 函数会收到一个 promise ,该 promise 将包含 Python 函数的返回值。只有基本的 Python 对象(如 int、str、dict、…)才能返回到 Javascript。
  • width 窗口宽度。默认值为 800
  • height 窗户高度。默认值为 600
  • x 窗口 x 坐标。默认值 居中
  • y 窗口 y 坐标。默认值 居中
  • screen 屏幕显示窗口。screen 是由 webview.screens 返回的屏幕实例 。
  • resizable 是否可以调整窗口大小。默认值为 True
  • fullscreen 是否开启全屏模式。默认为 False
  • min_size 指定最小窗口大小的元组(宽度、高度)。默认值是 (200, 100)
  • hidden 是否隐藏窗口。默认为 False
  • frameless 是否开启无框窗口。默认值为 False
  • easy_drag 是否开启无框窗口的拖动模式。可通过拖动任何点来移动窗口。默认值为True该参数仅对无框窗口有效,对普通窗口无效。
  • focus 是否创建一个可聚焦的窗口。默认为 True
  • minimized 是否开启最小化模式。默认为 False
  • maximized 是否开启最小化模式。默认为 False
  • on_top 设置窗口始终在其他窗口的顶部。默认为 False
  • confirm_close 是否显示窗口关闭确认对话框。默认为 False
  • background_color 加载 WebView 之前显示的窗口的背景颜色。指定为十六进制颜色。默认是 ‘#FFFFFF’
  • transparent 是否开启透明窗口。默认为 False不支持 Windows 系统。
  • text_select 是否启用 document 文本选择。默认值为 False 。想要单独控制每个元素的文本选择,请使用 CSS 属性 user-select
  • zoomable 是否启用文档缩放。默认为 False
  • draggable 是否启用图像和链接对象拖动。默认为 False
  • vibrancy 启用窗口毛玻璃效果。默认为 False仅支持 macOS 。
  • server 设置自定义 WSGI 服务器实例。默认为 http.BottleServer
  • server_args 传递给服务器实例化的字典参数。
  • localization 传递给每个窗口的本地化字典参数。

webview.start

1
2
3
webview.start(func=None, args=None, gui=None, debug=False, menu=[],
http_server=False, http_port=None, user_agent=None,
server=http.BottleServer, server_args={}, localization={})

启动 GUI 循环,并显示已经创建的窗口。此函数必须从主线程调用。

  • func 启动 GUI 循环时调用的函数。
  • args 调用函数的传参。可以是单个变量,也可以是元组。
  • gui 指定 GUI 模式,可选值为 Nonecefqtgtk。更多细节请查看 渲染器
  • debug 是否启用调试模式。默认为 False
  • http_server 是否启用内置 HTTP 服务器。默认为 False 。如果启用,将会为每个窗口开启一个独立的 HTTP 服务器,并使用随机端口。对于非本地 URL,此参数被忽略。
  • http_port 指定 HTTP 服务器的端口号。默认 随机端口
  • user_agent 设置 User-Agent 字符串。
  • menu 传递菜单对象列表以创建应用程序菜单。
  • server 设置自定义 WSGI 服务器实例。默认为 http.BottleServer
  • server_args 传递给服务器实例化的字典参数。
  • localization 本地化字典参数。

域间通信

这里的通信指的是 JavaScript(视图层,前端)和 Python(业务层,后端)的相互访问。

从 Python 调用 Javascript

Python 代码中调用 window.evaluate_js(code, callback=None) 可以执行 JavaScript 代码。

  • 在视图层代码中,绑定函数到 window
1
2
3
4
5
6
// JavaScript

window['py2js_demo'] = (res) => {
const resDict = JSON.parse(res)
console.log('js', resDict)
}
  • 在业务层代码中,调用视图层的函数。
1
2
3
4
5
6
7
8
9
10
11
12
# Python

import webview

def system_py2js(window):
'''调用js中挂载到window的函数'''
info = {'appName': 'PPX'}
infoJson = json.dumps(info)
window.evaluate_js(f"py2js_demo('{infoJson}')")

window = webview.create_window()
webview.start(system_py2js, window)

从 Javascript 调用 Python

Python 代码中将类的实例传给 create_windowjs_api 。在 JavaScript 代码中调用 pywebview.api.method_name 即可。

  • 在业务层代码中,将类的实例传给 create_windowjs_api
1
2
3
4
5
6
7
8
9
10
11
12
# Python

import webview

class Api:
def system_getAppInfo(self):
return {'appName': 'PPX'}

if __name__ == '__main__':
api = Api()
webview.create_window(js_api=api)
webview.start()
  • 在视图层代码中,调用业务层的函数。
1
2
3
4
5
// JavaScript

window.pywebview.api.system_getAppInfo().then((res) => {
console.log('js', res)
})

打包客户端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
###########
# 简单用法 #
###########

# 初始化
pnpm run init

# 开发模式
pnpm run start

# 正式打包
pnpm run build

# 预打包,带console,方便输出日志信息
pnpm run pre


###########
# 进阶用法 #
###########

# 初始化,cef兼容模式
pnpm run init:cef

# 开发模式,cef兼容模式【仅win系统】
pnpm run start:cef

# 预打包,带console,cef兼容模式【仅win系统】
pnpm run pre:cef

# 预打包,带console,生成文件夹【仅win系统】
pnpm run pre:folder

# 预打包,带console,生成文件夹,cef兼容模式【仅win系统】
pnpm run pre:folder:cef

# 正式打包,cef兼容模式【仅win系统】
pnpm run build:cef

# 正式打包,生成文件夹【仅win系统】
pnpm run build:folder

# 正式打包,生成文件夹,cef兼容模式【仅win系统】
pnpm run build:folder:cef

应用打包分为两步进行:

  • 打包成可执行文件
  • 打包成安装程序

打包成可执行文件

基于 Pyinstaller 将项目代码打包成可执行文件。

  • Windows 环境下打包成 exe 格式的可执行文件。
  • macOS 环境下打包成 app 格式的可执行文件。(用 x86_64 芯片打包的应用可以在 x86_64M 芯片电脑上运行,用 M 芯片打包的应用只能在 M 芯片电脑上运行)

打包过程,会先由 pyapp/spec/getSpec.py 脚本生成 windows.specmacos.spec 打包配置文件,之后基于该配置文件进行打包。

::: tip 注意
这里需要注意一个问题。因 Pyinstaller 的打包机制,可能会造成某些动态库或者 Python 模块并没有被打包进可执行文件。因此,可能出现在生产环境运行没问题。但是打包后,就提示某些动态库或模块丢失。遇到这种情况,就需要在打包配置文件中添加丢失的动态库或模块。
:::

添加动态链接库

也可以简单的理解为, addDll 用于添加文件

1
2
3
4
5
6
7
# 示例
# 动态库是以元组形式字符串添加
# 以下示例表示将本地包中的 icudtl.dat 和 zh-CN.pak 文件添加到打包中
addDll = """
('../../pyapp/pyenv/pyenvCEF/Lib/site-packages/cefpython3/icudtl.dat', './'),
('../../pyapp/pyenv/pyenvCEF/Lib/site-packages/cefpython3/locales/zh-CN.pak','./locales')
"""
添加 Python 模块

也可以简单的理解为, addModules 用于添加文件夹

1
2
3
# 模块是以元组形式字符串添加
# 以下示例表示将本地包中的 requests 模块整体添加到打包中
addModules = "('../../gui/dist', 'web'), ('../../static', 'static')"

打包成安装程序

  • Windows 环境下,基于 InnoSetup ,打包成 exe 格式的安装程序
  • macOS 环境下,基于 appdmg ,打包成 dmg 格式的安装程序
打包成 exe

打包过程,会先由 pyapp/package/exe/getIss.py 脚本生成 InnoSetup.iss 打包配置文件,之后基于该配置文件进行打包。

打包所需的数据均来自于 pyapp/config/config.py 配置文件。该文件几乎不需要修改。

::: warning 注意
值得一提的是,安装包的唯一 GUID 。这个唯一编号取自于 pyapp/config/config.py 配置文件。在 pnpm run init 初始化之前,需要手动把 pyapp/config/config.py 配置文件中的 appISSID 置空,PPX 会自动生成一个唯一 appISSID ,生成后请勿修改!否则安装程序将会重复安装多个应用,而非覆盖安装。
:::

1
2
3
4
# pyapp/config/config.py

# 初始化之前,请手动将 appISSID 设置为 ''
appISSID = '' # Inno Setup 打包唯一编号。在执行 pnpm run init 之前,请设置为空,程序会自动生成唯一编号,生成后请勿修改!!!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# pyapp/package/exe/getIss.py

import os
from config.config import Config

appName = Config.appName # 应用名称
appVersion = Config.appVersion # 应用版本号
appVersion = appVersion[1:] # 去掉第一位V
appDeveloper = Config.appDeveloper # 应用开发者
appBlogs = Config.appBlogs # 个人博客
rootDir = os.path.dirname(pyappDir)
buildDir = os.path.join(rootDir, 'build')
logoPath = os.path.join(rootDir, 'pyapp', 'icon', 'logo.ico')
appISSID = Config.appISSID # 安装包唯一GUID
打包成 dmg

打包过程,会先由 pyapp/package/dmg/getJson.py 脚本生成 dmg.json 打包配置文件,之后基于该配置文件进行打包。

在打包之前,请替换 pyapp/package/dmg/bg.png 背景图片和 pyapp/package/dmg/潘高的小站.webloc 网址文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
"title": "''' + appName + '''",
"icon": "../../icon/logo.icns",
"background": "bg.png",
"icon-size": 50,
"contents": [
{
"x": 160,
"y": 120,
"type": "file",
"path": "../../../build/''' + appName + '''.app"
},
{
"x": 430,
"y": 120,
"type": "link",
"path": "/Applications"
},
{
"x": 450,
"y": 243,
"type": "file",
"path": "./潘高的小站.webloc"
}
],
"window": {
"size": {
"width": 590,
"height": 416
}
},
"format": "UDBZ"
}

跨平台打包

在本机电脑操作,只能打包出本系统对应的程序包。如果想打包出两种系统的程序包,需要借助 Github Action 的能力。

::: warning 提示
这里需要有 Github 操作基础。
:::

PPX 已经预先写好了 .github/workflows/main.yml 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
name: build
on:
push:
branches: [main]
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [windows-latest, macos-latest]
steps:
- name: 拉取项目代码
uses: actions/checkout@v3

- name: 安装node环境
uses: actions/setup-node@v3
with:
node-version: "19"

- name: 安装pnpm
uses: pnpm/action-setup@v2
id: pnpm-install
with:
version: "8.3.1"
run_install: false

- name: 获取pnpm仓库目录
id: pnpm-cache
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT

- name: 设置pnpm缓存
uses: actions/cache@v3
with:
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-

- name: 安装Python3环境
uses: actions/setup-python@v4
with:
python-version: "3.9"
cache: "pip"

- name: 初始化打包环境
run: pnpm run init

- name: 开始打包
run: pnpm run build

- name: 上传打包完成的程序包
uses: actions/upload-artifact@v3
with:
name: Setup
retention-days: 1
path: build/*-*_*.*

将代码提交至 Github 后,在 Actions 下会自动生成两种系统的程序包。

打包后程序白屏的一些解决方案

PPX 显示 GUI 窗口的本质是显示 HTML 页面,因此出现白屏现象极有可能是系统不支持正常显示 HTML 页面。

一般情况下,macOS 不会出现白屏。在 Windows 系统下出现白屏,可以按以下步骤排查:

  • 确保底层依赖软件已经正确安装

  • 使用 CEF 模式打包

    CEF 模式打包本质上是内置一个 Chrome v66 的浏览器,用于支持显示 HTML 页面。

    1
    pnpm run build:cef

数据库迁移

在 api/db/models.py 中修改数据库格式后,执行以下命令迁移数据库。

注意:迁移数据库前,需要对 sqlalchemy 数据库对象映射框架有所了解。

1
2
# 迁移数据库
m=备注迁移信息 pnpm run alembic

HMR 原理

  • 使用 npm-run-all 并行启用 vite(自带热更新) 和 pywebview
  • 使用 nodemon 监听 api/* pyapp/* main.py 等文件,有修改自动重启应用,达到 HRM 效果

*注:这里感谢 WnagoiYy 同学的 PR。

注意问题

  • 在 Windows 系统下,只能打包 exe 等适用于 Windows 的程序,不能打包 mac 系统下的 app 程序。同理,mac 也是一样。(不过,基于 Github Action 可实现同时打包两种安装包)
  • 在 Windows 系统下,请不要使用中文路径,否则可能会出现 cannot call null pointer pointer from cdata ‘int(_)(void _, int)’ 等错误信息。mac 系统无此问题。