文本格式指南

项目
08/10/2023

如果文本元素的粗体、斜体和代码样式的使用恰当、一致，可提高可读性，并有助于避免误解。

粗体

对 UI 元素（例如菜单选项、对话框名称和输入字段名称）使用粗体。

示例

正确示例：在“解决方案资源管理器”中，右键单击项目节点，然后选择“添加”>“新建项”。
错误示例：在“解决方案资源管理器”中，右键单击项目节点，然后选择“添加”>“新建项”。
错误示例：在“解决方案资源管理器”中，右键单击项目节点，然后选择“添加”>“新建项”。

斜体

将斜体用于以下内容：

带有定义或解释的新术语简介。
文件名称、文件夹名称、路径。
用户输入。

示例

正确示例：在应用服务中，应用在应用服务计划中运行。应用服务计划定义要运行 Web 应用的一组计算资源。
错误示例：在应用服务中，应用在“应用服务计划”中运行。应用服务计划定义了一组用于运行 Web 应用的计算资源。
正确示例：将 HttpTriggerCSharp.cs 中的代码替换为以下代码。
错误示例：将 HttpTriggerCSharp.cs 中的代码替换为以下代码。
正确示例：输入 ContosoUniversity 作为名称，然后选择“添加”。
错误示例：输入“ContosoUniversity”作为名称，然后选择“添加”。

代码样式

将代码样式用于以下内容：

代码元素，如方法名称、属性名称和语言关键字。
SQL 命令
NuGet 包名称
命令行命令*
数据库表和列名称
不应本地化的资源名称（例如虚拟机名称）
希望不可点击的 URL

为什么？ 旧版样式指南指定对许多此类文本元素使用粗体。但是，大多数文章都已本地化，代码样式会告诉翻译人员将这部分文本保留不译。

代码样式可以为内联（包括在 ` 中）或跨多行的隔离代码块（包括在 ``` 中）。请将较长的代码片段和路径放在隔离代码块中。

* 在命令行命令中，如果所有平台都支持正斜杠，则在文件路径中使用正斜杠。如果仅支持反斜杠，则使用反斜杠来说明 Windows 上运行的命令。例如，正斜杠在所有平台上的 .NET CLI 上都有效，因此将使用 dotnet build foldername/filename.csproj 而不是 dotnet build foldername\filename.csproj。

使用内联样式的示例

正确示例：默认情况下，实体框架将名为 Id 或 ClassnameID 的属性解释为主键。
错误示例：默认情况下，实体框架将名为 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."
所有隔离代码块都必须具有已批准的语言标记。有关支持语言标记的列表，请参阅如何在文档中包含代码。

占位符

如果希望用户将输入字符串的一部分替换为其自己的值，请使用用尖括号标记的占位符文本（小于 < 且大于 > 个字符）。

选项 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 标记。你将在生成报表中看到一条建议，并且占位符字在发生此情况时不会在 Microsoft Learn 页面输出中呈现。

为避免占位符上的内容丢失，请使用前面所述的 code 格式或转义字符 (\<\>)。

我们不建议使用大括号 { } 作为语法占位符。读者可能会将大括号占位符与以下使用的相同表示法混淆：

可替换文本
格式字符串
字符串内插
文本模板
类似的编程构造

大小写和间距：可以使用连字符（“短横线隔开式”）或下划线分隔占位符名称，或者可以使用帕斯卡命名法来实现。短横线隔开式可能会生成语法错误，下划线可能会与强调划线冲突。所有大写可能与多种语言中的命名常量冲突，但也可能引起对占位符名称的注意。

<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> 和 </kbd> HTML 标记括住键名称。
使用“+”来连接用户同时选择的键。

键和键盘快捷方式的示例

正确示例：选择 Alt+Ctrl+S。
错误示例：按 ALT+CTRL+S。
错误示例：点击 ALT+CTRL+S。

例外

风格指南并非严格的规则。如果它们降低了可读性，请进行部分改动。例如，主要包含代码元素的 HTML 表格如果全部应用代码样式，可能看起来杂乱。在此情况中，可选择使用粗体样式。

如果选择通常需要代码的替代文本样式，请确保该文本可在文章的本地化版本中进行翻译。代码是唯一一种自动防止翻译的样式。如果希望防止本地化但不使用代码样式，请参阅非本地化字符串。

通过