{"id":51038302,"url":"https://github.com/fivefish130/jxls-migration-tool","last_synced_at":"2026-06-22T08:32:28.537Z","repository":{"id":322979532,"uuid":"1091651227","full_name":"fivefish130/jxls-migration-tool","owner":"fivefish130","description":"Production-ready tool for migrating JXLS 1.x to 2.14.0","archived":false,"fork":false,"pushed_at":"2025-11-07T10:59:35.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T12:19:42.438Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fivefish130.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T10:15:12.000Z","updated_at":"2025-11-07T10:59:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fivefish130/jxls-migration-tool","commit_stats":null,"previous_names":["fivefish130/jxls-migration-tool"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fivefish130/jxls-migration-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fjxls-migration-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fjxls-migration-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fjxls-migration-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fjxls-migration-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fivefish130","download_url":"https://codeload.github.com/fivefish130/jxls-migration-tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fjxls-migration-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34641636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-22T08:32:26.533Z","updated_at":"2026-06-22T08:32:28.530Z","avatar_url":"https://github.com/fivefish130.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JXLS Migration Tool\n\n\n[![Version](https://img.shields.io/badge/version-3.4+-blue.svg)](https://github.com/your-org/jxls-migration-tool)\n[![Python](https://img.shields.io/badge/python-3.6+-green.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n\nA powerful, production-ready tool for automated migration from JXLS 1.x to JXLS 2.14.0 Excel templates.\n**中文文档**: [中文版 README](docs/README_ZH.md) | [中文使用指南](docs/USAGE_ZH.md)\n\n\n\n## ✨ Features\n\n- **Complete JXLS Instruction Support**: Migrates all JXLS instructions (forEach, if, out, area, multiSheet)\n- **Smart File Format Detection**: Auto-detects Excel file format regardless of extension\n- **Format Preservation**: Maintains all cell styles, column widths, row heights, merged cells\n- **XlsxWriter Integration**: Uses xlsxwriter for both .xls and .xlsx files with automatic shared strings table (避免富文本问题，POI 兼容性更好)\n- **Windows Terminal Optimized**: Auto-detects and configures UTF-8 support\n- **Detailed Reporting**: Generates Markdown, JSON, and DEBUG logs\n- **Production Ready**: Comprehensive error handling and logging\n\n## 📦 Installation\n\n### Requirements\n- Python 3.6+\n- xlrd 2.0.1\n- openpyxl\n- xlsxwriter (required for writing Excel files)\n\n### Quick Install\n```bash\npip install xlrd==2.0.1 openpyxl xlsxwriter\n```\n\n**Note**: xlsxwriter is required for writing Excel files with automatic shared strings table support (better POI 5.4.0+ compatibility).\n\n## 🚀 Quick Start\n\n### Migrate a directory\n```bash\n# Keep original file extensions but convert to .xlsx format\n# .xls files will have .xls extension but .xlsx content (Jxls 2.14.0 compatible)\n# .xlsx files will remain .xlsx extension\npython jxls_migration_tool.py input_directory --keep-extension\n\n# Specify output directory\npython jxls_migration_tool.py input_directory -o output_directory --keep-extension\n\n# Dry run (preview changes without modifying files)\npython jxls_migration_tool.py input_directory --dry-run --verbose\n```\n\n**Note**: `--keep-extension` preserves the original file extension but ensures all files have .xlsx content for Jxls 2.14.0 compatibility. This avoids the need to modify backend code.\n\n### Migrate a single file\n```bash\npython jxls_migration_tool.py input.xls -f output.xlsx\n```\n\n## 📋 JXLS Instruction Conversion\n\n| JXLS 1.x | JXLS 2.14.0 | Description |\n|----------|-------------|-------------|\n| `\u003cjx:forEach items=\"...\" var=\"...\"\u003e` | `jx:each(items=\"...\" var=\"...\" lastCell=\"...\")` | Comment-based, auto-removes tag rows |\n| `\u003cjx:if test=\"...\"\u003e` | `jx:if(condition=\"...\" lastCell=\"...\")` | test → condition, comment-based |\n| `\u003cjx:out select=\"...\"/\u003e` | `${...}` | Direct expression replacement |\n| `\u003cjx:area lastCell=\"...\"\u003e` | `jx:area(lastCell=\"...\")` | Preserve existing or auto-generate |\n| `\u003cjx:multiSheet data=\"...\"\u003e` | `jx:multiSheet(data=\"...\")` | Full multi-sheet support |\n\n## 📊 Real-World Results\n\n**Migration Statistics (923 Excel files)**:\n- ✅ Successfully migrated: 50 JXLS templates\n- ⏭️  Skipped: 873 files (no JXLS instructions)\n- ❌ Failed: 0 files\n- 🎯 Success rate: **100%**\n\n**Module Distribution**:\n- Module A: 7 templates\n- Module B: 1 template\n- Module C: 42 templates\n\n**Command Statistics**:\n- Total JXLS commands found: 106\n- Successfully converted: 106\n- Main types: forEach (50), area (50), if (6)\n\n## 📖 Documentation\n\n- **[Usage Guide](docs/USAGE.md)** - Detailed usage instructions\n- **[使用指南](docs/USAGE_ZH.md)** - 中文版详细使用说明\n- **[API Documentation](docs/API.md)** - Programmatic API reference\n- **[Examples](examples/)** - Code examples and use cases\n- **[Changelog](docs/CHANGELOG.md)** - Version history and changes\n```\nusage: jxls_migration_tool.py [-h] [-o OUTPUT] [-f] [--keep-extension]\n                              [--dry-run] [-v] [--verbose]\n                              input_path\n\nJXLS 1.x → 2.14.0 Migration Tool\n\npositional arguments:\n  input_path              Input file or directory path\n\noptional arguments:\n  -h, --help              show this help message and exit\n  -o OUTPUT, --output OUTPUT\n                          Output directory (default: same as input)\n  -f OUTPUT_FILE, --file OUTPUT_FILE\n                          Output file (for single file migration)\n  --keep-extension        Keep original file extensions\n  --dry-run               Preview changes without modifying files\n  -v, --verbose           Enable verbose logging\n```\n\n## 🎯 Migration Example\n\n### Before (JXLS 1.x)\n```\nRow 1: \u003cjx:area lastCell=\"E5\"\u003e\nRow 2: Purchase Order List\nRow 3: \u003cjx:forEach items=\"datas\" var=\"item\"\u003e\nRow 4: ${item.sku} | ${item.qty} | ${item.price}\nRow 5: \u003c/jx:forEach\u003e\nRow 6: Total: ${total}\n```\n\n### After (JXLS 2.x)\n```\nRow 1: (blank)\n       └─ [Comment] jx:area(lastCell=\"E4\")\nRow 2: Purchase Order List\nRow 3: ${item.sku} | ${item.qty} | ${item.price}\n       └─ [Comment] jx:each(items=\"datas\" var=\"item\" lastCell=\"C3\")\nRow 4: Total: ${total}\n```\n\n**Key Changes**:\n- ✅ Deleted tag rows (3rd and 5th)\n- ✅ Added jx:area comment at row 1\n- ✅ Added jx:each comment at row 3\n- ✅ Auto-calculated lastCell=\"C3\" (column C, row 3)\n\n## 🔧 Smart File Format Detection\n\nThe tool auto-detects the actual Excel file format by reading file headers, not relying on extensions:\n\n| File Header | Format | Description |\n|------------|--------|-------------|\n| `D0 CF 11 E0 A1 B1 1A E1` | XLS | OLE2/Compound Document |\n| `PK` (50 4B) | XLSX | ZIP format |\n\nThis allows:\n- `.xls` files that are actually `.xlsx` format to be handled correctly\n- `.xlsx` files that are actually `.xls` format to be handled correctly\n- Automatic selection of the correct processor (xlrd vs openpyxl)\n\n## 💡 Windows Terminal Optimization\n\nAutomatically detects and optimizes for Windows Terminal:\n\n```python\n# Auto-detects these environment variables\nWT_SESSION, WT_PROFILE_ID\n\n# Windows Terminal: Uses native UTF-8 (no configuration needed)\n# Traditional cmd/PowerShell: Auto-sets chcp 65001\n```\n\n## 📄 Output Reports\n\nAfter migration, three types of reports are generated:\n\n1. **migration_report.md** - Human-readable Markdown report\n   - Statistics (success/fail/success rate)\n   - List of successful files\n   - List of failed files (with error details)\n   - Summary of main changes\n\n2. **migration_report.json** - Machine-readable JSON report\n   - Timestamps and complete statistics\n   - Detailed change records for each file\n   - Failure reasons and details\n\n3. **jxls_migration.log** - Complete DEBUG log in UTF-8 encoding\n\n## ⚠️ Known Limitations\n\n1. **varStatus** - JXLS 2.x no longer supports varStatus (must be implemented manually in Java code)\n2. **Encrypted files** - Cannot process password-protected Excel files\n3. **Corrupted files** - Cannot process damaged Excel files\n4. **Special formats** - Very rare special formats may require manual adjustment\n\n## 🆘 Troubleshooting\n\n### Q: Missing xlrd library error\n```bash\npip install xlrd openpyxl xlsxwriter\n```\n\n### Q: Missing xlsxwriter library error\n```bash\npip install xlsxwriter\n```\n**Note**: xlsxwriter is required for all migrations. It provides automatic shared strings table support and avoids rich text format issues.\n\n### Q: Rich text format issues / POI compatibility problems\n**Solution**: The tool now uses xlsxwriter for both .xls and .xlsx files (v3.4+), which automatically uses shared strings table to avoid rich text format issues.\n\n**Technical Details**:\n- **Before v3.4**: .xlsx files used openpyxl which could retain rich text formatting\n- **After v3.4**: All files (.xls and .xlsx) use xlsxwriter with automatic shared strings table\n- **Benefits**: Better Apache POI 5.4.0+ compatibility, no rich text issues\n\nIf you still encounter rich text issues:\n1. Verify you're using xlsxwriter: Check logs for \"使用 XlsxWriter 写入文件\"\n2. Update xlsxwriter: `pip install --upgrade xlsxwriter`\n3. Re-run migration with `--verbose` flag to see detailed processing logs\n\n### Q: File has .xls extension but is actually .xlsx format\nThis is normal! The tool auto-detects and handles this. Use `--keep-extension` to preserve original extension.\n\n### Q: Incorrect lastCell parameter\nManually open the .xlsx file, right-click the comment, and modify the lastCell parameter (usually the last column and last row of the table).\n\n### Q: Some templates failed to migrate\nCheck the log file for specific errors. Common causes:\n- File corruption\n- Password protection\n- Special JXLS instructions\n- Complex nested structures\n\n### Q: How to handle encrypted Excel files\nThe tool cannot process encrypted files. Decrypt them first.\n\n### Q: Windows Terminal not detected\nCheck for environment variables `WT_SESSION` or `WT_PROFILE_ID`.\n\n## 📝 Migration Best Practices\n\n1. **Backup original files** - Use `_backup` suffix for backup directory\n2. **Run dry-run first** - Use `--dry-run` to preview changes\n3. **Test key templates** - Verify business functions after migration\n4. **Review reports** - Check migration_report.md for details\n5. **Validate exports** - Ensure all export functions work correctly\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Setup\n```bash\n# Clone the repository\ngit clone https://github.com/your-org/jxls-migration-tool.git\ncd jxls-migration-tool\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run tests\npython -m pytest tests/\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 👨‍💻 Author\n\n**fivefish**\n- Version: 3.4+ (富文本问题修复版)\n- Date: 2025-11-12\n\n## 🙏 Acknowledgments\n\n- [JXLS Project](https://jxls.sourceforge.net/) - The excellent Java library for Excel templating\n- [xlrd](https://github.com/python-excel/xlrd) - Python library for reading .xls files\n- [openpyxl](https://openpyxl.readthedocs.io/) - Python library for reading/writing .xlsx files\n\n## 📚 Related Projects\n\n- [JXLS Official Documentation](https://jxls.sourceforge.net/)\n- [POI Project](https://poi.apache.org/) - Apache POI - Java API for Microsoft Documents\n\n---\n\n**Happy Migrating! 🎉**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivefish130%2Fjxls-migration-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffivefish130%2Fjxls-migration-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivefish130%2Fjxls-migration-tool/lists"}