演示 Markdown 参考文档

Cloud Shell 教程(也称为“演示”)可帮助用户快速而有效地熟悉您的项目,这种教程易于设置和启动。Cloud Shell 演示是一套用 CommonMark Markdown 编写的说明。演示中也可以包含指令,这些指令是演示专用的 Markdown 表达式,用于添加聚焦和项目选择等高级功能。

如需了解如何在 Cloud Shell 中设置、编写和启动演示,请参阅演示编写指南

指令格式

要添加指令,请使用以下格式:

<walkthrough-directive-name param-name="param-value">
</walkthrough-directive-name>

在此格式中,“directive-name”和“param”是占位符。例如,如果您想使用指令 editor-open-file 和参数 filePath,请使用以下格式:

<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>

Cloud Shell 指令

下表列出了在编写 Cloud Shell 演示时可用的指令及其各自的参数。

演示元数据和布局

指令:作者

<walkthrough-author></walkthrough-author>

Author 标记可定义关于作者的元数据。所有参数都是可选的。

参数 说明
name 作者的名字。
repositoryUrl 用于反馈的代码库的链接。
tutorialName 演示 ID

指令:演示时长

<walkthrough-tutorial-duration></walkthrough-tutorial-duration>

Walkthrough Duration 标记可提供时钟图标以及估算演示学习时长的消息。

参数 说明
duration 演示时长估算值(分钟)。

指令:建议的演示卡

<walkthrough-tutorial-card></walkthrough-tutorial-card>

Walkthrough Card 标记可链接到建议的教程。

参数 说明
url 演示网址。
icon 图标名称。
label 用于点击事件分析的标签。

指令:脚注

<walkthrough-footnote>Footnote text here</walkthrough-footnote>

Footnote 指令可将文本指定为步骤底部的脚注。 脚注文本将作为内部文本被写入。

项目选择

指令:项目设置

<walkthrough-project-setup></walkthrough-project-setup>

Project Setup 组件可帮助用户创建或选择要使用的项目。 此步骤将阻止用户继续操作,直到其选择有效项目为止。

项目 Permissions 标记可为演示设置所需的项目权限。如果用户对所选项目没有权限,则 Project Setup 不会将该项目视为有效项目。

如需了解项目权限的工作原理,请参阅文档

参数 说明
permissions (可选)以逗号分隔的所需权限列表。

指令:项目和结算设置

<walkthrough-project-billing-setup></walkthrough-project-billing-setup>

Project and Billing Setup 组件可帮助用户创建或选择要使用的项目。此步骤将阻止用户继续操作,直到其选择启用了结算功能的有效项目为止。

参数 说明
permissions (可选)以逗号分隔的所需权限列表。

聚焦功能和各类按钮

指令:Spotlight pointer

<walkthrough-spotlight-pointer>Label text here</walkthrough-spotlight-pointer>

Spotlight pointer 指令可创建一个可点击标签,该标签可用于聚焦屏幕上指定的界面元素。只需要提供其中一个参数。如果同时提供两个参数,则需要使用 spotlightId

指针可以通过 Instrumentation ID(属于 DOM 元素的属性)或使用 CSS 选择器来选择元素。这两种类型的选择器都允许使用逗号分隔的选择器来匹配元素。与选择器匹配的所有元素都将突出显示。

标签文本将作为内部文本被写入。

参数 说明
spotlightId Instrumentation ID,可以使用逗号来分隔多个 ID。
cssSelector CSS 选择器
聚焦目标/Instrumentation ID 说明
console-nav-menu Console 导航菜单,位于左上方的汉堡形菜单。
devshell-activate-button 用于打开 Cloud Shell 的按钮,靠近右上角。
devshell-web-editor-button 打开位于 Cloud Shell 的顶端栏上的 Orion 编辑器。
devshell-web-preview-button 打开 Cloud Shell 的网络预览窗口。

如需了解编辑器框架内的聚焦功能,请参阅编辑器指令部分。

指令:启用 API

<walkthrough-enable-apis></walkthrough-enable-apis>

