JsPrettier

JsPrettier是一个适用于Sublime Text的Prettier插件，Prettier是一个有争议的代码格式化工具。

观看快速演示

• 安装
  • 要求
  • 安装Prettier
  • 使用包控制安装JsPrettier
  • 手动安装JsPrettier
  • 使用Git安装JsPrettier
• 使用方法
  • 命令作用域
  • 自定义键绑定
• 设置
  • Sublime Text设置
  • Prettier选项
  • 项目级别设置
  • Prettier配置文件
• Prettier插件支持
  • Prettier PHP
• 问题
• 变更
• 作者
• 许可证

安装

JsPrettier兼容Sublime Text 2和3，以及所有支持的操作系统。

要求

• Sublime Text – 代码文本编辑器
• Node.js – JavaScript运行环境
  • yarn 或 npm – JavaScript的包管理器
    • Prettier – 有争议的代码格式化工具（v3或以上）

安装Prettier

如果你已经安装了Prettier（使用下面的yarn 或 npm命令之一），你已经设置好了……否则

# yarn (local):
yarn add prettier --dev

# yarn (global):
yarn global add prettier

# npm (local):
npm install --save-dev prettier

# npm (global):
npm install --global prettier

使用包控制安装JsPrettier

安装JsPrettier最简单且推荐的方式是使用包控制。

在应用菜单中，转到

• 工具 -> 命令面板... -> 包控制：安装包，键入单词JsPrettier，然后选择它以完成安装。

手动安装JsPrettier

1. 下载并解压 JsPrettier zip 文件 到您的 Sublime Text 包夹目录。
2. 将解压的目录重命名从 SublimeJsPrettier-master 改为 JsPrettier。

默认 Sublime Text 包夹路径：

• OS X: ~/Library/Application Support/Sublime Text [2|3]/Packages
• Linux: ~/.Sublime Text [2|3]/Packages
• Windows: %APPDATA%/Sublime Text [2|3]/Packages

注意 请将 [2|3] 部分替换为您安装的 Sublime Text 版本的适当版本。

使用Git安装JsPrettier

如果您是 Git 用户，可以将 JsPrettier 安装并直接克隆到您的 Sublime Text 包夹目录 来保持其最新状态。

提示： 您可以通过应用菜单中的 首选项 -> 浏览包... 定位到您的 Sublime Text 包夹目录。

git clone https://github.com/jonlabelle/SublimeJsPrettier.git "JsPrettier"

使用方法

有三种方式可以格式化代码

1. 命令面板： 在命令面板 (ctrl/cmd + shift + p) 中输入 JsPrettier 格式化代码。
2. 上下文菜单： 在文件任何位置右键单击弹出上下文菜单并选择 JsPrettier 格式化代码。
3. 键绑定： 默认没有用于运行 Prettier 的键绑定，但您可以 添加自己的键绑定。

命令作用域

JsPrettier 将首先尝试格式化代码的选择，然后是整个文件。当 auto_format_on_save 设置为 true 时，将格式化 整个文件。

自定义键绑定

要添加一个 自定义键绑定，请参考以下示例，该示例将 js_prettier 命令绑定到 ctrl + alt + f

{ "keys": ["ctrl+alt+f"], "command": "js_prettier" }

设置

可以通过导航到应用程序菜单来配置插件设置和 Prettier 选项

• 首选项
  • 包设置
    • JsPrettier
      • 设置 - 默认 （查看默认设置）
      • 设置 - 用户 （覆盖默认设置）

Sublime Text设置

• debug （默认：false）
  当启用（true）时，调试信息将打印到控制台 - 对故障排除和检查传递给 Prettier 的生成命令很有用。启用调试模式还将 Prettier 的 --log-level 选项设置为 debug（当 additional_cli_args 未重写时），以便在控制台打印额外的调试信息。

• prettier_cli_path （默认：空）
  如果 Sublime Text 在自动解析到 Prettier 的路径时出现问题，您可以在此处设置自定义路径。当设置空时，插件将尝试通过

1. Locally installed prettier relative to active view.
2. Locally installed prettier relative to the Sublime Text Project file's root directory.
3. The current user home directory.
4. JsPrettier Sublime Text plug-in directory.
5. Globally installed prettier.

**Examples:**

