共用方式為

使用 EditorConfig 定義一致的編碼樣式

  • 發行項

若要強制使用程式碼基底的所有人都使用一致的編碼樣式，您可以在解決方案或專案中新增 .editorConfig 檔案。 EditorConfig 檔案設定遵守 EditorConfig.org 所維護的檔案格式規格。許多程式碼編輯器和應用程式都支援 EditorConfig 檔案，包括 Visual Studio。 由於設定位於檔案中，因此它們會伴隨您的程式碼，甚至可以在 Visual Studio 之外使用。

在 Visual Studio 中，EditorConfig 檔案設定優先於工具>選項>文字編輯器>C/C++>程式碼樣式下可用的各種全域文字編輯器設定。 您可以使用 EditorConfig 檔案來自訂每個程式碼庫，以使用該專案專屬的文字編輯器設定。

您可以手動填入 EditorConfig 檔案，或是根據 Visual Studio 中選擇的程式碼樣式設定來自動產生該檔案。 若要根據目前的 Visual Studio 設定建立新 .editorconfig 檔案，請從 Visual Studio 主選單中選擇工具>選項>文字編輯器>C/C++>一般。 然後從設定中選擇產生 .editorconfig 檔案。 選擇專案所在的資料夾，然後選擇 [選取資料夾] 以儲存 .editorconfig 檔案。

使用 EditorConfig 檔案時，仍然可以繼續在 Visual Studio 文字編輯器中設定您自己的個人編輯器喜好設定。 每當您使用沒有 EditorConfig 檔案的程式碼基底時，或 EditorConfig 檔案不覆寫特定的設定時，就會套用這些文字編輯器的設定。 這類喜好設定的範例之一是在程式碼縮排樣式中使用定位字元或空格。

當您在 Visual Studio 中將 EditorConfig 檔案新增至您的專案時，系統只會根據 EditorConfig 設定來格式化新的程式碼。 除非您執行下列其中一個命令，否則不會變更現有程式碼的格式：

  • 程式碼清除。

    在 Visual Studio 編輯器中選取 [程式碼清除]，或按 Ctrl+K、Ctrl+E。 此命令適用於空白字元設定，例如縮排樣式，以及選取的程式碼樣式設定，例如括號喜好設定。

  • 將文件格式化。

    選取 [編輯]>[進階]>[將文件格式化]，或在預設設定檔中按 Ctrl+K、Ctrl+D。 此命令僅適用於空白字元設定，例如縮排樣式。

程式碼一致性

EditorConfig 檔案設定可以讓您在程式碼基底中維護一致的編碼樣式和慣例，無論使用的編輯器或 IDE 為何。 您可以控制的編碼樣式包括縮排樣式、定位字元寬度、行尾字元和編碼等。 例如，如果您的程式碼基底慣例是縮排使用五個空白字元、文件使用 UTF-8 編碼方式，且每一行的結尾為 CR/LF，您可以設定 EditorConfig 檔案來使用這項慣例。

當您在個人專案中使用的編碼慣例和團隊專案的不同時，EditorConfig 檔案非常實用。 例如，您可能偏好在您的程式碼中縮排時新增定位字元。 但是，您的團隊可能偏好縮排時新增四個空格。 EditorConfig 檔案藉由讓您具有每個案例的組態來解決此問題。

由於程式碼基底中的 .editorconfig 檔案包含 .editorconfig 設定，所以會跟隨該程式碼基底一起移動。 只要您在符合 EditorConfig 規範的編輯器中開啟程式碼檔案，便會啟動文字編輯器設定。

注意

由於建置錯誤或警告，您在 EditorConfig 檔案中設定的慣例無法在 CI/CD 管線中強制執行。 任何樣式偏差只會顯示在 Visual Studio 編輯器中和 [錯誤清單] 中。

支援的設定

Visual Studio 中的編輯器支援 EditorConfig 屬性的核心集：

  • indent_style
  • indent_size
  • tab_width
  • end_of_line
  • 字元集
  • trim_trailing_whitespace
  • insert_final_newline
  • 根

