Phoenix.LiveView.HTMLFormatter

Форматирует шаблоны HEEx из файлов .heex или сигилов ~H.

Это mix format плагин.

Настройка

Добавьте его как плагин в файл .formatter.exs и убедитесь, что расширение heex указано в параметре inputs.

[
  plugins: [Phoenix.LiveView.HTMLFormatter],
  inputs: ["*.{heex,ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{heex,ex,exs}"],
  # ...
]

Поддержка редакторов

Большинство редакторов с поддержкой интеграции с mix format должны автоматически форматировать шаблоны .heex и ~H. Для других редакторов может потребоваться пользовательская интеграция, а некоторые из них могут предоставлять дополнительные возможности. Вот несколько полезных публикаций:

• Форматирование шаблонов HEEx в VS Code

Параметры

• :line_length — форматтер Elixir по умолчанию ограничивает длину строки 98 символами. Это значение можно изменить с помощью параметра :line_length в файле .formatter.exs.

• :heex_line_length — изменяет длину строки только для форматтера HEEx.

  [
    # ...omitted
    heex_line_length: 300
  ]

• :migrate_eex_to_curly_interpolation — автоматически преобразует выражение EEx <%= ... %> с одним выражением в вариант с фигурными скобками. По умолчанию — true.

• :attribute_formatters — задаёт форматтеры для определённых атрибутов.

  [
    plugins: [Phoenix.LiveView.HTMLFormatter],
    attribute_formatters: %{class: ClassFormatter},
  ]

• :tag_formatters — задаёт форматтеры для определённых тегов. В настоящее время разрешены только style и script.

  [
    plugins: [Phoenix.LiveView.HTMLFormatter],
    tag_formatters: %{script: MyApp.PrettierFormatter}
  ]

  Подробности см. в документации по Phoenix.LiveView.HTMLFormatter.TagFormatter.

• :inline_matcher — список регулярных выражений, определяющих, следует ли считать компонент встроенным. По умолчанию используется ["link", "button"]: встроенными считаются компоненты, в названии которых есть link или button. Чтобы отключить это поведение, задайте пустой список.

Форматирование

Этот форматтер стремится быть максимально согласованным с форматтером Elixir и учитывает HTML-элементы «блочного» и «встроенного» типа.

Раньше HTML-элементы делили на «блочные» и «встроенные». Хотя сейчас эти понятия определяются CSS, историческое различие сохраняется, поскольку оно обычно определяет поведение браузера при отображении по умолчанию. В частности, добавление или удаление пробелов между открывающим и закрывающим тегами блочного элемента не изменит отображаемый результат, тогда как для встроенных элементов это может произойти.

Подробнее об этих понятиях можно узнать по ссылкам:

• https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content
• https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content

Дан HTML-код:

  <section><h1>   <b>{@user.name}</b></h1></section>

Он будет отформатирован следующим образом:

<section>
  <h1><b>{@user.name}</b></h1>
</section>

Блочный элемент будет перенесён на следующую строку, а встроенные элементы останутся в текущей строке, если они помещаются в заданную длину строки.

Встроенные элементы также останутся на отдельных строках, если вы намеренно разместили их таким образом:

<section>
  <h1>
    <b>{@user.name}</b>
  </h1>
</section>

Если атрибуты не помещаются в текущую строку, форматтер разместит каждый из них на отдельной строке. Таким образом, следующий код:

<section id="user-section-id" class="sm:focus:block flex w-full p-3" phx-click="send-event">
  <p>Hi</p>
</section>

Будет отформатирован так:

<section
  id="user-section-id"
  class="sm:focus:block flex w-full p-3"
  phx-click="send-event"
>
  <p>Hi</p>
</section>

Этот форматтер не форматирует выражения Elixir с помощью do...end. При этом содержащийся в нём текст будет отформатирован соответствующим образом. Например, такой исходный код:

<%= live_redirect(
       to: "/my/path",
  class: "my class"
) do %>
        My Link
<% end %>

Будет отформатирован так:

<%= live_redirect(
       to: "/my/path",
  class: "my class"
) do %>
  My Link
<% end %>

Обратите внимание: форматированию подвергся только текст My Link.

Преднамеренные переводы строк

Форматтер сохраняет преднамеренные переводы строк. Однако, если их несколько подряд, он оставит не более одного:

<p>
  text


  text
</p>

Будет отформатирован так:

<p>
  text

  text
</p>

Встроенные элементы

Мы не форматируем встроенные элементы, если перед ними или после них есть текст без пробелов. Иначе добавление лишнего пробела изменило бы отображаемый результат.

Форматтер считает следующие теги встроенными элементами:

• <a>
• <abbr>
• <acronym>
• <audio>
• <b>
• <bdi>
• <bdo>
• <big>
• <br>
• <button>
• <canvas>
• <cite>
• <code>
• <data>
• <datalist>
• <del>
• <dfn>
• <em>
• <embed>
• <i>
• <iframe>
• <img>
• <input>
• <ins>
• <kbd>
• <label>
• <map>
• <mark>
• <meter>
• <noscript>
• <object>
• <output>
• <picture>
• <progress>
• <q>
• <ruby>
• <s>
• <samp>
• <select>
• <slot>
• <small>
• <span>
• <strong>
• <sub>
• <sup>
• <svg>
• <template>
• <textarea>
• <time>
• <u>
• <tt>
• <var>
• <video>
• <wbr>
• Теги и компоненты, соответствующие параметру :inline_matcher.

Все остальные теги считаются блочными элементами.

Пропуск форматирования

Если вы не хотите, чтобы часть HTML-кода форматировалась автоматически, используйте специальный атрибут phx-no-format, чтобы форматтер пропустил блок элемента. Обратите внимание: этот атрибут не будет отображён.

Таким образом:

<.textarea phx-no-format>My content</.textarea>

В редакторе кода этот фрагмент останется без изменений, но будет отображён так:

<textarea>My content</textarea>