```json
{
    // macOS and Linux examples:
    "prettier_cli_path": "/usr/local/bin/prettier",
    "prettier_cli_path": "/some/absolute/path/to/node_modules/.bin/prettier",
    "prettier_cli_path": "./node_modules/.bin/prettier",
    "prettier_cli_path": "~/bin/prettier",
    "prettier_cli_path": "$HOME/bin/prettier",
    "prettier_cli_path": "${project_path}/bin/prettier",
    "prettier_cli_path": "$ENV/bin/prettier",
    "prettier_cli_path": "$NVM_BIN/prettier",

    // Windows examples:
    "prettier_cli_path": "C:/path/to/prettier.cmd",
    "prettier_cli_path": "%USERPROFILE%\\bin\\prettier.cmd"
}

```

• node_path （默认：空）
  如果 Sublime Text 在解析到 node 的绝对路径时出现问题，您可以在此处设置自定义路径。

  示例

  {
      // macOS/Linux:
      "node_path": "/usr/local/bin/node",
      "node_path": "/some/absolute/path/to/node",
      "node_path": "./node",
      "node_path": "~/bin/node",
      "node_path": "$HOME/bin/node",
      "node_path": "${project_path}/bin/node",
      "node_path": "$ENV/bin/node",
      "node_path": "$NVM_BIN/node",
  
      // Windows:
      "node_path": "C:/path/to/node.exe",
      "node_path": "%USERPROFILE%\\bin\\node.exe"
  }
  

• auto_format_on_save （默认：false）
  在保存时自动格式化文件。

• auto_format_on_save_excludes （默认：[]）
  当 auto_format_on_save 启用时忽略的文件排除模式。

  示例

  {
      "auto_format_on_save_excludes": [
          "*/node_modules/*",
          "*/file.js",
          "*.json"
      ]
  }
  

• auto_format_on_save_requires_prettier_config （默认：false）
  仅在找到（或未找到）Prettier 配置文件时启用自动保存格式化。

  Prettier 配置文件是通过首先检查 additional_cli_args 设置中是否指定了 --config </path/to/prettier/config> 来解决的，然后是搜索正在格式化的文件的位置，最后导航到文件树直到找到一个配置文件（或未找到）。

• allow_inline_formatting （默认：false）
  启用对内联代码的 选择 格式化能力。例如，在 PHP 或 HTML 文件中格式化 JavaScript 代码的选择。当设置为 true 时，JsPrettier 命令可以在所有 Sublime Text 语法中使用。

• custom_file_extensions（默认：[]）
  已内置对 js、jsx、cjs、mjs、json、jsonc、json5、html、graphql/gql、ts、tsx、cts、mts、css、scss、less、md、mdx、yml、yaml、vue 和 component.html（angular html）文件的内置支持。

  在此处放置额外的文件扩展名，并确保不要包含扩展名前的点。

• max_file_size_limit（默认：-1）
  允许的最大文件大小（以字节为单位），供格式化使用。由于性能原因，文件大小大于指定 max_file_size_limit 的文件将不会进行格式化。将 max_file_size_limit 的值设置为 -1 将禁用文件大小检查（默认）。

• disable_tab_width_auto_detection（默认：false）
  是否禁用插件自动设置 Prettier 的 “tabWidth / –tab-width” 选项，并遵循 Prettier 的配置设置。

• disable_prettier_cursor_offset（默认：false）
  Prettier 在游标偏移计算期间似乎存在一个（明显且讨厌的）缺陷，当尝试格式化大型或压缩文件时（但不仅限于这些情况）。这个问题实际上导致CPU使用率连续攀升至100%……无限期，或直到强制终止运行 Prettier 的 node 可执行文件/进程。

  为了避免这种行为问题，直到问题得到解决，您可以通过将 disable_prettier_cursor_offset 的值设置为 true，禁用插件（JsPrettier）向 Prettier 传递游标偏移位置。

  • 参见相关问题：#147，#168
  • Prettier 游标偏移说明文档

• additional_cli_args（默认：{}）
  附加到 prettier 命令的参数键值对。

  示例

  {
      "additional_cli_args": {
          "--config": "~/.prettierrc",
          "--config": "$HOME/.prettierrc",
          "--config": "${project_path}/.prettierrc",
          "--config": "/some/absolute/path/to/.prettierrc",
  
          "--config-precedence": "file-override",
          "--ignore-path": "${file_path}/.prettierignore",
          "--with-node-modules": "",
          "--plugin-search-dir": "$folder"
      }
  }
  

Prettier选项

• useTabs（通过 translate_tabs_to_spaces 设置内部设置）
  使用制表符进行行缩进。

