prettier.el
Emacs 的 prettier
包通过运行 Prettier 来重新格式化您的代码,具有最小的开销,可以按需或在保存文件时自动执行。
对于合理大小的文件,在性能良好的系统上,除 Prettier 本身外的额外开销仅为个位数毫秒。
Prettier 在一个长期运行的进程中执行,这样只需支付一次 Node 启动开销,并且 V8 JIT 编译器有更好的机会发挥魔力。
其他功能包括对通过 tramp-mode
重新格式化远程文件的一流支持,以及与许多主要模式的集成。
这不是 Emacs 的官方 Prettier 集成。官方包可以在 https://github.com/prettier/prettier-emacs 找到。
安装
从 MELPA 安装,例如使用 M-x package-install RET prettier RET
。
exec-path
上需要有 node
可执行文件。建议提供最新版本的 Node,因为旧版本往往明显较慢。prettier
还使用 Emacs 的 nvm
包,因此如果您有 nvm,只需运行 nvm install node
即可确保最新版本可用。
Prettier 包需要安装在您的 npm 包内,或者使用 npm
或 yarn
全局安装。最低要求是 1.6 版本,但建议使用最新版本以获得所有解析器、功能和错误修复。
您可以使用 M-x prettier-info
查看给定缓冲区正在使用的版本,并在找不到 Node 或 Prettier 时帮助诊断。
上述说明适用于重新格式化本地文件;有关如何配置远程系统,请参见下文。
故障排除
如果您看到 Cannot find prettier anywhere
错误,即使 Prettier 已全局安装,您可能正在使用通过 Ubuntu 上的 snap
安装的 node
。使用此方法安装时,node
无法找到全局安装的包。可以通过显式设置 NODE_PATH
来解决这个问题,例如:
(setenv "NODE_PATH" "/usr/local/lib/node_modules")
配置
使用 M-x global-prettier-mode
在您的 Prettier 版本和任何已安装插件支持的所有主要模式中启用次要模式(参见下面的 prettier-enabled-parsers)。启用后,次要模式将在保存文件时重新格式化,并将设置从 Prettier 同步到 Emacs,如缩进级别。
要在启动时全局启用 prettier-mode
:
(add-hook 'after-init-hook #'global-prettier-mode)
按文件/目录启用
emacs 有一个很棒的功能叫做每目录本地变量,可以用来自动为特定文件或目录启用 prettier-mode
。例如,如果您在 git 仓库顶部的 .dir-locals.el
文件中放入以下内容:
((js-mode . ((eval . (prettier-mode t)))))
那么它应该会自动为任何使用 js-mode
的文件启用 prettier-mode
。(注意:如果文件已经打开,您需要关闭并重新打开它们才能看到效果。)您也可以按文件路径而不是按模式匹配,如上述文档所述。
还有一种替代机制,如果您想避免向目录添加 .dir-locals.el
,可以将以下内容添加到您的 emacs 配置中:
(dir-locals-set-class-variables 'prettier-js
'((js-mode . ((eval . (prettier-mode t))))))
(dir-locals-set-directory-class "/path/to/my/pretty/project/" 'prettier-js)
使用
通过 prettier-mode
启用为次要模式后,您的源代码会在保存时进行格式化。
您还可以随时在任何缓冲区中使用 M-x prettier-prettify
来美化整个缓冲区(这不需要启用次要模式),以及使用 M-x prettier-prettify-region
来美化区域(但请注意,区域应该与完整的代码块对齐)。
如果您为这两个命令中的任何一个提供前缀参数,您将能够设置/覆盖用于格式化的 Prettier 解析器。
更改 Prettier 配置
每当有任何相关配置更改时,您都应该运行 M-x prettier-restart
,例如当您安装新版本的 Node、Prettier 或任何插件时;当您在已经在 Emacs 中打开文件的目录中安装或卸载 Prettier 作为本地 npm 包时;或者当您更改可能影响任何打开文件的 Prettier 设置时。这样做将清除所有缓存并确保您的更改生效。
在远程服务器上
当您编辑远程主机上的文件时,Prettier 将在该主机上远程运行。这意味着远程主机需要按上述说明安装 Node 和 Prettier。远程主机上无法使用 nvm
;您需要确保正确设置 tramp-remote-path
。
远程格式化可能在未来通过以下方式得到改进:
-
仅使用远程 Prettier 来确定远程文件的选项,但使用本地 Prettier 进行实际格式化。这将有助于处理大型源文件和慢速连接。
-
通过遍历远程文件系统并查找配置文件来消除对远程 Prettier 的需求。这不太可能发生,因为这意味着需要让这个包的代码与 Prettier 配置发现逻辑保持同步。
自定义
M-x customize-group prettier
这是可用选项的概述。个别设置的文档字符串可能包含其他信息。
prettier-mode-sync-config-flag
如果您不希望 prettier-mode
更改您的缓冲区本地设置以匹配 Prettier 选项,请将此设置为 nil
。
prettier-editorconfig-flag
如果你不希望 Prettier 使用 .editorconfig
文件加载选项,请将此项设置为 nil
。
prettier-enabled-parsers
自定义此项以禁用你不想使用的任何解析器。
prettier-infer-parser-flag
如果你不希望 Prettier 根据文件名和内容推断要使用的解析器,请将此项设置为 nil
。
prettier-prettify-on-save-flag
如果你不希望 Prettier 在保存时美化(格式化)缓冲区,请将此项设置为 nil
。你仍然可以使用 prettier-prettify
显式格式化缓冲区,你可能想将其绑定到一个按键。
prettier-inline-errors-flag
如果你希望语法错误内联显示,而不是发送到默认错误缓冲区,请将此项设置为 t
。这个功能是实验性的,当错误在窗口外时可能无法很好地工作。
prettier-pre-warm
选择如何预热 Prettier 缓存。
本质上,这决定了你何时等待 Prettier 启动开销:
使用 none
,你通常在第一次保存时等待。使用 full
,你在首次激活 prettier-mode
时等待。
some
是一个折中方案,你在首次激活时等待一部分,在第一次保存时等待另一部分。
prettier-mode-ignore-buffer-function
这个函数在 prettier-mode
支持的每个缓冲区中调用。如果它返回非 nil 值,该缓冲区将被忽略,prettier-mode
不会为其激活。默认情况下,会忽略嵌套在 node_modules
目录下的文件缓冲区。你可以将其设置为 nil
,这样就不会忽略任何缓冲区。
prettier-mode-lighter
这个 S 表达式作为模式行的一部分进行求值。默认值显示字符串 Prettier
以及缓冲区使用的 Prettier 解析器和 Prettier 版本。
prettier-diff-timeout-seconds
选择允许差异操作运行的时间长度,这对于由 Prettier 重新格式化导致的大文件和许多编辑很重要。差异仅用于将光标移动到正确的新位置(并调整区域、覆盖等),所以本质上这让你决定愿意为此等待多长时间。设置为 0 将禁用超时,并让差异操作始终运行到完成。在 1.4.0 版本之前,这个值固定为 1 秒。
参见 [https://github.com/google/diff-match-patch/wiki/API#diff_maintext1-text2--diffs](diff-match-patch 文档)。
prettier-diff-edit-cost
决定由 Prettier 重新格式化产生的单个编辑如何积极地合并为更大的编辑。默认设置应该能够合理工作。可以将其设置为 0 以完全禁用编辑分组,这是 1.4.0 版本之前的行为。
与 prettier-emacs
的区别
-
prettier-emacs
在外部进程中启动 Prettier,每次调用都要承担 Node 启动开销,除非使用prettier_d
等工具来缓解。本包使用长期运行的子进程。 -
prettier-emacs
让 Prettier 根据文件名猜测要使用的解析器。本包尽可能从主模式推导解析器,只有在不支持主模式时才根据文件名猜测。 -
prettier-emacs
不会修改你的缓冲区配置,如缩进偏移量。默认情况下,prettier-mode
会尝试将缓冲区配置尽可能匹配 Prettier 配置。 -
本包保持光标相对于代码的位置不变。
-
本包对通过
tramp-mode
编辑远程文件提供一流支持(对于大型源文件和慢速连接还有改进空间),并支持使用本地 Prettier 安装(在项目的node_modules
中而不是全局安装)。 -
prettier-emacs
允许通过设置prettier-js-args
或prettier-js-width-mode
来覆盖各种 Prettier 选项。相比之下,本包认为你的 Prettier 配置文件应该作为唯一的真实来源。
致谢
本包深受原始集成 Prettier 到 Emacs 的包 prettier-emacs
的启发。
从源代码构建
有关构建说明,请参阅 HACKING.md
,有关发布过程的信息,请参阅 RELEASING.md
。
许可证
© 2018 年至今 Julian Scheid 版权所有
GNU 通用公共许可证第 3 版或任何更新版本(参见 COPYING)