# textus

**Repository Path**: qiuzongman/textus

## Basic Information

- **Project Name**: textus
- **Description**: 文本处理程序，使用Lua语法
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 文本处理, 文本转换, Lua语法, 文本工具

## README

# Textus — 文本处理工具

[**📦 立即下载 v1.1.0**](https://gitee.com/qiuzongman/textus/releases/download/1.1.0/Textus_x64_1.1.0.zip)

基于 Rust + [wind-ui-rs](https://github.com/huanfeng/wind-ui-rust) 的 Windows 轻量级文本处理工具。常驻系统托盘，选中文本后一键执行 Lua 脚本处理，结果自动粘贴回源程序。

> 仅支持 **Windows 10/11 x64（64 位）**。极简设计，托盘常驻，90 个内置脚本。

## 功能特性

- 常驻托盘，不干扰日常工作流
- 90 个内置 Lua 脚本：编号、对符、转换、行操作、排版、Markdown
- 脚本参数化：支持文本框、下拉框、复选框等参数控件，含多语言翻译
- 全局热键一键唤起（默认 F8）
- 自动复制 → 执行 → 粘贴的完整流水线
- 可拖分隔条调整标签栏宽度
- 窗口置顶、不透明度可配置（设置窗口）
- 语言切换：托盘右键菜单 → 悬停展开子菜单（中文/English）
- PCRE2 正则支持（`rex` 全局表）
- 零运行时依赖（Lua 5.4 / 图标 / 二维码全部编译期内嵌）

## 快速开始

### 环境要求

- Windows 10/11 x64
- **Rust 工具链**（≥ 1.85，通过 https://rustup.rs 安装）

### 构建

```bat
cd .main
cargo build --release
```

产物路径：`../.bf/release/textus.exe`

### 一键构建与部署

```bat
build.bat
```

自动编译 release 版本并部署到 `../.build/textus.exe`。

## 目录结构

```
.main/
├── Cargo.toml          构建规则（package + 依赖 + release profile）
├── Cargo.lock          依赖版本锁定
├── build.rs            编译期脚本（embed-resource 嵌入 exe 图标）
├── build.bat           一键构建脚本
├── README.md           本文档
├── LICENSE             GNU AGPL-3.0 许可证
├── patches/            对第三方库的补丁记录
├── src/                Rust 源码
├── doc/                文档
│   └── help.html       用户帮助（随 exe 发布到 .build/doc/）
├── image/              图片资源（icon.ico / 二维码 PNG）
├── script/             内置 Lua 脚本（随 exe 发布到 .build/script/）
└── .cargo/config.toml  Cargo 配置（target-dir 重定向到 ../.bf/）
```

### 内置脚本分类

| 分类 | 数量 | 说明 |
|---|---|---|
| `01.编号` | 11 | 数字/字母/中文/符号编号 |
| `02.对符` | 13 | 引号、括号、书名号等对称包裹 |
| `03.转换` | 12 | 大小写、全半角、标点中英、千分位、正则替换 |
| `04.行` | 14 | 前缀/后缀、截取/删除、排序、逆序、断行 |
| `05.排版` | 8 | 空格/空行/重复行清理、混排间隔 |
| `06.Markdown` | 32 | 标题、格式、列表、代码块、表格、提示块等 |

## 技术栈

| 组件 | 版本 | 说明 |
|---|---|---|
| Rust | 2021 edition | 主语言 |
| wind-ui-rs | — | Windows 原生 UI 框架 |
| mlua | 0.10 | Lua 5.4 绑定（vendored 静态链接） |
| pcre2 | 0.2 | PCRE2 正则引擎 |
| arboard | 3.4 | 跨平台剪贴板 |
| windows | 0.62 | Windows API 绑定 |
| embed-resource | 3 | 编译期资源嵌入（图标） |

## 源码架构

```
src/
├── main.rs          应用入口 + UI 构建 + 窗口管理 + 脚本执行编排 + 托盘菜单
├── settings.rs      运行时配置（settings.ini 读写）
├── settings_ui.rs   设置窗口 UI
├── clipboard.rs     剪贴板原子操作（arboard 封装）
├── paste.rs         键盘模拟（Ctrl+C/V）+ 前台窗口焦点管理
├── topmost.rs       窗口置顶状态管理
├── splits.rs        可拖垂直分隔条控件（Widget trait 实现）
├── scanner.rs       脚本目录扫描 + --!param 声明解析
├── lua_runner.rs    Lua 脚本执行引擎（mlua + PCRE2 正则）
├── param_dialog.rs  脚本参数输入对话框
├── icon_asset.rs    ICO 解码 + 窗口/托盘图标源
└── about.rs         关于对话框
```

### 依赖方向

```
main.rs → 所有模块
settings_ui.rs → settings.rs
param_dialog.rs → scanner.rs
about.rs → settings.rs
lua_runner.rs → （无内部依赖）
paste.rs → （无内部依赖）
scanner.rs → （无内部依赖）
```

### 脚本执行流程

```
用户点击脚本按钮
    │
    ├─ 有参数 → 先弹参数对话框 → 用户点确定后 ↓
    ├─ 无参数 → ↓
    │
    ├─ 1. clipboard::read_clipboard()     ← 保存原始剪贴板
    ├─ 2. paste::ensure_external_focus()  ← 焦点还给源程序（失败则提示并中止）
    ├─ 3. paste::simulate_copy()          ← Ctrl+C 复制选中文本
    ├─ 4. clipboard::read_clipboard()     ← 读取选中文本
    ├─ 5. clipboard::write_clipboard()    ← 恢复原始剪贴板
    │
    ├─ 6. lua_runner::execute_lua()
    ├─ 7. clipboard::write_clipboard()    ← 写入脚本结果
    └─ 8. paste::simulate_paste()         ← 自动粘贴（auto_paste 开启时）
```

### 关键设计决策

- **frameless 窗口**：所有窗口自绘标题栏（26px，白底 + 底部框线），风格统一
- **hide_on_close**：关闭按钮只是隐藏窗口，进程常驻托盘，退出只能通过托盘菜单
- **WS_EX_TOOLWINDOW**：不在 Alt+Tab / 任务栏显示，避免干扰用户
- **SW_SHOWNA**：显示窗口但不激活，保留焦点在源程序上
- **DPI 感知**：窗口尺寸用逻辑像素，位置用物理像素，`dpi_scale()` 处转换
- **焦点归还**：每 500ms 轮询记录外部前台窗口，发键前归还焦点
- **Lua 非沙箱**：标准库全量开放，`rex` 全局表封装 PCRE2 正则能力

### 编码约定

- 每个模块顶部 `//!` 模块文档；公共函数 `///` 文档注释
- `Result<T, String>` 统一错误类型；UI 层用 `ctx.toast_err()` 展示
- `unsafe` 必须包裹 Win32 FFI 调用并注释安全性
- 颜色从 `Settings` 读取，不硬编码

### 新增代码规则

1. **纯逻辑**（无 UI / 无 Win32）→ 独立模块，可写单元测试
2. **UI 窗口/控件** → 用 wind-ui-rs 的 `Element` / `Window` API
3. **Win32 API 调用** → 集中封装在对应职责模块
4. **脚本相关** → scanner（扫描）/ lua_runner（执行）分离

## 脚本编写

内置 Lua 脚本的编写规范见 exe 旁的 `doc/help.html`（程序内点击"帮助文档"打开）。

## 许可证

[GNU AGPL-3.0](LICENSE)

第三方组件（wind-ui-rs、mlua、pcre2、arboard、windows 等）的许可证见各 crate 的 `Cargo.toml` 及源码。