更新记录

0.1.5（2025-10-05） 下载此版本

更新日志

HBuilderX Prettier 格式化插件的所有重要更改。

[0.1.5] - 2024-10-05

Format and Save 版本

✨ 新增功能

• 整个项目格式化: 支持项目目录右键整体格式化功能
• 智能过滤: 自动跳过 node_modules、dist、.min.js 等不需要格式化的文件

平台兼容性

HBuilderX插件通用注意事项

HBuilderX-2.7.12以下版本安装插件市场内的插件后，卸载时需手动卸载，详细教程参考：如何手动卸载插件

Format and Save

一个功能强大的 HBuilderX 插件，提供代码格式化、智能分栏、注释增强等多种开发效率工具。

💝 感谢原作者：本插件基于 zqy233/formatAndSave 进行开发和优化，感谢原作者的贡献！

✨ 主要功能

🎨 代码格式化

Prettier 智能格式化

• 配置优先级：优先使用项目根目录的 .prettierrc.js 配置文件，如果不存在则使用插件默认配置
• 自动配置创建：首次格式化时自动在项目根目录创建 .prettierrc.js 和 .prettierignore 文件
• 多语言支持：支持 JavaScript、TypeScript、Vue、HTML、CSS、JSON、Markdown 等多种文件格式
• 实时格式化：按 Ctrl+S 保存时自动格式化当前文件，无需额外操作
• 智能错误处理：对不支持的文件类型给出友好提示，不会中断工作流程

项目批量格式化

• 一键格式化：右键项目目录选择"格式化整个项目"，批量处理所有支持的文件
• 智能过滤：自动跳过 node_modules、dist、.min.js 等不需要格式化的文件
• 进度反馈：格式化过程中显示处理进度和结果统计
• 安全机制：格式化前自动备份，确保代码安全

📱 Vue 文件增强

智能分栏系统

• 双分栏模式：将 Vue 单文件组件分解为左右两个编辑器窗口，方便对比和编辑
• 自动识别：智能识别 Vue 文件的 <template>、<script>、<style> 三个区域
• 实时同步：左右分栏内容实时同步，修改一处另一处自动更新
• 快捷切换：通过 Ctrl+J 快速切换不同的分栏显示模式

多种分栏模式

1. 无折叠模式：左右分栏都显示完整内容，适合全局查看
2. 三区域模式：右分栏创建三个标签页，分别显示 template、script、style
3. Script 专注模式：左分栏显示 template+style，右分栏专注显示 script 代码
4. Template 专注模式：左分栏显示 script，右分栏显示 template+style
5. Style 专注模式：左分栏显示 template+script，右分栏专注显示 style

Vue 开发优化

• 语法高亮保持：分栏后每个区域保持正确的语法高亮和代码提示
• 折叠状态记忆：记住用户的折叠偏好，下次打开相同类型文件时自动应用
• 快速导航：在不同区域间快速跳转，提高开发效率

💬 注释功能

块注释生成

• JSDoc 格式：快速生成标准的 /** */ 格式块注释，符合 JSDoc 规范
• 智能模板：根据光标位置自动判断是否为函数、类或变量，生成对应的注释模板
• 快捷键操作：使用 Ctrl+Shift+/ 一键生成块注释
• 自动格式化：生成的注释自动按照项目的代码风格进行格式化

强化注释系统

• 嵌套注释支持：在 HTML 和 CSS 中支持嵌套注释，解决传统注释的局限性
• 智能识别：自动识别当前文件类型，使用相应的注释语法
• 多行注释：支持选中多行代码进行批量注释和取消注释
• 注释切换：Ctrl+/ 智能切换注释状态，已注释的代码取消注释，未注释的添加注释

注释增强功能

• TODO 标记：支持 TODO、FIXME、NOTE 等特殊标记的高亮显示
• 注释对齐：自动对齐多行注释，保持代码整洁
• 注释模板：提供常用的注释模板，如版权信息、函数说明等

🔧 开发工具

VSCode 集成

