通过

文本格式指南

如果文本元素的粗体、斜体和代码样式的使用恰当、一致，可提高可读性，并有助于避免误解。 如果本指南未涵盖文本格式设置元素，请参阅 Microsoft写作风格指南。 以下文章提供有关文本格式的详细指导：

UI 元素

UI 元素（如菜单项、对话框名称和文本框的名称）应采用粗体文本。

  • 这一点：在 解决方案资源管理器中，右键单击项目节点，然后选择“ 添加新>项”。

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

Git 存储库和分支名称

选择或输入说明时，对 Git 存储库或分支名称使用加粗文本。

  • 这：在分支菜单中，选择主。

  • 不是这样：在分支菜单中，选择“main”。

新术语简介

使用斜体文本来介绍新术语以及定义或说明。 首次使用它时，将新术语斜体化，然后对定义或说明使用常规文本。

  • 正确示例：在应用服务中，应用在应用服务计划中运行。 应用服务计划定义要运行 Web 应用的一组计算资源。

  • 错误示例：在应用服务中，应用在“应用服务计划”中运行。应用服务计划定义了一组用于运行 Web 应用的计算资源。

代码样式

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

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

为什么？ 某些样式参考线为其中许多文本元素指定粗体。 但是，大多数文章都已本地化，代码样式会告诉翻译人员将这部分文本保留不译。

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

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

使用内联样式的示例

  • 正确示例：默认情况下，实体框架将名为 或 Id 的属性解释为主键ClassnameID。
  • 错误示例：默认情况下，实体框架将名为 Id 或 ClassnameID 的属性解释为主键。
  • 正确示例： 包为 EF Core 提供运行时支持Microsoft.EntityFrameworkCore。
  • 错误示例：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")>）发送到数据库。

  • 正确示例：例如，若要在 目录运行 Get-ServiceLog.ps1 脚本，请键入C:\Scripts：

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

  • 错误示例：例如，若要在 C:\Scripts 目录运行 Get-ServiceLog.ps1 脚本，请键入："C:\Scripts\Get-ServiceLog.ps1."

  • 所有隔离代码块都必须具有已批准的语言标记。 有关支持语言标记的列表，请参阅如何在文档中包含代码。

占位符

在段落文本或过程步骤中，对用户将替换为自己的信息的占位符文本使用斜体。

  • 此项：输入 密码

  • 不是：输入“密码”

  • 此项：输入 -p密码

  • 不是：输入 -p 密码

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

选项 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 标记，并将其标记为 disallowed-html-tag。 你将在生成报告中看到一条建议，如果发生这种情况，占位符文字便不会呈现在 Microsoft Learn 页面输出中。

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

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

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

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

<Resource-Group-Name> 或 <ResourceGroupName>

标题

不要将内联样式（如斜体、粗体或内联代码样式）应用于标题。

为什么？ 标题具有自己的样式，混合其他样式会产生不一致。

  • 此包：导入 Microsoft.NET.Sdk.Functions 包

  • 不是这样：导入 Microsoft.NET.Sdk.Functions 包

链接文本

不要将内联样式（如斜体或粗体）应用于链接文本。

为什么？ 人们依靠标准的超链接文本将文本元素识别为可点击的链接。 例如，将链接样式设置为斜体，可能会掩盖文本是链接的事实。

不是这样： Microsoft.NET.Sdk.Functions 的 NuGet 包生成 function.json 文件。

键和键盘快捷方式

引用键或键组合时，请遵循以下约定：

  • 将键名称的首字母大写。
  • 用 <kbd> 和 </kbd> HTML 标记括住键名称。
  • 使用“+”来连接用户同时选择的键。

键和键盘快捷方式的示例

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

异常

一致的样式准则可创建可靠的客户体验并简化创作过程。 必须仔细考虑这些准则的例外情况。

如果异常情况涉及使用通常需要编码的备用文本样式，请确保在文章的本地化版本中翻译该文本是合适的。 如果希望防止本地化但不使用代码样式，请参阅非本地化字符串。