English

</div>

文档网站： https://cellium-project.github.io/Cellium/ （推荐 | 更好的阅读体验）

文档导航：

Cellium

Python + HTML/JS 的桌面应用框架。

基于"核心驱动-模块解耦"理念的 Python 桌面应用框架。

通过一个精密的微内核（Core）作为调度中枢，实现了前端交互与后端逻辑的彻底分离。开发者只需将功能封装为独立的"细胞单元"，其余的跨模块通信、并发调度与资源管理均由 Cellium 核心透明完成，让复杂的系统构建变得像拼图一样简单。

| 特点 | 说明 | |------|------| | 核心驱动 | 微内核统一调度，开发者只需关注业务逻辑 | | 模块解耦 | 前后端独立开发，通过协议通信 | | 简单 | 只需写 Python 函数定义功能，前端调用即可 | | 灵活 | 完整 Web 前端生态，任意 UI 框架 | | 轻量 | 基于 MiniBlink，体积小、启动快 |

对比传统方案：

| 方案 | 学习成本 | 开发效率 | UI 灵活性 | |------|---------|---------|----------| | PyQt/Tkinter | 高 | 中 | 低 | | Electron | 中 | 高 | 高 | | Cellium | 低 | 高 | 高 |

示例应用：

Cellium-Serial - 基于 Cellium 框架开发的串口通信工具，打包体积仅 28MB

快速示例：

# app/components/greeter.py
from app.core.interface.base_cell import BaseCell


class Greeter(BaseCell):
    """问候组件：接收文字，添加后缀后返回"""

    @property
    def cell_name(self) -> str:
        """组件唯一标识，用于前端调用"""
        return "greeter"

    def get_commands(self) -> dict:
        """返回可用命令列表"""
        return {
            "greet": "添加问候后缀，例如: greeter:greet:你好"
        }

    def _cmd_greet(self, text: str = "") -> str:
        """添加 Hallo Cellium 后缀"""
        if not text:
            return "Hallo Cellium"
        return f"{text} Hallo Cellium"

<!-- html/index.html -->
<button onclick="window.mbQuery(0, 'greeter:greet:你好', function(){})">问候</button>

直接调用方法

Cellium 组件支持直接调用模式，即前端通过 window.mbQuery() 直接调用后端组件方法，无需配置路由。

1. 后端组件定义

组件只需继承 BaseCell 基类，实现三个核心方法：

| 方法 | 说明 | |------|------| | cell_name | 组件唯一标识，用于前端调用 | | get_commands() | 返回可用命令字典 | | _cmd_<命令名> | 具体命令实现，BaseCell 自动映射 |

BaseCell 自动处理命令映射，无需编写 execute 方法。

2. 前端调用格式

// 格式：window.mbQuery(id, 'cell_name:command[:args]', callback)
// id: 消息ID，通常传 0
// cell_name: 组件的 cell_name 属性值
// command: get_commands() 中定义的命令名
// args: 可选参数，支持字符串或 JSON
// callback: 回调函数，接收返回结果

3. 调用示例

简单参数：

window.mbQuery(0, 'greeter:greet:你好', function(response) {
    console.log(response);  // "你好 Hallo Cellium"
});

复杂数据：

const data = JSON.stringify({name: "Alice", age: 25});
window.mbQuery(0, `user:create:${data}`, function(response) {
    console.log(response);
});

无参数：

window.mbQuery(0, 'greeter:greet:', function(response) {
    console.log(response);  // "Hallo Cellium"
});

4. 命令格式规范

格式：cell_name:command[:args][:async]
cell_name：组件的 cell_name 属性值（小写字母）
command：组件 get_commands() 中定义的命令名
args：可选参数，支持简单字符串或 JSON 格式
:async：可选后缀，耗时任务自动提交到线程池执行，避免阻塞 UI

5. 异步执行（避免阻塞 UI）

耗时任务使用 :async 后缀自动后台执行，完成后通过 run_js() 推送结果：

// 前端调用，加 :async 后缀
window.mbQuery(0, 'jstest:delay:3:async', null);
// 不等待回调，后端完成后自动推送结果

# 后端组件
class JsTest(BaseCell):
    def _cmd_delay(self, seconds: int = 3):
        time.sleep(seconds)  # 在后台线程执行，不会卡 UI
        self.run_js(f"alert('耗时任务完成')")  # 推送结果到前端
        return None

提示：前端传 null 作为回调，实现"发完就不管"，后端完成后主动推送。

选择 Cellium：用你熟悉的 Python 和 Web 技术，快速构建桌面应用。

MiniBlink 依赖

Cellium 依赖 MiniBlink 作为 WebView 引擎。

下载地址：

官方 GitHub Releases: https://github.com/weolar/miniblink49/releases
每日构建版本: https://gitcode.com/Resource-Bundle-Collection/68b02

放置方法：

从上述地址下载 MiniBlink SDK（或直接下载 mb132_x64.dll）
将 mb132_x64.dll 复制到项目根目录的 dll/ 文件夹中：

python-miniblink/
├── dll/
│   └── mb132_x64.dll    # <-- 将下载的 DLL 放在这里
└── main.py

感谢：感谢 MiniBlink 团队开源如此轻量级、高性能的浏览器引擎，让开发者能够轻松构建桌面应用。

核心理念

Cellium 的设计遵循"核心驱动-模块解耦"的核心哲学，将复杂系统简化为可组合的细胞单元。

核心驱动

微内核作为系统的唯一核心，负责：

命令路由 - 解析并分发前端命令到对应组件
事件调度 - 管理组件间的事件通信
生命周期 - 协调组件的加载、初始化和销毁
资源管理 - 统一管理多进程、线程等系统资源

模块解耦

每个组件单元（Cell）具有以下特性：