• 一键打开：右键项目目录选择"使用vscode打开所在目录"
• 路径智能识别：自动识别项目根目录，确保在正确的位置打开 VSCode
• 环境检测：自动检测系统中的 VSCode 安装路径，支持多版本共存
• 快速切换：在 HBuilderX 和 VSCode 之间快速切换，充分利用两个编辑器的优势

引号跳转系统

• 智能选择：Alt+↑/↓ 快速跳转到上一个/下一个引号区域
• 精确定位：自动选中引号内的完整内容，包括嵌套引号的处理
• 多种引号支持：支持单引号、双引号、反引号等多种引号类型
• 批量操作：选中引号区域后可以进行批量替换、复制等操作

智能导航功能

• 快速定位：在大文件中快速定位到指定的引号区域
• 历史记录：记住最近访问的引号位置，支持快速返回
• 可视化指示：高亮显示当前选中的引号区域，提供清晰的视觉反馈
• 键盘优先：所有操作都支持纯键盘操作，提高编码效率

🚀 快速开始

安装要求

基础环境

• HBuilderX 版本：≥ 2.7.0

插件依赖

• plugin-manager：HBuilderX 插件管理器（内置）

核心依赖包

兼容性说明

• Prettier 3.x：支持最新的代码格式化特性和语法
• Node.js：建议使用 Node.js 14+ 版本以获得最佳性能
• 文件编码：支持 UTF-8、GBK 等多种编码格式

安装方法

方式一：离线安装（推荐）

1. 下载插件：获取完整的 format-and-save 文件夹（包含 node_modules 目录）
2. 放置插件：将整个文件夹复制到 HBuilderX 插件目录
   • Windows: HBuilderX安装目录/plugins/ 或 %APPDATA%/HBuilder X/plugins/
   • macOS: ~/Library/Application Support/HBuilder X/plugins/
   • Linux: ~/.config/HBuilder X/plugins/
3. 重启 HBuilderX：重启编辑器使插件生效
4. 验证安装：检查菜单中是否出现相关功能

方式二：在线安装依赖

如果下载的插件不包含 node_modules 目录，需要手动安装依赖：

1. 进入插件目录：

   cd /path/to/HBuilderX/plugins/format-and-save

2. 安装依赖：

   npm install
   # 或使用 yarn
   yarn install

3. 依赖安装完成后，重启 HBuilderX

依赖自动安装机制

🚀 智能依赖管理：插件内置了完整的依赖检测和自动安装系统：

• 🔍 启动时检测：插件激活时自动检测依赖完整性
• 📦 智能验证：检查 node_modules 目录和核心依赖包
• 🎯 模块加载测试：尝试加载 prettier、await-to-js、fast-diff 等核心模块
• 🚀 一键安装：依赖缺失时提供自动安装选项
• 🔄 多重备选：支持 npm、yarn、cnpm 多种包管理器
• ✅ 安装验证：安装完成后自动验证并激活功能

自动安装流程详解

第一步：依赖检测

插件激活 → 检查 package.json → 检查 node_modules 目录
    ↓
验证核心依赖包存在 → 尝试加载模块 → 检测结果

第二步：用户选择

┌─ 🔍 检测到依赖缺失
│
├─ 💬 弹出选择对话框：
│  │
│  ├─ [🚀 自动安装] → 智能安装流程
│  │   ├─ npm install --production --no-optional
│  │   ├─ yarn install --production --ignore-optional
│  │   └─ cnpm install --production --no-optional
│  │
│  ├─ [📋 手动安装] → 显示详细指导
│  │   ├─ 显示插件路径
│  │   ├─ 提供安装命令
│  │   └─ 复制路径到剪贴板
│  │
│  └─ [❌ 取消] → 跳过安装（功能受限）
│
└─ ✅ 安装完成 → 自动加载模块 → 激活所有功能

第三步：安装执行

• 超时保护：5分钟安装超时，避免无限等待
• 进度提示：显示"正在安装插件依赖，请稍候..."
• 错误处理：安装失败时自动尝试下一个包管理器
• 成功反馈：安装成功后显示"依赖安装成功，插件已激活！"

