Параметры

Prettier поставляется с несколькими параметрами форматирования.

Чтобы узнать больше о позиции Prettier по параметрам, см. Философию параметров.

Если вы измените какие-либо параметры, рекомендуется сделать это через файл конфигурации. Таким образом, Prettier CLI, интеграции с редакторами и другие инструменты будут знать, какие параметры вы используете.

Экспериментальные условные операторы

Попробуйте новый формат условных операторов Prettier перед тем, как он станет стандартным.

Допустимые параметры:

• true - Используйте необычные условные операторы, где знак вопроса следует за условием.
• false - Сохраните стандартное поведение условных операторов; знак вопроса остается на той же строке, что и следствие.

Ширина вывода

Укажите длину строки, по которой будет производиться перенос.

Для удобочитаемости не рекомендуется использовать более 80 символов:

В руководствах по стилю кода часто устанавливаются правила максимальной длины строки в 100 или 120 символов. Однако, когда люди пишут код, они не стремятся достичь максимального количества столбцов на каждой строке. Разработчики часто используют пробелы для разбивки длинных строк для улучшения читабельности. На практике средняя длина строки часто оказывается значительно ниже максимума.

Параметр printWidth Prettier работает не так. Это не жёсткий верхний предел длины строки. Это способ сказать Prettier, примерно, какой длины вы хотели бы строки. Prettier будет делать и короче, и длиннее строки, но в целом будет стремиться к указанной ширине printWidth.

Помните, компьютеры глупы. Вам нужно явно сказать им, что делать, в то время как люди могут делать собственные (неявные) суждения, например, о том, когда разбить строку.

Другими словами, не пытайтесь использовать printWidth так, как будто это ESLint’s max-len – они не одно и то же. max-len просто говорит, какова максимальная допустимая длина строки, но не какова предпочтительная длина – а именно это и задаёт printWidth.

Установка max_line_length в файле .editorconfig настроит ширину вывода Prettier, если не переопределена.

(Если вы не хотите переносить строки при форматировании Markdown, можно установить параметр Проза Перенос для его отключения.)

Ширина табуляции

Укажите количество пробелов на уровень отступа.

Установка indent_size или tab_width в файле .editorconfig настроит ширину табуляции Prettier, если не переопределена.

Табуляция

Отступы строк табуляцией вместо пробелов.

Установка indent_style в файле .editorconfig настроит использование табуляции Prettier, если не переопределено.

(Табуляция будет использоваться для отступов, но Prettier использует пробелы для выравнивания, например, в условных операторах. Это поведение известно как SmartTabs.)

Точки с запятой

Печать точек с запятой в конце операторов.

Допустимые параметры:

• true - Добавление точки с запятой в конце каждого оператора.
• false - Добавление точек с запятой только в начале строк, которые могут привести к ошибкам ASI.

Кавычки

Использование одинарных кавычек вместо двойных.

Примечания:

• Кавычки JSX игнорируют этот параметр – см. jsx-single-quote.
• Если количество одинарных кавычек превышает количество двойных, для форматирования строки будут использоваться кавычки, используемые реже - Пример: "I'm double quoted" приводит к "I'm double quoted" и "This \"example\" is single quoted" приводит к 'This "example" is single quoted'.

См. рациональное использование строк для получения дополнительной информации.

Кавычки свойств

Изменение случаев использования кавычек для свойств в объектах.

Допустимые параметры:

• "as-needed" - Добавление кавычек вокруг свойств объектов только там, где это необходимо.
• "consistent" - Если хотя бы одно свойство в объекте требует кавычек, добавить кавычки ко всем свойствам.
• "preserve" - Учитывать использование кавычек в свойствах объектов.

Обратите внимание, что Prettier никогда не убирает кавычки из числовых имён свойств в выражениях Angular, TypeScript и Flow, потому что различие между строковыми и числовыми ключами существенно в этих языках. См.: Angular, TypeScript, Flow. Также Prettier не убирает кавычки из числовых свойств для Vue (см. вопрос об этом).

Кавычки JSX