EditorConfig 支援所有 Visual Studio 支援語言的 EditorConfig 編輯器設定，除了 XML 以外。

EditorConfig 也支援程式碼樣式慣例，包括 C# 和 Visual Basic 的語言、格式化和命名慣例。

新增及移除 EditorConfig 檔案

當您將 EditorConfig 檔案新增至專案或程式碼基底之後，Visual Studio 會根據 EditorConfig 檔案設定格式化您撰寫的所有新程式碼行。 不過，在您格式化文件或執行程式碼清除之前，Visual Studio 並不會將現有的樣式轉換為新的樣式。 例如，如果您的檔案中以定位字元將縮排格式化，然後新增了以空格將縮排格式化的 EditorConfig 檔案，縮排字元不會自動轉換為空格。 在您格式化文件 (選取 [編輯]>[進階]>[格式化文件] 或 按 Ctrl+K、Ctrl+D) 後，EditorConfig 檔案中的空白字元設定才會套用到現有的程式碼。

如果您從專案或程式碼基底移除了 EditorConfig 檔案，必須關閉並重新開啟所有開啟的程式碼檔案，全域編輯器設定才會影響新的程式碼行。

將 EditorConfig 檔案新增至專案

若要新增 EditorConfig 檔案至專案或解決方案中，請執行下列步驟：

  1. 在 Visual Studio 中開啟專案或解決方案。 選取解決方案或專案節點，視您的 EditorConfig 設定應套用至解決方案中的所有專案或僅只一個專案而定。 您也可以選取專案或解決方案中的資料夾，將 ..editorconfig 檔案新增到此資料夾。

  2. 從功能表中選擇 [專案]>[新增項目]，或按 Ctrl+Shift+A。

    [新增項目] 對話方塊隨即開啟。

  3. 在搜尋方塊中輸入 editorconfig。

    搜尋結果中會顯示兩個 editorconfig 檔案項目範本。

    顯示 Visual Studio 中 EditorConfig 檔案項目範本的螢幕擷取畫面。

  4. 選取 editorconfig 檔案 (空) 範本以新增 EditorConfig 檔案，其中已經預先填入空白字元、程式碼樣式和命名慣例的預設 EditorConfig 選項。 或者，選取 editorconfig 檔案 (.NET) 範本，新增已預先填入預設 .NET 空格、程式碼樣式和命名慣例的 EditorConfig 檔案。

    新的 .editorconfig 檔案會出現在方案總管中，後者在編輯器中開啟為新的索引標籤。

    顯示方案總管和編輯器中 .editorconfig 檔案的螢幕擷取畫面。

  5. 選擇性地編輯檔案，然後加以儲存。

新增 EditorConfig 檔案的其他方式

有數種其他方式，可讓您將 EditorConfig 檔案新資到您專案：

檔案階層和優先順序

當您將 .editorconfig 檔案新增到檔案階層中的資料夾時，其設定會套用到該層級及以下的所有適用檔案。 您也可以覆寫特定專案、程式碼基底，或程式碼基底組件的 EditorConfig 設定，這樣它就會使用和其他程式碼基底組件不同的慣例。 當您納入來自其他地方的程式碼，但不想變更其慣例時，這樣做非常實用。

請遵循這些方針：

  • 若要覆寫部分或全部的 EditorConfig 設定，請將 .editorconfig 檔案新增至您想要套用這些覆寫設定的檔案階層層級。 新的 EditorConfig 檔案設定會套用到相同層級的檔案和所有子目錄中的檔案。

    螢幕擷取畫面，其中顯示了 EditorConfig 階層圖。

  • 如果要覆寫部分而不是全部設定，請在 .editorconfig 檔案中僅指定那些設定。 只有明確列在較低層級 .editorconfig 檔案中的屬性才會被覆寫。 任何較高層級 .editorconfig 檔案中的其他設定仍繼續套用。

  • 如果想要確保不套用任何較高層級 .editorconfig 檔案的設定到此程式碼基底組件，請在較低層級 .editorconfig 檔案中新增 root=true 屬性：

    # top-most EditorConfig file for this level
