# kk-toolbox **Repository Path**: yifengliu/kk-toolbox ## Basic Information - **Project Name**: kk-toolbox - **Description**: KK开发的高级工具箱 - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-09-25 - **Last Updated**: 2025-09-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # KK-Toolbox 一个功能强大的桌面文档搜索工具，基于Java Swing开发，专门用于在指定文件夹中搜索包含特定文本内容的PDF和Word文档。 ## 🚀 功能特性 ### 核心功能 - **📁 多格式支持**: 支持PDF (.pdf)、Word (.doc/.docx) 文档搜索 - **🔍 智能搜索**: 全文本内容搜索，不区分大小写 - **📂 递归搜索**: 自动搜索指定文件夹及其所有子文件夹 - **⚡ 异步处理**: 后台线程执行搜索，界面响应流畅 - **📊 实时进度**: 显示搜索进度条和详细状态信息 ### 界面特性 - **🎨 现代化UI**: 基于Java Swing的直观图形界面 - **📋 结果展示**: 表格形式显示匹配文件的详细信息 - **🔍 文件详情**: 双击查看文件详细信息和操作选项 - **🔄 模块化设计**: 独立的PDF搜索、Word搜索和综合搜索模块 - **🏠 主菜单导航**: 清晰的功能模块选择界面 ### 技术特性 - **🌐 跨平台**: 支持Windows、macOS、Linux等操作系统 - **📦 独立运行**: 可打包为单一JAR文件，无需额外安装 - **🛡️ 异常处理**: 优雅处理损坏或加密的文档文件 - **💾 内存优化**: 自动资源管理，避免内存泄漏 - **📝 详细日志**: 完整的日志记录和错误追踪 ## 📋 系统要求 - **Java**: JDK 8 或更高版本 - **操作系统**: Windows 7+, macOS 10.10+, Linux (任何支持Java的发行版) - **内存**: 建议512MB以上可用内存 - **磁盘空间**: 约50MB (包含所有依赖) ## 🚀 快速开始 ### 方式一：直接运行 (推荐) 1. 确保系统已安装Java 8+ 2. 下载预编译的JAR文件：`kk-toolbox-1.0.0.jar` 3. 双击运行或使用命令： ```bash java -jar kk-toolbox-1.0.0.jar ``` ### 方式二：从源码构建 ```bash # 克隆项目 git clone cd kk-toolbox # 编译并打包 mvn clean package # 运行程序 java -jar target/kk-toolbox-1.0.0.jar ``` ### 方式三：Windows EXE (仅Windows) ```bash # 使用提供的脚本构建Windows可执行文件 ./build_windows_exe.sh # 运行生成的EXE文件 ./target/黄PP的工具小黑匣.exe ``` ## 📖 使用指南 ### 主界面操作 1. **启动应用**: 运行程序后显示主菜单界面 2. **选择功能**: 点击相应按钮选择搜索模块： - **PDF搜索**: 专门搜索PDF文档 - **Word搜索**: 专门搜索Word文档 - **综合搜索**: 同时搜索PDF和Word文档 (开发中) ### 搜索操作流程 1. **选择文件夹**: 点击"选择文件夹"按钮选择要搜索的目录 2. **输入关键词**: 在搜索文本框中输入要查找的关键词 3. **开始搜索**: 点击"开始搜索"按钮启动搜索过程 4. **查看进度**: 观察进度条和状态信息了解搜索进展 5. **查看结果**: 搜索完成后在表格中查看匹配的文件 6. **文件详情**: 双击任意结果行查看文件详细信息 ### 界面说明 #### 主菜单界面 - **标题区域**: 显示应用程序名称和描述 - **功能按钮**: 三个主要功能模块的入口按钮 - **版本信息**: 底部显示版本号和开发者信息 #### 搜索界面 - **导航区域**: 返回主菜单按钮和文件夹选择 - **搜索控制**: 搜索文本输入框和搜索按钮 - **结果显示**: 表格形式显示搜索结果，包含： - 文件名 - 完整路径 - 文件大小 - **状态栏**: 显示搜索进度条和当前状态信息 ## 🏗️ 项目架构 ### 目录结构 ``` src/main/java/com/kktoolbox/ ├── MainMenuFrame.java # 主菜单界面 ├── engine/ # 搜索引擎核心 │ ├── PDFSearchEngine.java # PDF文档搜索引擎 │ ├── WordSearchEngine.java # Word文档搜索引擎 │ └── CombinedSearchEngine.java # 综合搜索引擎 ├── entity/ # 数据实体类 │ └── PDFSearchResult.java # 搜索结果数据类 ├── model/ # 模型和接口 │ ├── SearchProgressCallback.java # 搜索进度回调接口 │ └── FileDetailsDialog.java # 文件详情对话框 └── ui/ # 用户界面 ├── pdf/ │ └── PDFSearchFrame.java # PDF搜索界面 └── word/ └── WordSearchFrame.java # Word搜索界面 ``` ### 核心组件 #### 1. 主菜单系统 (MainMenuFrame) - 应用程序入口和导航中心 - 提供功能模块选择界面 - 统一的异常处理和日志记录 #### 2. 搜索引擎 (Engine Package) - **PDFSearchEngine**: 专门处理PDF文档的文本提取和搜索 - **WordSearchEngine**: 处理Word文档(.doc/.docx)的文本提取和搜索 - **CombinedSearchEngine**: 整合PDF和Word搜索功能 #### 3. 用户界面 (UI Package) - **PDFSearchFrame**: PDF搜索专用界面 - **WordSearchFrame**: Word搜索专用界面 - 模块化设计，每个功能独立界面 #### 4. 数据模型 (Entity & Model) - **PDFSearchResult**: 搜索结果数据封装 - **SearchProgressCallback**: 搜索进度回调接口 - **FileDetailsDialog**: 文件详情显示对话框 ### 设计模式 - **MVC模式**: 界面、业务逻辑和数据分离 - **观察者模式**: 通过回调接口实现搜索进度通知 - **工厂模式**: 搜索引擎的创建和管理 - **单例模式**: 日志记录器和配置管理 ## 🔧 技术栈 ### 核心依赖 - **Apache PDFBox 2.0.29**: PDF文档处理和文本提取 - **Apache POI 5.2.5**: Word文档处理和文本提取 - poi: 核心API - poi-ooxml: .docx格式支持 - poi-scratchpad: .doc格式支持 - **SLF4J 1.7.36 + Logback**: 日志框架 - **Lombok 1.18.30**: 减少样板代码 - **Java Swing**: GUI界面框架 ### 构建工具 - **Maven 3.6+**: 项目构建和依赖管理 - **Maven Shade Plugin**: 创建包含所有依赖的Fat JAR - **Launch4j**: Windows EXE文件生成 ## 🛠️ 开发指南 ### 环境准备 ```bash # 必需环境 - JDK 8+ - Maven 3.6+ - IDE (推荐IntelliJ IDEA或Eclipse) # 可选工具 - Launch4j (用于生成Windows EXE) - Git (版本控制) ``` ### 开发命令 ```bash # 编译项目 mvn compile # 运行测试 mvn test # 打包JAR文件 mvn package # 清理构建文件 mvn clean # 完整构建流程 mvn clean package # 跳过测试打包 mvn clean package -DskipTests ``` ### 代码规范 - **编码**: 统一使用UTF-8编码 - **命名**: 遵循Java标准命名规范 - **注释**: 使用Javadoc格式的详细注释 - **异常**: 完善的异常处理和日志记录 - **格式**: 统一的代码格式和缩进 ### 日志配置 项目使用SLF4J + Logback进行日志管理，配置文件位于： ``` src/main/resources/logback.xml ``` ## ⚡ 性能优化 ### 内存管理 - 及时关闭PDF/Word文档资源 - 使用try-with-resources确保资源释放 - JVM垃圾回收优化 ### 线程安全 - 搜索操作在后台线程执行 - UI更新通过EDT (Event Dispatch Thread) 进行 - 避免界面阻塞和假死 ### 错误处理 - 优雅处理损坏或加密的文档 - 跳过无法读取的文件并记录日志 - 用户友好的错误提示信息 ### 搜索优化 - 实时进度反馈 - 可中断的搜索过程 - 智能文件类型检测 ## ❓ 常见问题 ### Q: 程序无法启动？ **A**: 请检查以下几点： - 确保已安装Java 8或更高版本 - 检查JAVA_HOME环境变量设置 - 确认JAR文件完整且未损坏 - 查看控制台错误信息 ### Q: 搜索速度很慢？ **A**: 搜索速度受以下因素影响： - 文件夹大小和文件数量 - 文档文件的大小和复杂度 - 系统硬件性能（CPU、内存、磁盘） - 建议对大型文件夹进行分批搜索 ### Q: 某些文档搜索不到内容？ **A**: 可能的原因： - 文档已加密或损坏 - 扫描版PDF（纯图片格式） - Word文档包含特殊格式或嵌入对象 - 当前版本不支持OCR文字识别 ### Q: 如何生成Windows EXE文件？ **A**: 使用以下方法： ```bash # 方法1: 使用项目提供的脚本 ./build_windows_exe.sh # 方法2: 手动使用Launch4j # 1. 先打包JAR: mvn clean package # 2. 使用Launch4j配置文件: launch4j-config.xml # 3. 生成EXE文件 ``` ### Q: 支持哪些文档格式？ **A**: 当前支持的格式： - **PDF**: .pdf (使用PDFBox提取文本) - **Word**: .doc (Word 97-2003) 和 .docx (Word 2007+) - **注意**: 不支持加密文档和纯图片扫描文档 ## 🔄 版本历史 ### v1.0.0 (当前版本) - ✅ 完整的PDF和Word文档搜索功能 - ✅ 现代化的图形用户界面 - ✅ 模块化架构设计 - ✅ 详细的代码注释和文档 - ✅ Windows EXE打包支持 - ✅ 完善的异常处理和日志记录 ### 未来计划 - 🔄 综合搜索模块完善 - 📊 搜索结果导出功能 - 🎨 界面主题和样式定制 - 🔍 高级搜索选项（正则表达式、文件类型过滤） - 📱 更多文档格式支持 ## 📄 许可证 本项目采用 **MIT许可证**，详见 [LICENSE](LICENSE) 文件。 ## 🤝 贡献指南 欢迎提交Issue和Pull Request来改进这个项目！ ### 贡献流程 1. **Fork** 本项目到你的GitHub账户 2. **创建特性分支**: `git checkout -b feature/AmazingFeature` 3. **提交更改**: `git commit -m 'Add some AmazingFeature'` 4. **推送分支**: `git push origin feature/AmazingFeature` 5. **创建Pull Request**: 在GitHub上创建PR ### 贡献指导 - 遵循现有的代码风格和规范 - 添加适当的测试用例 - 更新相关文档 - 确保所有测试通过 ## 📞 支持与反馈 - **问题报告**: [GitHub Issues](https://github.com/your-repo/kk-toolbox/issues) - **功能建议**: [GitHub Discussions](https://github.com/your-repo/kk-toolbox/discussions) - **开发者**: KK-Toolbox Team --- **感谢使用 KK-Toolbox！** 🎉 如果这个项目对你有帮助，请考虑给我们一个 ⭐ Star！