格式化給定的檔案和模式。

$ mix format mix.exs "lib/**/*.{ex,exs}" "test/**/*.{ex,exs}"

如果任何檔案是 -，則從標準輸入讀取輸入，並將輸出寫入標準輸出。

格式化選項

格式化程式會讀取目前目錄中的 .formatter.exs 檔案，以進行格式化設定。評估此檔案應傳回關鍵字清單。

以下是 .formatter.exs 檔案的範例，可用作起點

[
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]

除了 Code.format_string!/2 中列出的選項之外，.formatter.exs 檔案還支援下列選項

• :inputs（路徑和模式清單）- 指定此任務要使用的預設輸入。例如，["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]。模式會使用 Path.wildcard/2 擴充。

• :plugins（模組清單）（自 v1.13.0 起）- 指定模組清單，以自訂格式化程式的運作方式。有關更多資訊，請參閱下方的「外掛程式」區段。

• :subdirectories（路徑和模式清單）- 指定具有其自己的格式化規則的子目錄。每個子目錄都應有一個 .formatter.exs，用於設定該子目錄中的條目應如何格式化。.formatter.exs 之間的設定不會共用或繼承。如果 .formatter.exs 將「lib/app」列為子目錄，則 .formatter.exs 中的規則將不會在 lib/app/.formatter.exs 中提供。請注意，父 .formatter.exs 不得在其 :inputs 設定中指定「lib/app」子目錄中的檔案。如果發生這種情況，將會選取哪個格式化設定的行為未指定。

• :import_deps（依據原子指定的相依性清單）- 指定要匯入其格式化設定的相依性清單。有關更多資訊，請參閱下方的「匯入相依性設定」區段。

• :export（關鍵字清單）- 指定要匯出的格式化設定。請參閱下方的「匯入相依性設定」區段。

特定於任務的選項

• --check-formatted - 檢查檔案是否已格式化。這在預提交掛鉤和 CI 腳本中很有用，如果你想拒絕未格式化程式碼的貢獻。如果檢查失敗，格式化的內容不會寫入磁碟。請記住，格式化的輸出可能因 Elixir 版本而異，因為改進和修正已套用於格式化程式。

• --no-exit - 僅在與 --check-formatted 一起使用時有效。如果你不希望此 Mix 任務失敗（並傳回非零退出碼），但仍想檢查格式錯誤並將其列印到主控台，請傳遞此選項。

• --dry-run - 格式化後不儲存檔案。

• --dot-formatter - 格式化程式設定檔檔案的路徑。如果有一個可用，預設為 .formatter.exs。有關更多資訊，請參閱上面的「格式化選項」部分。

• --stdin-filename - 正在 stdin 上格式化的檔案路徑。如果你正在使用外掛程式來支援自訂檔案類型（例如 .heex），這很有用。如果不傳遞此標記，則假設透過 stdin 傳遞的程式碼是有效的 Elixir 程式碼。預設為「stdin.exs」。

何時格式化程式碼

我們建議開發人員直接在編輯器中格式化程式碼，無論是在儲存檔案時自動格式化，還是透過明確的命令或按鍵繫結。如果你的編輯器中沒有此選項，新增所需的整合通常是呼叫

$ cd $project && mix format $file

其中 $file 參照目前的檔案，而 $project 是你的專案根目錄。

也可以透過傳遞樣式和檔案清單給 mix format 來格式化整個專案的程式碼，如本任務文件最上方所示。此清單也可以在 .formatter.exs 檔案中的 :inputs 鍵下設定。

外掛程式

可以自訂格式化程式的行為。外掛程式必須實作 Mix.Tasks.Format 行為。例如，假設你的專案以兩種不同的方式使用 Markdown：透過自訂 ~M sigil，以及透過副檔名為 .md 和 .markdown 的檔案。自訂外掛程式會像這樣

defmodule MixMarkdownFormatter do
  @behaviour Mix.Tasks.Format

  def features(_opts) do
    [sigils: [:M], extensions: [".md", ".markdown"]]
  end

  def format(contents, opts) do
    # logic that formats markdown
  end
end

傳遞給 format/2 的 opts 包含所有格式化選項和

• :sigil (原子) - 正在格式化的 sigil，例如 :M。

• :modifiers（字元清單）- sigil 修飾詞清單。

• :extension（字串）- 正在格式化的檔案副檔名，例如 ".md"。

現在任何應用程式都可以使用您的格式化程式，如下所示

# .formatter.exs
[
  # Define the desired plugins
  plugins: [MixMarkdownFormatter, AnotherMarkdownFormatter],
  # Remember to update the inputs list to include the new extensions
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}", "posts/*.{md,markdown}"]
]

請注意，在使用外掛程式執行格式化程式時，您的程式碼會先編譯。

此外，您輸入外掛程式的順序就是格式順序。因此，在上述 .formatter.exs 中，MixMarkdownFormatter 會在 AnotherMarkdownFormatter 之前格式化 markdown 檔案和 sigil。

匯入相依性設定

此任務支援從相依性匯入格式化程式設定。

想要匯出格式化程式設定的相依性，需要在專案根目錄有一個 .formatter.exs 檔案。在此檔案中，相依性可以列出一個 :export 選項，其中包含要匯出的設定。目前，:export 下只支援一個選項：:locals_without_parens（其值與 Code.format_string!/2 中 :locals_without_parens 的值形狀相同）。

相依性的 :export 選項中 :locals_without_parens 下列出的函式，可以在專案的格式化程式設定檔的 :import_deps 選項中列出該相依性後匯入專案。

例如，假設您有一個名為 my_app 的專案，它相依於另一個名為 my_dep 的專案。my_dep 想要匯出一些設定，因此 my_dep/.formatter.exs 會如下所示

# my_dep/.formatter.exs
[
  # Regular formatter configuration for my_dep
  # ...

  export: [
    locals_without_parens: [some_dsl_call: 2, some_dsl_call: 3]
  ]
]

為了匯入設定，my_app 的 .formatter.exs 會如下所示

# my_app/.formatter.exs
[
  import_deps: [:my_dep]
]