独立封装 - 组件包含完整的业务逻辑和状态
接口契约 - 所有组件实现统一的 ICell 接口
透明通信 - 通过事件总线进行跨组件通信
即插即用 - 配置即加载，无须修改核心代码

前端后端分离

flowchart TB
    subgraph Frontend["前端层"]
        H["HTML/CSS"]
        J["JavaScript"]
        MB["window.mbQuery() 调用"]
    end

    Core["Cellium 微内核"]

    subgraph Backend["后端层"]
        Calc["Calculator"]
        Grt["Greeter"]
        Json["JsonTest"]
    end

    Frontend -->|"window.mbQuery()"| Core
    Core --> Backend

架构设计

flowchart TB
    subgraph Presentation["前端交互层"]
        MW["MainWindow"]
        MW -->|"窗口管理"| MW
        MW -->|"事件订阅"| MW
        MW -->|"UI 渲染"| MW
    end

    subgraph Kernel["微内核层"]
        EB["EventBus"]
        BR["Bridge"]
        HD["Handler"]
        DI["DIContainer"]
    end

    subgraph Component["组件层"]
        Calc["Calculator"]
        Grt["Greeter"]
        Json["JsonTest"]
    end

    Presentation -->|"前端交互"| Kernel
    Kernel -->|"事件通信"| Component
    HD <-->|"消息处理"| DI
    BR <-->|"桥接通信"| EB

设计原则

微内核架构 - 核心只负责调度和协调，不包含业务逻辑
组件单元 - 所有功能以独立组件形式存在
统一接口 - 所有组件实现 ICell 接口，遵循相同契约
事件驱动 - 组件间通过事件总线通信，互不直接依赖
依赖注入 - 组件无需手动导入核心服务，自动注入解耦

数据流向

flowchart TD
    A["用户操作"] --> B["JavaScript HTML/CSS"]
    B -->|"window.mbQuery(0, 'cell:command:args')"| C["MiniBlinkBridge 接收回调"]
    C --> D["MessageHandler 命令解析与路由"]

    D --> E{处理方式}
    E -->|"命令模式"| G["直接方法调用"]

    G --> I["返回结果"]
    I -->|"→"| K["JavaScript 更新 UI"]

    subgraph 后端内部
    L["组件A"] -->|event_bus.publish| M["EventBus"]
    M -->|事件通知| N["组件B"]
    M -->|事件通知| O["组件C"]
    end

    N -->|"run_js"| K
    O -->|"run_js"| K

注意：事件系统是后端内部使用的，用于组件间解耦通信。前端无法直接发布事件。前端→后端用 mbQuery()，后端→前端用 run_js()。

目录结构

python-miniblink/
├── app/
│   ├── core/                    # 微内核模块
│   │   ├── __init__.py          # 模块导出
│   │   ├── bus/                 # 事件总线
│   │   │   ├── __init__.py
│   │   │   ├── event_bus.py     # 事件总线实现
│   │   │   ├── events.py        # 事件类型定义
│   │   │   └── event_models.py  # 事件模型定义
│   │   ├── window/              # 窗口管理
│   │   │   ├── __init__.py
│   │   │   └── main_window.py   # 主窗口
│   │   ├── bridge/              # 桥接层
│   │   │   ├── __init__.py
│   │   │   └── miniblink_bridge.py  # MiniBlink 通信桥接
│   │   ├── handler/             # 消息处理
│   │   │   ├── __init__.py
│   │   │   ├── message_handler.py   # 消息处理器（命令路由）
│   │   │   └── title_bar_handler.py # 标题栏处理器
│   │   ├── util/                # 工具模块
│   │   │   ├── __init__.py
│   │   │   ├── logger.py        # 日志管理
│   │   │   ├── mp_manager.py    # 多进程管理器
│   │   │   └── components_loader.py  # 组件加载器
│   │   ├── di/                  # 依赖注入
│   │   │   ├── __init__.py
│   │   │   └── container.py     # DI 容器
│   │   ├── interface/           # 接口定义
│   │   │   ├── __init__.py
│   │   │   ├── icell.py         # ICell 组件接口
│   │   │   └── base_cell.py     # BaseCell 基础组件（推荐）
│   │   └── __init__.py          # 模块导出
│   ├── components/              # 组件单元
│   │   ├── __init__.py
│   │   ├── calculator.py        # 计算器组件
│   │   └── greeter.py           # 问候组件
│   └── __init__.py              # 模块导出
├── docs/                        # 文档教程
│   ├── index.md                 # 文档首页
│   ├── index.en.md              # 文档首页（英文）
│   ├── component-tutorial.md    # 组件开发教程
│   ├── component-tutorial.en.md # 组件开发教程（英文）
│   ├── event-mode-tutorial.md   # 事件模式教程
│   ├── event-mode-tutorial.en.md # 事件模式教程（英文）
│   ├── multiprocessing-tutorial.md   # 多进程教程
│   └── multiprocessing-tutorial.en.md # 多进程教程（英文）
├── html/                        # HTML 资源
│   └── index.html               # 主页面
├── font/                        # 字体文件
├── dll/                         # DLL 文件
│   └── mb132_x64.dll            # MiniBlink 引擎
├── config/                      # 配置文件
│   └── settings.yaml            # 组件配置
├── dist/                        # 构建输出目录
├── main.py                      # 入口文件
├── build.bat                    # 构建脚本
├── requirements.txt             # 依赖配

Cellium

Install / Use

README

Cellium

直接调用方法

1. 后端组件定义

2. 前端调用格式

3. 调用示例

4. 命令格式规范

5. 异步执行（避免阻塞 UI）

MiniBlink 依赖

目录

核心理念

核心驱动

模块解耦

前端后端分离

架构设计

设计原则

数据流向

目录结构