Enable APIs 组件可创建一个按钮,点击该按钮会启用 API。此功能可使您的项目访问 GCP API。

请参阅文档,了解您可以启用的 API。

参数 说明
apis 以逗号分隔的待启用 API 的列表。

指令:打开 Cloud Shell

<walkthrough-open-cloud-shell-button></walkthrough-open-cloud-shell-button>

Open Cloud Shell 组件创建一个按钮,当点击该按钮时会打开 Cloud Shell(选中当前项目)。

参数 说明
open-cloud-shell 查看父级步骤时打开 Cloud Shell。

指令:在后台打开 Cloud Shell

<walkthrough-devshell-precreate></walkthrough-devshell-precreate>

devshell-precreate 指令在后台预配了 Cloud Shell 实例,因此加载速度更快。在显示步骤时运行。

动态变量

指令:数据绑定

<walkthrough-watcher-constant></walkthrough-watcher-constant>

演示允许对键值对进行数据绑定。您可以通过指令或演示框架设置这些值,并可使用指令 watcher-constant 在演示会话中定义它们。

之后,您可以通过以下内容来引用字符串值:

{{<key>}}

Markdown 中的示例用法:

# My Walkthrough

## Step 1

<walkthrough-watcher-constant key="my-key" value="Hello Google">
</walkthrough-watcher-constant>

My message: {{my-key}}

包含以下可用的内置键:

值的说明
project-id 用户当前的项目 ID。
project-name 用户的项目名称。

指令:Watcher Constant

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Watcher 是可以为演示设置的动态字符串。Watcher Constant 可定义演示开头的值。如需了解详情,请参阅数据绑定部分。

参数 说明
key Watcher 的键。
value Watcher 的值。

指令:内嵌图标

<walkthrough-inline-icon-name></walkthrough-inline-icon-name>

“inline-icon-name”是您要指定的图标(如 nav-menu-iconconclusion-trophy)的占位符。

以下图标为内嵌图标形式。

内嵌图标名称 图标
cloud-shell-icon Cloud Shell 图标
web-preview-icon 网络预览图标
cloud-shell-editor-icon Cloud Shell Editor 图标
nav-menu-icon 导航菜单图标
notification-menu-icon 通知菜单图标
pin-section-icon 置顶菜单部分图标

以下图标为图片形式。

内嵌图标名称 图标
conclusion-trophy 总结部分的奖杯图标

Cloud Shell Editor 指令

Cloud Shell Editor 页面支持编辑器指令。

指令:打开文件

<walkthrough-editor-open-file></walkthrough-editor-open-file>

Open file 指令可创建一个可点击的标签,用于从编辑器中的 Cloud Shell 磁盘打开文件。

标签文本将作为内部文本被写入。

参数 说明
filePath 相对文件路径

指令:在编辑器中打开选定的文本

<walkthrough-editor-select-line></walkthrough-editor-select-line>

editor-select-line 指令创建一个可点击的标签,点击该标签即可在编辑器中打开文件并在其中选择一行文本。

参数 说明
filePath 相对文件路径
startLine 起始行
startCharacterOffset 起始索引
endLine 结束行
endCharacterOffset 结束索引

指令:在编辑器中打开正则表达式指定的文本

<walkthrough-editor-select-regex>Label text here</walkthrough-editor-select-regex>

editor-select-regex 指令创建一个可用于在编辑器中打开文件的可点击的标签,并根据提供的正则表达式在其中选择文本。

参数 说明
filePath 相对文件路径
regex 要匹配的正则表达式

标签文本将作为内部文本被写入。

指令:Spotlight pointer

<walkthrough-editor-spotlight>Label text here</walkthrough-editor-spotlight>

Spotlight pointer 指令可创建一个可点击标签,该标签可用于聚焦屏幕上的编辑器内指定的界面元素。

指针只能选择预定义的目标。

参数 说明
spotlightId 编辑器 ID

标签文本将作为内部文本被写入。

编辑器聚焦目标 说明
fileMenu 突出显示文件菜单按钮。
editMenu 突出显示修改菜单按钮。
navigator 突出显示项目字段中指定的文件。