# pywebview-word

**Repository Path**: python_90/pywebview-word

## Basic Information

- **Project Name**: pywebview-word
- **Description**: 桌面单词歌词悬浮组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Word Lyric · 桌面单词歌词悬浮组件

> 🖥️ 基于 pywebview + WebView2 的桌面背单词工具  
> 透明悬浮窗 · 无缝滚动 · 系统托盘 · 多词库切换 · 配置持久化

---

## 🚀 快速开始

```bash
# 安装依赖
uv sync

# 运行
uv run python main.py
```

---

## ✨ 功能概览

| 模块 | 说明 |
|------|------|
| 🌐 透明悬浮窗 | 毛玻璃卡片，始终置顶，不遮挡操作 |
| 📜 无缝滚动 | CSS 双份数据 + `translateX(-50%)` 循环，无跳动 |
| 🖱️ 拖拽移动 | JS 计算绝对坐标 → Python API 移动窗口 |
| ⏸️ 悬停暂停 | 鼠标移入卡片暂停滚动 + 放大动画 |
| 📋 系统托盘 | 显示/隐藏/调速/选词本/退出 |
| 🔄 多词库切换 | 托盘右键一键切换，支持 7 套词库 |
| ⚡ 动态调速 | 3~60 秒/词，实时生效 |
| 💾 配置持久化 | 词库/速度/位置自动保存，下次启动恢复 |

---

## 📂 项目结构

```
word/
├── main.py              # 入口：窗口创建 / Win32 配置 / 托盘 / API
├── index.html           # 前端：毛玻璃 UI / 滚动动画 / 拖拽逻辑
├── pyproject.toml       # 依赖管理
├── config.json          # 用户配置（自动生成）
├── readme.md
└── word/                # 词库目录（tab 分隔：单词\t释义）
    ├── 初中-乱序.txt
    ├── 高中-乱序.txt
    ├── 四级-乱序.txt
    ├── 六级-乱序.txt
    ├── 考研-乱序.txt
    ├── 托福-乱序.txt
    └── SAT-乱序.txt
```

---

## 🧱 技术栈

| 层面 | 技术 | 用途 |
|------|------|------|
| 桌面壳 | `pywebview` 6.x | WebView2 窗口容器 |
| 渲染 | `HTML` / `CSS` / `JS` | 毛玻璃 UI + 滚动动画 |
| 窗口控制 | `ctypes` → Win32 API | 无边框 / 置顶 / DWM 玻璃效果 |
| 系统托盘 | `pystray` + `Pillow` | 托盘图标 + 右键菜单 |
| 打包 | `PyInstaller` | 可选，独立 exe 分发 |

---

## ⚙️ 核心实现

### 透明窗口

```python
# 环境变量必须在 WebView2 初始化前设置
os.environ["WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS"] = (
    "--disable-gpu-compositing "
    "--disable-features=msWebView2BrowserHitTransparentWhenOverlapped "
)

# 窗口配置
webview.create_window(frameless=True, transparent=True, on_top=True)
```

- `--disable-gpu-compositing` 关闭 GPU 层合成，等效 Electron 的同名开关
- `DwmExtendFrameIntoClientArea` 扩展玻璃效果至整个客户区
- 加载后 `hide()` → `show()` 强制重绘，修复透明初始化白屏

### 无缝滚动

```css
.word-scroll-inner {
    animation: scroll-left var(--scroll-duration) linear infinite;
}
@keyframes scroll-left {
    0%   { transform: translateX(0); }
    100% { transform: translateX(-50%); }
}
```

- JS 构建双份单词数据（data × 2），滚动到 50% 时恰好回到起点
- `--scroll-duration` = `单词数 × 秒/词`，动态 CSS 变量控制速度

### 拖拽移动

`-webkit-app-region: drag` 在 WebView2 上不生效，改用 JS 手动实现：

```
mousedown → 记录 grabX/Y（鼠标屏幕坐标）+ winStartX/Y（窗口坐标）
mousemove → 新坐标 = winStart + (screen - grab)
         → pywebview.api.move_window(newX, newY)  [Python 端执行 window.move()]
mouseup   → 停止
```

### 配置持久化

```json
// config.json（自动生成，同级目录）
{
  "wordbook": "四级-乱序",
  "speed": 5.0,
  "x": 960,
  "y": 900
}
```

| 触发时机 | 保存字段 |
|----------|----------|
| 拖动窗口 | `x`, `y` |
| 切换单词本 | `wordbook` |
| 调整速度 | `speed` |
| 启动时 | 全部恢复 |

---

## 🖱️ 托盘菜单

```
┌─ 显示 ──────────────────── 双击托盘 / 点击此
├─ 隐藏 ──────────────────── 隐藏悬浮窗
├──────────────────────────
├─ 滚动速度 ─┬─ 3 秒/词
│            ├─ 5 秒/词 (默认)
│            ├─ 6 ~ 60 秒/词
├─ 选择单词本 ─┬─ 初中-乱序
│              ├─ 高中-乱序
│              ├─ 四级-乱序
│              ├─ 六级-乱序
│              ├─ 考研-乱序
│              ├─ 托福-乱序
│              └─ SAT-乱序
├──────────────────────────
└─ 退出 ──────────────────── 彻底关闭
```

---

## 📦 打包为 exe

```bash
uv sync --group build
uv run pyinstaller --onefile --windowed --add-data "index.html;." --add-data "word;word" main.py
```

---

## 🔧 环境要求

| 项 | 版本 |
|----|------|
| Python | ≥ 3.10 |
| Windows | 10 / 11 |
| WebView2 Runtime | 系统自带 |
| 依赖 | pywebview ≥ 5.0, pystray ≥ 0.19, Pillow ≥ 12.0 |