共用方式為

文字格式設定指導方針

  • 發行項

對文字項目一致且適當地使用粗體、斜體和程式碼樣式可提升可讀性並避免誤解。

粗體

使用粗體來表示使用者介面元素，例如功能表選取項目、對話方塊名稱、輸入欄位名稱。

範例

  • 這：在 方案總管 中，以滑鼠右鍵按兩下項目節點，然後選取[新增>專案]。
  • 不是這樣：在 方案總管 中，以滑鼠右鍵按兩下項目節點，然後選取[新增>專案]。
  • 不是這樣：在 方案總管 中，以滑鼠右鍵按兩下項目節點，然後選取[新增>專案]。

斜體

使用斜體來表示：

  • 介紹新的字詞，包含其定義或說明。
  • 檔案名稱、資料夾名稱、路徑。
  • 使用者輸入。

範例

  • 正確：在 App Service 中，應用程式會在 App Service 方案中執行。 App Service 方案定義一組計算資源供 Web 應用程式執行。
  • 不是這樣：在 App Service 中，應用程式會在「App Service 方案」中執行。App Service 方案會定義一組要執行之 Web 應用程式的計算資源。
  • 這：將 HttpTriggerCSharp.cs 中的程式代碼取代為下列程序代碼。
  • 不是這樣：將中的 HttpTriggerCSharp.cs 程式代碼取代為下列程序代碼。
  • 這：輸入 ContosoUniversity 以取得 [名稱]，然後選取 [ 新增]。
  • 不是這樣：針對 [名稱] 輸入 “ContosoUniversity”，然後選取 [新增]。

程式碼樣式

使用程式碼樣式來表示：

  • 程式碼項目，例如方法名稱、屬性名稱和語言關鍵字。
  • SQL 命令
  • NuGet 套件名稱
  • 命令列命令*
  • 資料庫資料表和資料行名稱
  • 不應當地語系化的資源名稱，例如虛擬機器名稱
  • 不想讓人按的 URL

為什麼？ 較舊的樣式指南會為許多這類文字元素指定粗體。 然而，大部分的文章都已當地語系化，而程式碼樣式能告訴譯者保留該部分的文字不要翻譯。

程式代碼樣式可以是 跨多行的內嵌 式程式代碼區塊（以 '' 括住）或 圍欄 式程式代碼區塊。 請將較長的程式碼片段和路徑放在括住的程式碼區塊中。

* 在命令列命令中，如果所有平臺上都支援正斜線，請在檔案路徑中使用正斜線。 使用反斜杠來說明只在支援反斜杠時，在 Windows 上執行的命令。 例如，正斜線適用於所有平臺上的 .NET CLI，因此您會使用 dotnet build foldername/filename.csproj 而不是 dotnet build foldername\filename.csproj。

內嵌樣式的範例

  • 正確：根據預設，Entity Framework 會將名為 Id 或 ClassnameID 的屬性解譯為主索引鍵。
  • 不正確：根據預設，Entity Framework 會將名為 Id 或 ClassnameID 的屬性解譯為主索引鍵。
  • 正確：Microsoft.EntityFrameworkCore 套件提供 EF Core 的執行階段支援。
  • 不正確：Microsoft.EntityFrameworkCore 套件提供 EF Core 的執行階段支援。

括住的程式碼區塊範例

  • 正確：只變更 IQueryable 的陳述式不會將任何命令傳送至資料庫，如下列程式碼：

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • 不是這樣：只有變更 IQueryable 的語句不會將任何命令傳送至資料庫，例如 var students = context。Students.Where（s => s.LastName == “Davolio”）。

  • 正確：例如，若要在 C:\Scripts 目錄中執行 Get-ServiceLog.ps1 指令碼，請鍵入：

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • 不正確：例如，若要在 C:\Scripts 目錄中執行 Get ServiceLog.ps1 指令碼，請鍵入："C:\Scripts\Get-ServiceLog.ps1"。

  • 所有隔離的程式碼區塊都必須有已核准的語言標記。 如需支援的語言標記清單，請參閱如何在 Docs 中包含程式碼。

預留位置

如果您希望使用者以自己的值取代輸入字串的一部分，請使用以角括號標示的佔位元文字（小於 < 和大於 > 字元）。