Использование одинарных кавычек вместо двойных в JSX.

Заключительные запятые

Значение по умолчанию изменено с es5 на all в версии 3.0.0

Печать заключительных запятых, где это возможно, в многострочных синтаксических конструкциях, разделённых запятыми. (Например, в массиве на одной строке заключительные запятые никогда не используются.)

Допустимые параметры:

• "all" - Заключительные запятые, где это возможно (включая параметры и вызовы функций). Для запуска JavaScript-кода с таким форматированием требуется движок, поддерживающий ES2017 (Node.js 8+ или современный браузер) или нижнего уровня компиляция. Это также включает заключительные запятые в параметрах типа в TypeScript (поддерживается с TypeScript 2.7, выпущенной в январе 2018 года).
• "es5" - Заключительные запятые, где это возможно в ES5 (объекты, массивы и т. д.). Заключительные запятые в параметрах типа в TypeScript и Flow.
• "none" - Заключительные запятые не используются.

Пробелы вокруг скобок

Печать пробелов между скобками в литералах объектов.

Допустимые параметры:

• true - Пример: { foo: bar }.
• false - Пример: {foo: bar}.

Строка скобок

Размещение > многострочного HTML-элемента (HTML, JSX, Vue, Angular) в конце последней строки вместо отдельной строки (не относится к самозакрывающимся элементам).

Допустимые параметры:

• true - Пример:

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

• false - Пример:

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

[Устаревшее] Скобки JSX

Этот параметр устарел в версии 2.4.0, используйте --bracket-same-line вместо него

Размещение > многострочного JSX-элемента в конце последней строки вместо отдельной строки (не относится к самозакрывающимся элементам).

Допустимые параметры:

• true - Пример:

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

• false - Пример:

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

Скобки стрелочных функций

Впервые доступен в v1.9.0, значение по умолчанию изменено с avoid на always в v2.0.0

Включать скобки вокруг единственного параметра стрелочной функции.

Допустимые параметры:

• "always" - Всегда включать скобки. Пример: (x) => x
• "avoid" - Исключение скобок, где возможно. Пример: x => x

На первый взгляд, избегание скобок может показаться лучшим выбором из-за меньшего визуального шума. Однако, когда Prettier удаляет скобки, становится сложнее добавлять аннотации типов, дополнительные аргументы или значения по умолчанию, а также вносить другие изменения. Последовательное использование скобок обеспечивает лучший опыт разработчика при редактировании реальных кодовых баз, что оправдывает значение по умолчанию для параметра.

Диапазон

Форматирование только части файла.

Эти два параметра можно использовать для форматирования кода, начиная и заканчивая заданным смещением символов (соответственно, включительно и исключающие). Диапазон будет простираться:

• Назад до начала первой строки, содержащей выбранный оператор.
• Вперед до конца выбранного оператора.

Парсер

Укажите, какой парсер использовать.

Prettier автоматически определяет парсер по пути к файлу, поэтому вам обычно не нужно изменять это значение.

Парсеры babel и flow поддерживают один и тот же набор функций JavaScript (включая аннотации типов Flow). Они могут отличаться в некоторых крайних случаях, поэтому, если у вас возникнут проблемы, попробуйте использовать flow вместо babel. Аналогичное относится к typescript и babel-ts. babel-ts может поддерживать функции JavaScript (предложения), которые ещё не поддерживает TypeScript, но он менее допускает некорректный код и менее проверен, чем парсер typescript.

Допустимые значения:

