详细技术介绍与功能架构
简墨 (LiteWrite)
艺术级在线文档排版与多模态本地编辑器 | Artistic Online Document Typography & Editor
📖 项目简介 (Introduction)
简墨 (LiteWrite) 是一款专注于排版艺术与数据隐私的离线优先 (Local-First) 文档编辑与格式转换平台。
区别于传统的在线协同编辑器，简墨倡导 100% 纯前端运行与本地数据主权。无需注册账号，不上传任何内容至云端服务器，所有文档草稿、插入的图片和表格均持久化存储在浏览器的本地 IndexedDB 数据库中。同时，简墨具备完整的 Office 格式兼容性、智能编码解析和多格式高保真导出能力，无论是学术撰写、技术文档编写、还是日常办公排版，都能提供轻快、优雅、安全的使用体验。
✨ 核心特性 (Key Features)
1. 📝 四大专业编辑模式
- 富文本排版模式 (Rich Text & Office WYSIWYG):
- 提供标题分级 (H1-H3)、字体颜色、荧光笔高亮、粗体/斜体/下划线/删除线、文字对齐及有序/无序列表。
- 支持快捷插入自定义行列的网格表格。
- 保留格式粘贴：支持从 Microsoft Word 或 Excel 直接复制图文表格粘贴至编辑器，自动保留单元格合并、背景色与边框样式。
- Markdown 实时排版模式 (Markdown with Live Preview):
- 采用轻量高效的实时双栏对照与同步排版。
- 支持标准 Markdown 语法、表格、引用块与代码块。
- 内置代码块语法高亮与一键复制功能。
- 代码高亮模式 (Code Highlighting & Templates):
- 专为程序员与技术写作者设计的代码编辑环境。
- 支持 Python, JavaScript, TypeScript, HTML, CSS, JSON, C++, Java, SQL 等多种语言语法高亮。
- 内置常用代码骨架与算法模板，开箱即用。
- 纯文本模式 (Plain Text):
- 极简无干扰纯文本处理，适合草稿记录、待办整理与格式清洗。
- 底部提供字符数、字数 (Word Count)、总行数的实时精准统计。
2. 📂 强大的文档导入与解析
- Word 文档 (
.docx)：基于 Mammoth 引擎，秒级解析并无损还原 Word 文档中的段落排版、标题层级与图片。 - Excel 表格 (
.xlsx)：基于 SheetJS 引擎，将多工作表数据转换为网页可交互式栅格表格。 - Markdown (
.md) 与纯文本 (.txt)：原生识别排版与元数据。 - 源代码文件 (
.py,.js,.ts,.html,.json,.sql等)：自动识别语言并载入对应代码模板。 - 二进制流感知与多字符编码重解：保留原始文件二进制流，当出现中文或特殊符号乱码时，可在界面中随时切换编码重新解析。
3. 💾 高保真多格式 & 多编码保存导出
- 导出格式支持：
Word (.docx)：保留富文本结构与样式。Excel (.xlsx)：智能识别提取编辑器中的数据表格并导出为标准电子表格。矢量 PDF (.pdf)：基于 jsPDF 与 html2canvas，高保真矢量打印与文档归档。Markdown (.md)：一键将富文本或排版转出为标准 Markdown 文件。源码/纯文本：支持自定义扩展名代码文件导出。
- 多字符编码方案：
UTF-8（现代标准默认）UTF-8 带 BOM（兼容 Windows 老旧软件）GBK / GB2312（中国国家标准，杜绝老旧 Excel/文本乱码）UTF-16 LE/UTF-16 BEISO-8859-1 (Latin-1)
4. 🖼️ 多媒体资源管理器 (Media & Gallery)
- 支持截图直接
Ctrl+V粘贴、本地图片拖拽插入，自动转化为本地 Base64/Blob，无需图床。 - 右侧专用媒体抽屉栏，可直观查看当前文档内引用的所有图片资源。
- 支持单张图片放大预览、原图无损导出下载或从文档中快速清理。
5. 🔒 隐私安全与本地持久化 (100% Privacy & Local-First)
- 零云端上传：所有业务逻辑和文件解析均在浏览器端完成，无网络通信开销，断网也能正常工作。
- IndexedDB 存储引擎：突破 LocalStorage 5MB 容量限制，稳定存储数十兆图文数据。
- 文档生命周期管理：支持历史文档检索、按更新时间排序、创建时间展示、自动防丢保存（带实时保存状态指示）。
6. 🌐 国际化与暗黑主题
- 8 种国际化语言支持：
- 🇨🇳 简体中文 (
zh-CN) - 🇭🇰/🇹🇼 繁体中文 (
zh-TW) - 🇺🇸 英语 (
en) - 🇰🇷 韩语 (
ko) - 🇯🇵 日语 (
ja) - 🇩🇪 德语 (
de) - 🇫🇷 法语 (
fr) - 🇪🇸 西班牙语 (
es)
- 🇨🇳 简体中文 (
- 暗黑/明亮主题切换：支持一键切换舒适的深色护眼模式与清新典雅的纸质明亮模式。
- 法律与合规：内置多语言免责声明 (Disclaimer) 与版权声明 (Copyright)。
🛠️ 技术栈 (Tech Stack)
| 模块 / 功能 | 采用技术 |
|---|---|
| 前端框架 | React 19 + TypeScript |
| 构建工具 | Vite 6 |
| 样式与图标 | Tailwind CSS v4 + Lucide React |
| 动画效果 | Motion (Framer Motion) |
| Office 文档解析 | Mammoth.js (.docx 解析) + SheetJS / xlsx (.xlsx 解析) |
| PDF 导出渲染 | jsPDF + html2canvas |
| 本地数据持久化 | 浏览器原生 IndexedDB API |
📁 目录结构 (Directory Structure)
├── index.html # HTML 页面入口
├── metadata.json # Google AI Studio 应用元数据与能力配置
├── package.json # 项目依赖与运行脚本
├── vite.config.ts # Vite 构建与 TailwindCSS 插件配置
├── tsconfig.json # TypeScript 配置文件
├── sw.js # Service Worker 脚本
├── src/
│ ├── main.tsx # 应用程序入口
│ ├── App.tsx # 主编辑器控制台、文档切换与状态调度
│ ├── index.css # 全局样式与 Tailwind 导入
│ ├── types.ts # 全局 TypeScript 接口定义 (文档模型、编码、代码模板)
│ ├── components/
│ │ ├── DocumentList.tsx # 左侧本地文档历史列表、搜索与新建栏
│ │ ├── Toolbar.tsx # 顶部富文本排版工具栏 (文字样式、色盘、表格插入)
│ │ ├── ExportModal.tsx # 导出设置模态弹窗 (格式选择、编码转换、文件重命名)
│ │ ├── ImageManager.tsx # 右侧多媒体资源管理器 (图片提取、下载与清理)
│ │ ├── LegalModal.tsx # 多语言免责声明与版权信息模态窗
│ │ └── editor-utils.ts # 编辑器 DOM 辅助函数与光标工具
│ └── lib/
│ ├── db.ts # IndexedDB 底层读写封装 (创建、查询、更新、删除)
│ ├── export.ts # 多格式与多编码导出引擎 (Blob 处理、PDF、Excel、Word 转换)
│ ├── markdown.ts # 轻量级 Markdown 解析器与多语言代码高亮器
│ ├── welcomeTemplates.ts # 多语言模式内置新手欢迎文档与测试模板
│ └── i18n.ts # 8 种语言的完整国际化字典与翻译映射
🚀 本地运行与开发指南 (Getting Started)
前置要求 (Prerequisites)
- Node.js (推荐 18.x 或 20.x+)
- npm 或 pnpm / yarn
1. 安装依赖 (Install Dependencies)
npm install
2. 启动本地开发服务 (Start Dev Server)
npm run dev
启动成功后，浏览器访问终端提示的地址（默认为 http://localhost:3000）。
3. 代码检查与构建 (Build & Lint)
# 执行 TypeScript 类型校验
npm run lint
# 生产环境打包构建
npm run build
# 预览生产构建包
npm run preview
🔐 数据安全与使用声明 (Privacy & Disclaimer)
- 纯前端本地存储：简墨所有功能均在本地浏览器环境中运行，不设任何数据收集服务器。
- 数据备份建议：由于数据保存在您当前浏览器的 IndexedDB 中，清除浏览器缓存、重装系统或使用无痕模式可能导致本地草稿遗失。建议对重要文档及时点击**「保存并导出」**到本地硬盘中持久保存。
📄 许可证 (License)
本项目基于 MIT License 开源。欢迎 Star、Fork 或提交 Issue / Pull Request！