選項 1： 使用程式代碼樣式來包圍佔位元字組或包含的片語。 例如，您可以針對單一片語使用單一反引號 '，或針對程式代碼圍欄格式使用三個刻度 ''。

`az group delete -n <ResourceGroupName>`

轉譯為：

az group delete -n <ResourceGroupName>

或

選項 2： 使用反斜杠字元 \ 逸出 Markdown 中的角括號字元，例如 \< 和 \>。 雖然只需要左角括弧上的第一個逸出，但逸出右括弧\<\>也適用於一致性。 轉譯的 HTML 不會向讀取器顯示逸出字元：

az group delete -n \<ResourceGroupName\>

轉譯為：

az group delete -n <ResourceGroupName>

通知讀者有關佔位符的資訊：在這類佔位符範例前面的文字中，向讀者說明必須移除方括號中的文字，並以實際值取代。 我們建議針對使用者輸入使用斜體。 您可以在角括弧內嵌程式代碼內格式化斜體：

在下列範例中，將佔位元文字 <ResourceGroupName> 取代為您自己的資源組名。

警告

Microsoft Learn 網站不會 <轉譯使用角括弧的佔位元> 文字，以防括號未正確逸出，或文字不是程式代碼格式。 Microsoft Learn 建置程式會將 <佔位符> 詞組解譯為對讀者瀏覽器可能危險的 HTML 標記，並將它標示為 不允許的 html-tag。 您會在建置報表中看到建議，而且發生此情況時，Microsoft Learn 頁面輸出中不會轉譯佔位元字組。

若要避免佔位元上的內容遺失，請使用code如先前所述的格式設定或逸出字元 （\<\>）。

我們不建議使用大括弧 { } 作為語法佔位符。 讀者可以將大括弧佔位符與中使用的相同表示法混淆：

  • 可取代的文字
  • 格式字串
  • 字串插補
  • 文字範本
  • 類似的程式設計建構

大小寫和間距：您可以使用連字元（“kebab case”） 或底線分隔佔位元名稱，也可以使用Pascal大小寫來進行。 Kebab 案例可能會產生語法錯誤，而且底線可能會與底線衝突。 所有上限可能會與許多語言的具名常數衝突，但也可能引起佔位符名稱的注意。

<Resource-Group-Name> 或 <ResourceGroupName>

標題和連結文字

請勿對標題或超連結文字套用內嵌樣式，例如斜體或粗體。

為什麼呢?

大眾會根據標準超連結文字確認文字項目為可按的連結。 例如，將連結設定為斜體，可能會遮蔽文字是連結的事實。 標題有其專屬樣式，混用其他樣式並不美觀。

標題和連結文字的範例

  • 這:function.json檔案是由 NuGet 套件Microsoft.NET.Sdk.Functions 所產生。

  • 不是這樣:function.json檔案是由 NuGet 套件Microsoft.NET.Sdk.Functions 產生。

  • 正確：

    ### The Microsoft.NET.Sdk.Functions package

  • 不正確：

    ### The *Microsoft.NET.Sdk.Functions* package

鍵盤和鍵盤快速鍵

用到按鍵或按鍵組合時，請遵循下列慣例：

  • 將按鍵名稱的第一個字母大寫。
  • 使用和 </kbd> HTML 標記括住<kbd>索引鍵名稱。
  • 使用 「+」 來聯結使用者同時選取的金鑰。

按鍵和鍵盤快捷方式的範例

  • 這個：選取 Alt+Ctrl+S。
  • 不是這樣：按 ALT+CTRL+S。
  • 不是這樣：按 ALT+CTRL+S。

例外狀況

樣式指導方針並不是僵化的規則。 在會危害可讀性的情況下，可採行不同的做法。 例如，如果 HTML 資料表中多為程式碼項目，滿滿的程式碼樣式看起來會很擁擠。 您可以在該內容中選擇粗體樣式。

如果您在通常會呼叫程式碼之處選擇使用替代的文字樣式，請確定該文字可以在當地語系化版本的文章中翻譯。 畢竟，程式碼是唯一可以自動防止翻譯的樣式。 如果您想要在不使用程式碼樣式的情況下防止當地語系化，請參閱 不可當地語系化的字串。