200 lines
9.1 KiB
Markdown
200 lines
9.1 KiB
Markdown
# 闲言 WordsLeisure
|
||
|
||
<p align="center">
|
||
<strong>文字阅读更纯粹</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
句子阅读 · 壁纸制作 · 图文创作 · 全平台
|
||
</p>
|
||
|
||
---
|
||
|
||
## 关键字
|
||
|
||
`Flutter` `iOS 26 Liquid Glass` `专业编辑器` `3D贴纸` `液态玻璃` `SVG动画` `全平台7端` `鸿蒙` `Frosted Glass` `Riverpod` `Drift` `freezed` `go_router` `pro_image_editor`
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
闲言是一款以句子阅读和图文创作为核心的跨平台应用，源自一个 Lua 原生项目（65 文件 15000+ 行），经过全面 Flutter 重写，采用 iOS 26 Liquid Glass 设计语言，覆盖 Android、iOS、macOS、Windows、Linux、Web 和鸿蒙 7 大平台。核心编辑器模块基于 pro_image_editor 深度定制，集成 8 个子编辑器、7 类贴纸系统、3D 模型交互和完整导出链路，是一个功能完备的图文创作工具。
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
### 专业图文编辑器
|
||
|
||
内置 8 个子编辑器：画笔、文字、裁剪旋转、色调调整、滤镜、模糊、Emoji、贴纸。支持 5 种画布比例切换（9:16/3:4/1:1/4:3/16:9）、三等分/点阵网格参考线、智能对齐吸附、取色器（实时预览+放大镜+HEX）、多节点渐变编辑器、操作历史树形面板。编辑器采用 Frosted Glass 毛玻璃主题，所有 UI 组件统一圆角阴影风格。
|
||
|
||
### 七类贴纸系统
|
||
|
||
液态玻璃贴纸（8 种预设，liquid_glass_widgets Shader 渲染）、轻量玻璃贴纸（4 种预设，liquid_glass_easy 透镜特效）、SVG 矢量贴纸（8 种本地 SVG）、Lottie 动画贴纸（6 种本地动画）、网络贴纸（6 类 36 张在线资源）、形状贴纸（4 种基础几何）、3D 模型贴纸（几何体/装饰/自然 3 分类 10+ 模型，flutter_3d_controller WebView 实时渲染）。所有贴纸均可拖拽、缩放、旋转，导出时通过 RepaintBoundary 预渲染合成。
|
||
|
||
### 3D 内容引擎
|
||
|
||
统一使用 flutter_3d_controller（WebView + model-viewer）作为唯一 3D 渲染路径。支持 .glb 模型在线 CDN 加载，独立 3D 预览页面支持动画播放控制、自动旋转、相机重置。低端设备自动检测（Android API<28 / iOS<15）并展示降级提示。3D 贴纸导出采用静态快照方案解决 WebView 无法 RepaintBoundary 截图的限制。
|
||
|
||
### 完整导出链路
|
||
|
||
高分辨率 PNG 保存到相册（gal）、系统分享（share_plus）、.xycard 源文件格式（ZIP 压缩/解压，可再编辑）、JPEG/WebP 压缩导出（flutter_image_compress，体积减少 70%+）、GIF 逐帧导出、草稿自动保存与恢复、导出格式选择+质量滑块。
|
||
|
||
### 图片处理增强
|
||
|
||
图片尺寸/格式检测（image_size_getter，读文件头零解码）、EXIF 旋转自动校正、全屏大图预览（photo_view，缩放+旋转+双击循环+Hero 动画）、多图画廊（PhotoViewGallery）、裁剪编辑器（extended_image，自由/1:1/4:3/16:9 + 旋转翻转 + undo/redo）、大图内存优化（ExtendedResizeImage 降采样）。
|
||
|
||
### iOS 26 Liquid Glass 设计语言
|
||
|
||
全套设计令牌系统（颜色/间距/圆角/阴影/字体/毛玻璃），6 套主题配置，日夜双主题自动切换，自适应主题色（从图片提取调色板），Cupertino 优先的组件风格。底部面板采用 stupid_simple_sheet 弹簧动画，页面转场使用 heroine 弹簧物理效果替代 Hero。
|
||
|
||
---
|
||
|
||
## 架构设计
|
||
|
||
```
|
||
lib/
|
||
├── main.dart # 入口 + 设备能力检测初始化
|
||
├── app/ # MaterialApp.router + GlassTheme + Riverpod
|
||
├── core/ # 基础设施层 (35 文件)
|
||
│ ├── router/ # go_router + ShellRoute 声明式路由
|
||
│ ├── layout/ # AppShell + GlassBottomBar 统一布局
|
||
│ ├── theme/ # 6 套设计令牌 (颜色/圆角/阴影/间距/排版/Glass)
|
||
│ ├── network/ # Dio + Interceptor + ApiException
|
||
│ ├── storage/ # KvStorage + SecureStorage + Drift 4 表
|
||
│ └── utils/ # 动画/日志/平台检测/权限/扩展
|
||
├── editor/ # 编辑器核心模块 (82 文件)
|
||
│ ├── models/ # freezed 数据模型 + LayerInfo sealed class
|
||
│ ├── providers/ # Riverpod StateNotifier
|
||
│ ├── mixins/ # 编辑器行为混入 (7 个)
|
||
│ ├── services/core/ # ProEditorBridge + StickerConfigBuilder + WidgetLayerFactory
|
||
│ ├── services/export/ # ExportService + XycardService + DraftService + ImageCompressService
|
||
│ ├── services/image/ # ImageImportService + ImageInfoService + GlassRenderService
|
||
│ ├── services/3d/ # Platform3DService + Flutter3DControllerFactory
|
||
│ ├── pages/ # ProEditorPage + MiniEditor(3模式) + 工具页(裁剪/预览/3D)
|
||
│ └── widgets/ # 图层面板/颜色选择器/取色器/渐变编辑器/3D面板/水印面板等
|
||
├── features/ # 功能模块 (7 个，Feature-first 架构)
|
||
│ ├── home/ # 首页句子卡片流 + Hitokoto API (12 类型)
|
||
│ ├── inspiration/ # 灵感/工具中心
|
||
│ ├── search/ # 搜索
|
||
│ ├── profile/ # 个人中心
|
||
│ ├── member/ # 会员
|
||
│ ├── source/ # 来源
|
||
│ └── settings/ # 主题个性化设置
|
||
└── shared/ # 共享组件
|
||
└── widgets/ # GlassContainer/Skeleton/EmptyState/BottomSheet
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 框架 | Flutter 3.24+ / Dart 3.9+ |
|
||
| 状态管理 | Riverpod 2.5+ (StateNotifier + 依赖注入) |
|
||
| 路由 | go_router 14.0+ (ShellRoute + 深链接) |
|
||
| 数据库 | Drift 2.16+ (SQLite 类型安全 + 响应式查询) |
|
||
| 数据模型 | freezed 2.5+ (不可变 + JSON 序列化) |
|
||
| 网络 | Dio 5.4+ (拦截器 + 请求取消) |
|
||
| 后端 | Supabase (Auth + Database + Storage) |
|
||
| 设计语言 | iOS 26 Liquid Glass (Cupertino 优先) |
|
||
|
||
---
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 状态 | 说明 |
|
||
|------|:----:|------|
|
||
| Android | ✅ | 完整支持 |
|
||
| iOS | ✅ | 完整支持 |
|
||
| macOS | ✅ | 完整支持 |
|
||
| Windows | ✅ | 完整支持 (3D 仅静态) |
|
||
| Linux | ✅ | 完整支持 (3D 仅静态) |
|
||
| Web | ✅ | 完整支持 (压缩有限制) |
|
||
| 鸿蒙 (OpenHarmony) | ✅ | 适配中 |
|
||
|
||
---
|
||
|
||
## 核心依赖
|
||
|
||
| 库 | 用途 |
|
||
|----|------|
|
||
| pro_image_editor | 专业图片编辑引擎 (Frosted Glass 主题定制) |
|
||
| liquid_glass_widgets / liquid_glass_easy | iOS 26 液态玻璃组件 + 透镜特效 |
|
||
| flutter_3d_controller | 3D 模型交互预览 (WebView + model-viewer) |
|
||
| flutter_svg / lottie | SVG 渲染 / Lottie 矢量动画 |
|
||
| google_fonts | 15 种字体 (中 6 + 英 9) |
|
||
| photo_view / extended_image | 图片缩放查看 / 裁剪编辑 + 内存优化 |
|
||
| flutter_image_compress | 原生图片压缩 (JPEG/WebP/PNG/HEIC) |
|
||
| image_size_getter | 图片尺寸/格式检测 (零解码) |
|
||
| adaptive_palette | 自适应主题色提取 + 流体背景 |
|
||
| heroine / stupid_simple_sheet | 弹簧 Hero 动画 / iOS 26 Glass Sheet |
|
||
|
||
---
|
||
|
||
## 项目规模
|
||
|
||
- **147 个 Dart 文件** (核心代码 lib/)
|
||
- **16 个页面** (编辑器 8 页 + 功能 8 页)
|
||
- **8 个设计令牌文件** (颜色/圆角/阴影/间距/排版/Glass/主题)
|
||
- **27 个编辑器服务** (core 9 + export 8 + image 8 + 3d 5)
|
||
- **7 个功能模块** (Feature-first 架构)
|
||
|
||
---
|
||
|
||
## 开发进度
|
||
|
||
> 当前版本: v0.23.0
|
||
|
||
| Phase | 内容 | 状态 |
|
||
|-------|------|:----:|
|
||
| Phase 0 | 基础设施搭建 | ✅ |
|
||
| Phase 1 | 编辑器核心 + 首页句子流 | ✅ |
|
||
| 编辑器: 图层管理 | LayerPanel + UndoRedo + 图层 CRUD | ✅ |
|
||
| 编辑器: 3D 引擎 | 3D 贴纸 + 3D 预览 + 平台调度 | ✅ |
|
||
| 编辑器: 图片处理 | 压缩 + 预览 + 裁剪 + 信息读取 | ✅ |
|
||
| 编辑器: 3D 修复 | 统一渲染 + 图层模型统一 + bridge 拆分 | ✅ |
|
||
| Phase 2 | 内容发现 + 搜索 + 灵感 | 🔲 |
|
||
| Phase 3 | 壁纸 + 会员 + 通知 | 🔲 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone <repo-url>
|
||
cd xianyan
|
||
|
||
# 安装依赖
|
||
flutter pub get
|
||
|
||
# 生成代码 (freezed / drift / json_serializable)
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 运行
|
||
flutter run
|
||
```
|
||
|
||
---
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
|
||
| [AGENTS.md](AGENTS.md) | AI 开发指引 |
|
||
| [docs/01_项目总览.md](docs/01_项目总览.md) | 项目概述 + 架构 + 开发阶段 |
|
||
| [docs/07_三方库清单.md](docs/07_三方库清单.md) | 全部三方库选型与版本 |
|
||
| [docs/08_编辑器功能清单.md](docs/08_编辑器功能清单.md) | 编辑器架构 + 功能 + 路线图 |
|
||
| [docs/09_三方库扩展功能开发文档.md](docs/09_三方库扩展功能开发文档.md) | 7 库接口分析 + 扩展功能 |
|
||
| [docs/10_三方库扩展开发计划勾选表.md](docs/10_三方库扩展开发计划勾选表.md) | 按 Phase 细分开发任务 |
|
||
| [docs/11_编辑器空壳功能诊断与修复计划.md](docs/11_编辑器空壳功能诊断与修复计划.md) | 3D 空壳功能诊断 + 修复记录 |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Private — 仅供学习参考
|