• "babel" (через @babel/parser) Назывался "babylon" до версии 1.16.0
• "babel-flow" (тот же, что и "babel", но явно включает разбор Flow, чтобы избежать неоднозначности) Доступен с версии 1.16.0
• "babel-ts" (аналогичен "typescript", но использует Babel и его плагин для TypeScript) Доступен с версии 2.0.0
• "flow" (через flow-parser)
• "typescript" (через @typescript-eslint/typescript-estree) Доступен с версии 1.4.0
• "espree" (через espree) Доступен с версии 2.2.0
• "meriyah" (через meriyah) Доступен с версии 2.2.0
• "acorn" (через acorn) Доступен с версии 2.6.0
• "css" (через postcss) Доступен с версии 1.7.1
• "scss" (через postcss-scss) Доступен с версии 1.7.1
• "less" (через postcss-less) Доступен с версии 1.7.1
• "json" (через @babel/parser parseExpression) Доступен с версии 1.5.0
• "json5" (тот же парсер, что и "json", но вывод в формате json5) Доступен с версии 1.13.0
• "jsonc" (тот же парсер, что и "json", но вывод в формате "JSON с комментариями") Доступен с версии 3.2.0
• "json-stringify" (тот же парсер, что и "json", но вывод в формате JSON.stringify) Доступен с версии 1.13.0
• "graphql" (через graphql/language) Доступен с версии 1.5.0
• "markdown" (через remark-parse) Доступен с версии 1.8.0
• "mdx" (через remark-parse и @mdx-js/mdx) Доступен с версии 1.15.0
• "html" (через angular-html-parser) Доступен с версии 1.15.0
• "vue" (тот же парсер, что и "html", но также форматирует синтаксис Vue) Доступен с версии 1.10.0
• "angular" (тот же парсер, что и "html", но также форматирует синтаксис Angular через angular-estree-parser) Доступен с версии 1.15.0
• "lwc" (тот же парсер, что и "html", но также форматирует синтаксис LWC для атрибутов шаблонов без кавычек) Доступен с версии 1.17.0
• "yaml" (через yaml и yaml-unist-parser) Доступен с версии 1.14.0

Примечание: значение по умолчанию было "babylon" до версии 1.13.0.

Примечание: API пользовательского парсера удалён в версии 3.0.0. Используйте плагины вместо него (как перейти).

Путь к файлу

Укажите имя файла, чтобы определить, какой парсер использовать.

Например, следующее использует парсер CSS:

cat foo | prettier --stdin-filepath foo.css

Этот параметр полезен только в командной строке и в API. Он не имеет смысла в файле конфигурации.

Требование прагмы

Доступно с версии 1.7.0

Prettier может ограничивать форматирование файлов, содержащих специальный комментарий (прагму) в начале файла. Это очень полезно при постепенном переходе к Prettier больших, неотформатированных кодовых баз.

Файл с комментарием в начале:

/**
 * @prettier
 */

или

/**
 * @format
 */

Вставка прагмы

Доступно с версии 1.8.0

Prettier может вставлять специальный @format маркер в начало файлов, указывающий, что файл отформатирован с помощью Prettier. Это хорошо работает в сочетании с опцией --require-pragma. Если в начале файла уже есть блок документации, эта опция добавит новую строку с маркером @format.

Обратите внимание, что «в сочетании» не означает «одновременно». При совместном использовании этих двух опций приоритет имеет --require-pragma, поэтому --insert-pragma игнорируется. Идея в том, что при поэтапном внедрении Prettier в большую базу кода разработчики, участвующие в переходе, используют --insert-pragma, в то время как --require-pragma используется остальной командой и автоматизированными инструментами для обработки только уже перешедших файлов. Функция была вдохновлена стратегией внедрения Facebook .

Обертывание прозы

Доступно с версии 1.8.2

По умолчанию Prettier не изменяет обертывание в тексте Markdown, так как некоторые сервисы используют рендер, чувствительный к переносу строки (например, комментарии GitHub и BitBucket). Чтобы Prettier обертывал прозу в соответствии с шириной печати, измените этот параметр на "всегда". Если вы хотите, чтобы Prettier форматировал все блоки прозы в одну строку и полагался на мягкий перенос строки в редакторе/просмотрщике, используйте "never".

Допустимые значения:

• "always" - Обернуть прозу, если она превышает ширину печати.
• "never" - Развернуть каждый блок прозы в одну строку.
• "preserve" - Ничего не делать, оставить прозу как есть. Доступно с версии 1.9.0

Чувствительность к пробелам в HTML

Доступно с версии 1.15.0. Доступно для Handlebars с версии 2.3.0