• printWidth（默认：80）
  指定格式化代码应适应的行限制。

• tabWidth（默认：2）
  指定每个缩进级别的空格数量。

  重要：默认情况下，“tabWidth” 使用 SublimeText 为 “tab_size” 配置的值自动设置。要禁用此行为，您必须首先将 disable_tab_width_auto_detection 的值从 false 更改为 true。

• singleQuote（默认：false）
  使用单引号或双引号进行代码格式化。

• trailingComma（默认："all"）
  控制尽可能多地打印尾随逗号。有效选项

  • "none" - 没有尾随逗号
  • "es5" - 在 ES5（对象、数组等）中有效的尾随逗号
  • "all" - 在可能的情况下保留尾随逗号（函数参数）

• bracketSpacing（默认：true）
  控制打印对象字面量内部的空格。

• bracketSameLine（默认：false）
  将多行 HTML（HTML、JSX、Vue、Angular）元素的 > 放在最后一行末尾，而不是单独放在下一行（不适用于自闭合元素）。

• jsxSingleQuote（默认：false）
  在 JSX 中使用单引号而不是双引号。

• parser（默认："babel"）
  插件（JsPrettier）会自动根据当前文件或选定的内容设置 parser。

• semi（默认值：true）
  true 向每一行的末尾添加分号，或 false 向可能引入 ASI 故障的行首添加分号。