root = true

EditorConfig 檔案是從上到下讀取。 如果有多個具有相同名稱的屬性，則最先找到具有相同名稱的屬性優先。

編輯 EditorConfig 檔案

Visual Studio 2022 會提供 EditorConfig 檔案的視覺化編輯器。

編輯您的 EditorConfig 檔案後，您必須重新載入程式碼檔案，新的設定才會生效。

Visual Studio 提供 IntelliSense 完成清單，協助您編輯 EditorConfig 檔案。 例如：

螢幕擷取畫面，其中顯示了 EditorConfig 檔案中的 IntelliSense。

如果您要編輯許多 EditorConfig 檔案，則 EditorConfig 語言服務延伸模組會很有幫助。 這項延伸模組有部分功能包括語法反白顯示、 改善的 IntelliSense、驗證和程式碼格式化。

螢幕擷取畫面，其中顯示了 IntelliSense 與 EditorConfig Language Service 延伸模組。

範例

以下範例顯示 C# 程式碼片段在將 EditorConfig 檔案新增至專案之前和之後的縮排狀態：

  1. 在 [工具]>[選項] 對話方塊中，將 Visual Studio 文字編輯器的 [文字編輯器]>C#>[定位字元] 設定為在按下 Tab 鍵時，會產生四個空白字元。

    螢幕擷取畫面，其中顯示了「文字編輯器」索引標籤設定。

  2. 如同預期，當您在下一行按下 Tab 鍵時，會新增四個空白字元來將該行縮排。

    螢幕擷取畫面，其中顯示了 Tab 鍵在程式碼中加入空格。

    螢幕擷取畫面，其中顯示了 Tab 鍵在程式碼中加入空格。

  3. 使用 EditorConfig 切換索引標籤設定即可使用索引標籤。

    在 EditorConfig 檔案中選取 [使用索引標籤]。

    螢幕擷取畫面，其中顯示了設定 TAB 鍵索引標籤的使用方式。

    將名為 .editorconfig 的新檔案新增到專案中，其中包含下列內容。 [*.cs] 指標表示這項變更只會套用到此專案中的 C# 程式碼檔案。

    # Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

  4. 當您按下 Tab 鍵時，現在會出現定位字元，而不是空格。

    螢幕擷取畫面，其中顯示了 Tab 鍵在程式碼中加入定位字元。

    螢幕擷取畫面，其中顯示了 Tab 鍵在程式碼中加入定位字元。

疑難排解 EditorConfig 設定

如果目錄結構中的任何位置或在專案位置上方存在一個 EditorConfig 檔案，Visual Studio 會將該檔案中的編輯器設定套用到您的編輯器。 在此情況下，您可能會在狀態列中看到下列訊息：

User preferences for this file type are overridden by this project's coding conventions.

這表示，如果 [工具]>[選項]>[文字編輯器] 中的任何編輯器設定 (例如縮排大小及樣式、定位點大小或編碼慣例) 是在 EditorConfig 檔案中等於或高於目錄結構中的專案位置所指定，EditorConfig 檔案中的慣例就會覆寫 [文字編輯器] 中的設定。

若要針對 EditorConfig 問題進行疑難排解，請執行下列步驟：

  1. 若要關閉 Visual Studio 的 EditorConfig 支援，請清除 [工具]>[選項]>[文字編輯器] 中的 [遵循專案編碼慣例] 選項。

    螢幕擷取畫面，其中顯示了遵循專案編碼慣例的設定。

  2. 若要在專案的父目錄中尋找任何 EditorConfig 檔案，請開啟命令提示字元，並從包含專案的磁碟根目錄中執行下列命令。

    dir .editorconfig /s

  3. 若要控制 EditorConfig 慣例的範圍，請在存放庫根目錄或專案所在目錄的 .editorconfig 檔案中設定 root=true 屬性。

    Visual Studio 會在已開啟檔案的目錄和每個父目錄中尋找名為 .editorconfig 的檔案。 達到根檔案路徑，或者如果找到 root=true 的 .editorconfig 檔案時，搜尋就會結束。

相關內容