文字格式設定指導方針

發行項
08/10/2023

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

粗體

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

範例

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

斜體

使用斜體來表示：

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

範例

正確：在 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 案例可能會產生語法錯誤，而底線可能會與底線衝突。 All-caps 可能會與許多語言中的具名常數衝突，但也可以注意預留位置名稱。

<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 資料表中多為程式碼項目，滿滿的程式碼樣式看起來會很擁擠。您可以在該內容中選擇粗體樣式。

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

Share via