• requirePragma（默认值：false）
  Prettier 可以忽略顶部包含特殊注释的格式化文件，这种注释称为 pragma。当逐步将大型、未格式化的代码库转换为 Prettier 时，这很有用。

  例如，一个文件的第一行注释指定如下，并启用 --require-pragma 选项

  /**
  

  • @prettier */

  or
  
  ```javascript
  /**
   * @format
   */
  

• proseWrap（默认值：“preserve”）
  （仅限 Markdown 和 YAML）默认情况下，Prettier 会按原样包装 Markdown 和 YAML 文本，因为一些服务使用对换行符敏感的渲染器，例如 GitHub 评论和 BitBucket。在某些情况下，您可能希望依靠 SublimeText 的软换行，因此此选项允许您使用“never”退出。

  有效选项

  • “always” - 当文本超过打印宽度时包装文本。
  • “never” - 不包装文本。
  • “preserve” (默认) - 按原样包装文本。从 v1.9.0+ 开始提供。

• arrowParens（默认值：“always”）
  包括单箭头函数参数周围的括号。

  有效选项

  • “avoid” - 除非必要，否则省略括号。例如：x => x
  • “always” (总是) - 总是包括括号。例如：(x) => x

• htmlWhitespaceSensitivity（默认值：“css”）
  （仅限 HTML）指定 HTML 文件的全球空白敏感性，有关更多信息，请参阅 空白敏感性格式化。

  有效选项

  • “css”（默认）- 尊重 CSS 显示属性的默认值。
  • “strict” - 空白被认为是有意义的。
  • “ignore” - 空白被认为是不重要的。

• quoteProps（默认值：“as-needed”）
  更改对象中属性引号的使用。需要 Prettier v1.17+。

  有效选项

  • “as-needed”（默认）- 只有在需要时才添加对象属性的引号。
  • “consistent” - 如果对象中的至少一个属性需要引号，则引用所有属性。
  • “preserve” - 尊重对象属性中输入的引号。

• vueIndentScriptAndStyle（默认值：false）
  （仅限 Vue 文件）是否在 Vue 文件的 <script> 和 <style> 标签内缩进代码。有些人（比如 Vue 的创造者）不缩进来保存缩进级别，但这也可能破坏 Sublime Text 中的代码折叠。

  有效选项

  • false（默认）- 不要在 Vue 文件中缩进脚本和样式标签。
  • true - 在 Vue 文件中缩进脚本和样式标签。

• embeddedLanguageFormatting（默认值：“auto”）
  控制 Prettier 是否格式化文件中嵌入的引号代码。

  当 Prettier 识别到您似乎已在另一个文件中的字符串中放置一些它知道如何格式化的代码的案例时，例如在 JavaScript 中的带有 html 命名的标签模板或 Markdown 中的代码块中，它将默认尝试格式化该代码。

  有时此行为是不希望的，特别是在您可能没有打算将字符串解释为代码的情况下。此选项允许您在默认行为（auto）和完全禁用此功能（off）之间切换。

  请参阅 示例。

  有效选项

  • “auto”（默认）- 如果 Prettier 能够自动识别，则格式化嵌入的代码。
  • “关闭” - 永远不要自动格式化内嵌代码。

• editorconfig（默认：开启）
  是否在解析配置时考虑.editorconfig文件。

  如果editorconfig设置为true且项目中存在.editorconfig文件，Prettier将解析它并将属性转换为对应的Prettier配置。此配置将由.prettierrc等文件覆盖。目前，Prettier支持以下EditorConfig属性

  • end_of_line
  • indent_style
  • indent_size/tab_width
  • max_line_length

• singleAttributePerLine（默认：关闭）
  在HTML、Vue和JSX中强制每个属性一行。

  有效选项

  • 关闭（默认）不强制每个属性一行。
  • 开启强制每个属性一行。

更多详情和示例，请见Prettier选项文档页面。

项目级别设置

JsPrettier支持项目级别设置，在<project_name>.sublime-project文件中指定。

为了让项目级别的设置覆盖之前的配置，您需要在settings下添加一个新的js_prettier键和部分，如下所示。

示例Sublime Text项目文件

{
    "folders": [
        {
            "path": "."
        }
    ],
    "settings": {
        "js_prettier": {
            "debug": false,
            "prettier_cli_path": "",
            "node_path": "",
            "auto_format_on_save": false,
            "auto_format_on_save_excludes": [],
            "auto_format_on_save_requires_prettier_config": false,
            "allow_inline_formatting": false,
            "custom_file_extensions": [],
            "max_file_size_limit": -1,
            "disable_tab_width_auto_detection": false,
            "disable_prettier_cursor_offset": false,
            "additional_cli_args": {},
            "prettier_options": {
                "printWidth": 80,
                "tabWidth": 2,
                "singleQuote": false,
                "trailingComma": "all",
                "bracketSpacing": true,
                "bracketSameLine": false,
                "jsxSingleQuote": false,
                "parser": "babel",
                "semi": true,
                "requirePragma": false,
                "proseWrap": "preserve",
                "arrowParens": "always",
                "htmlWhitespaceSensitivity": "css",
                "quoteProps": "as-needed",
                "vueIndentScriptAndStyle": false,
                "embeddedLanguageFormatting": "auto",
                "editorconfig": true,
                "singleAttributePerLine": false
            }
        }
    }
}

Prettier配置文件

当检测到Prettier配置文件时，除parser、tabWidth和useTabs外的Sublime Text中定义的选项将被忽略。这些选项将根据当前文件或Sublime Text中定义的选择的语法设置自动设置。

自定义Prettier配置文件路径

要指定自定义Prettier配置路径，只需在additional_cli_args中添加一个--config <path>键值项。以下是一个示例

{
    "additional_cli_args":
    {
        "--config": "~/some/path/from/my/home/.prettierrc",
        "--config-precedence": "prefer-file",
        "--ignore-path": "${project_path}/.prettierignore"
    }
}

禁用Prettier配置文件发现

您也可以在additional_cli_args设置中添加--no-config选项，并告诉Prettier不要尝试找到配置文件。

{
    "additional_cli_args": {
        "--no-config": ""
    }
}

Prettier忽略配置文件发现（.prettierignore）

如果在additional_cli_args中没有指定--ignore-path选项，插件将搜索源文件同一目录下的.prettierignore文件，然后是当前激活的Sublime Text项目的根目录。如果两个路径都无法解析，则向上搜索目录树，最后检查用户的主目录。

Prettier插件支持

Prettier PHP

在大多数情况下，Prettier PHP可以作为Prettier的替代品。但是，JsPrettier仅检测您是否正在格式化PHP文件（或PHP选择），并将--parser设置为php。除此之外，您需要确保您的配置符合Prettier PHP 选项。

为了在项目根目录中安装Prettier PHP并将其用作Prettier的替代品

cd to/project/directory
npm install @prettier/plugin-php

Prettier社区插件

这是一个示例SublimeText项目（在问题#239中发布），它使用Prettier社区插件NiklasPor/prettier-plugin-go-template格式化*.gohtml文件。

以及另一个使用@trivago/prettier-plugin-sort-imports来排序导入示例项目（在问题#240中发布）。

问题

要报告错误或提出建议，请新建一个问题并选择合适的Issue模板（错误报告或功能请求）。请确保遵循每个模板中概述的指南……否则您的提交将可能立即被关闭。

变更

请访问变更日志页面以查看完整的变更列表。

作者

Jon LaBelle

许可证

MIT许可证