包管理器支持

手动安装指导

如果选择"手动安装"，插件会显示：

# 进入插件目录
cd "插件完整路径"

# 选择其中一种方式安装
npm install
# 或
yarn install
# 或
cnpm install

# 安装完成后重启 HBuilderX

便利功能：

• 🔗 一键复制路径：点击"复制路径"按钮直接复制插件目录
• 📍 路径自动识别：自动显示插件的完整安装路径
• 🔄 重启提醒：安装完成后提醒重启 HBuilderX

依赖说明详情

format-and-save/
├── package.json          # 插件配置和依赖声明
├── extension.js          # 插件入口文件
├── node_modules/         # 依赖包目录（未包含）
│   ├── prettier/         # v3.6.2 - 代码格式化核心
│   ├── await-to-js/      # v3.0.0 - 异步错误处理
│   └── fast-diff/        # v1.3.0 - 文本差异计算
└── src/                  # 插件源码目录

故障排除

如果插件无法正常工作，请检查：

1. 依赖完整性：确认 node_modules 目录存在且包含所有依赖
2. 权限问题：确保 HBuilderX 有插件目录的读写权限
3. 版本兼容：确认 HBuilderX 版本 ≥ 2.8.0
4. 重启编辑器：安装后必须重启 HBuilderX

手动重装依赖（如有需要）

# 删除现有依赖
rm -rf node_modules package-lock.json

# 重新安装
npm install --production

# 或指定依赖源
npm install --registry https://registry.npmmirror.com

⌨️ 快捷键

📋 右键菜单

编辑器右键菜单

• prettier格式化代码：格式化当前文件
• 向右复制分栏并自动折叠：
  • 无折叠模式
  • 左分栏不折叠，右分栏三区域显示
  • 左分栏显示 template+style，右分栏显示 script
  • 左分栏显示 script，右分栏显示 template+style
  • 左分栏显示 template+script，右分栏显示 style

项目目录右键菜单

• 使用vscode打开所在目录：在 VSCode 中打开项目
• 格式化整个项目：批量格式化项目中的所有文件

⚙️ 配置文件

.prettierrc.js

插件提供了完整的 Prettier 配置文件，包含以下主要配置：

module.exports = {
    printWidth: 180, // 每行最大长度
    tabWidth: 4, // 缩进空格数
    useTabs: true, // 使用制表符缩进
    semi: false, // 不添加分号
    singleQuote: true, // 使用单引号
    trailingComma: 'es5', // ES5 尾随逗号
    bracketSpacing: true, // 对象括号空格
    // ... 更多配置
}

.prettierignore

默认忽略以下文件和目录：

• uni_modules/、node_modules/
• *.min.js、*.min.css
• dist/、build/、unpackage/
• 配置文件和类型声明文件

🎯 使用场景

1. 日常开发

• 使用 Ctrl+S 保存时自动格式化代码
• 保持代码风格一致性

2. Vue 开发

• 使用 Ctrl+J 快速查看 Vue 文件结构
• 分栏显示不同区域，提高开发效率

3. 项目维护

• 右键项目目录，一键格式化整个项目
• 统一项目代码风格

4. 代码审查

• 使用分栏功能对比代码
• 快速导航和注释

🔧 高级功能

智能配置检测

• 优先使用项目根目录的 .prettierrc.js 配置
• 自动创建缺失的配置文件
• 支持 .prettierignore 忽略规则

文件类型支持

• JavaScript/TypeScript
• Vue 单文件组件
• HTML/CSS
• JSON
• Markdown
• 更多格式持续支持

错误处理

• 智能错误提示
• 不支持格式的文件自动跳过
• 配置文件错误诊断

📝 更新日志

v0.1.5

• 重构插件架构
• 优化格式化性能
• 增强 Vue 文件支持
• 完善错误处理机制

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件。

📄 许可证

MIT License

🔗 相关链接

• HBuilderX 官网
• Prettier 官网

享受高效的代码格式化体验！ 🎉