Укажите глобальную чувствительность к пробелам для HTML, Vue, Angular и Handlebars. См. информацию о чувствительности к пробелам для получения дополнительной информации.

Допустимые значения:

• "css" - Учитывать значение свойства CSS display по умолчанию. Для Handlebars обрабатывается как strict.
• "strict" - Пробелы (или их отсутствие) вокруг всех тегов считаются значимыми.
• "ignore" - Пробелы (или их отсутствие) вокруг всех тегов считаются незначимыми.

Отступы тегов script и style в файлах Vue

Доступно с версии 1.19.0

Нужно ли отступать код внутри тегов <script> и <style> в файлах Vue.

Допустимые значения:

• false - Не отступать теги script и style в файлах Vue.
• true - Отступать теги script и style в файлах Vue.

Конец строки

Доступно с версии 1.15.0, значение по умолчанию изменилось с auto на lf в версии 2.0.0

По историческим причинам существуют два распространённых варианта окончания строк в текстовых файлах. Это \n (или LF для Line Feed) и \r\n (или CRLF для Carriage Return + Line Feed). Первый вариант распространён в Linux и macOS, а второй — в Windows. Некоторые подробности об этом можно найти на Википедии.

Когда люди работают над проектом с разных операционных систем, легко получить смешанные окончания строк в общей репозитории Git. Также возможно, что пользователи Windows случайно изменят окончания строк в ранее сохранённом файле с LF на CRLF. Это приводит к большому git diff и затрудняет изучение истории файла по строкам (git blame).

Если вы хотите убедиться, что весь ваш репозиторий Git содержит только окончания строк в стиле Linux в файлах, обработанных Prettier:

1. Убедитесь, что опция endOfLine Prettier установлена в значение lf (это значение по умолчанию с версии v2.0.0)
2. Настройте плагин предварительной проверки для запуска Prettier
3. Настройте Prettier на запуск в вашей CI-системе с использованием флага --check. Если вы используете Travis CI, установите опцию autocrlf в значение input в .travis.yml.
4. Добавьте * text=auto eol=lf в файл .gitattributes репозитория. Возможно, вам придётся попросить пользователей Windows повторно клонировать репозиторий, чтобы убедиться, что git не преобразовал LF в CRLF при выгрузке.

Все современные текстовые редакторы во всех операционных системах могут правильно отображать окончания строк, когда используется \n (LF). Однако старые версии Блокнота для Windows визуально объединят такие строки в одну, поскольку они могут обрабатывать только \r\n (CRLF).

Допустимые варианты:

• "lf" – Только символ перевода строки (\n), распространён на Linux и macOS, а также внутри репозиториев git
• "crlf" - Символы возврата каретки + перевод строки (\r\n), распространены в Windows
• "cr" - Только символ возврата каретки (\r), используется очень редко
• "auto" - Сохранение существующих окончаний строк (смешанные значения в одном файле нормализуются путём анализа значений, используемых после первой строки)

Установление значения end_of_line в файле .editorconfig настроит использование Prettier для окончания строк, если не переопределено.

Форматирование встроенных языков

Впервые доступно в версии v2.1.0

Управление форматированием кода, вложенного в строку в файле.

Когда Prettier обнаруживает случаи, где, по всей видимости, в строке другого файла размещён код, который он может отформатировать, например, в помеченных шаблонах в JavaScript с тегом по имени html или в блоках кода в Markdown, он по умолчанию пытается отформатировать этот код.

Иногда это поведение нежелательно, особенно в тех случаях, когда строка не должна интерпретироваться как код. Эта опция позволяет переключаться между стандартным поведением (auto) и полным отключением этой функции (off).

Допустимые варианты:

• "auto" – Форматировать встроенный код, если Prettier может его автоматически идентифицировать.
• "off" - Никогда не форматировать автоматически встроенный код.

Одно свойство в строке

Впервые доступно в версии v2.6.0

Принудительное применение правила «одно свойство в строке» для HTML, Vue и JSX.

Допустимые варианты:

• false - Не применять правило «одно свойство в строке».
• true - Применять правило «одно свойство в строке».