格式化給定的檔案與樣式。

$ 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 (關鍵字清單) - 說明要匯出的格式化組態。請參閱以下「匯入相依關係組態」區段。

任務特定選項

• --force - 強制在所有檔案上發生格式化，而非依賴快取。

• --check-formatted - 檢查檔案是否已格式化，這在預提交掛鉤和 CI 腳本中非常有用，它可以拒絕未格式化代碼的貢獻。如果檢查失敗，則不會將格式化內容寫入磁碟。請記住，由於對格式化程式套用改善和修正，格式化輸出的結果在不同的 Elixir 版本中可能有所不同。

• --no-exit - 僅在與 --check-formatted 一起使用時有效。如果您不希望此 Mix 任務失敗 (並傳回非零退出碼)，但仍希望檢查格式錯誤並將它們列印到主控台中，請傳遞此參數。

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

• --dot-formatter - 格式化程式設定檔案路徑。如果存在，則預設為 .formatter.exs。更多資訊請參考上方「格式化選項」區段。

• --stdin-filename - 在標準輸入中被格式化的檔案路徑。如果您使用外掛程式來支援自訂檔案類型，例如 .heex，這將很有用。如果沒有傳入此標記，則會假設透過標準輸入傳遞的代碼是有效的 Elixir 代碼。預設為「stdin.exs」。

何時格式化代碼

我們建議開發人員直接在他們的編輯器中格式化代碼，無論是在儲存檔案時自動執行，還是通過明確的命令或鍵盤綁定執行。如果您的編輯器中沒有此選項，新增所需的整合通常只需呼叫

$ cd $project && mix format $file

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

您也可以透過將樣式和檔案清單傳遞給 mix format 來格式化整個專案的代碼，請參閱此任務文件的最上方。此清單也可以在 .formatter.exs 檔案的 :inputs 鍵中設定。

外掛程式

您可以自訂格式化程式如何執行。外掛程式必須實作 Mix.Tasks.Format 行為。例如，想像您的專案使用 Markdown，而且有兩種不同的方式：透過自訂 ~M 符號，以及透過副檔名為 .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 (原子) - 正在格式化的符號，例如 :M。

• :modifiers (字元清單) - 符號修改詞清單。

• :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（其值形式與 :locals_without_parens 在 Code.format_string!/2 中的值形式相同）。

相依項在 :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]
]