入门
Podman 桌面扩展可以提供一个入门工作流程,指导用户安装和设置扩展工作所需的所有工具,并可以选择提供有关扩展功能的说明。
为扩展添加入门就像在 package.json
中编写 JSON 一样简单。Podman 桌面会将 JSON 对象转换为实际代码以渲染所有项目。
入门包括一个标题、描述、媒体(图像)、启用子句和一个步骤列表。只有标题、启用子句和步骤是必需的,因为它们构成了定义工作流程所需的最低信息。在深入了解细节之前,让我们先检查 JSON 模式。
{
"title": "onboarding",
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"path": {
"type": "string"
},
"altText": {
"type": "string"
}
},
"enablement": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"path": {
"type": "string"
},
"altText": {
"type": "string"
}
},
"command": {
"type": "string"
},
"completionEvents": {
"type": "array",
"items": {
"type": "string"
}
},
"content": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"highlight": {
"type": "boolean"
},
"when": {
"type": "string"
}
},
"required": ["value"]
}
}
},
"when": {
"type": "string"
},
"component": {
"type": "string",
"enum": ["createContainerProviderConnection", "createKubernetesProviderConnection"]
},
"state": {
"type": "string",
"enum": ["completed", "failed"]
}
},
"required": ["id", "title"]
}
}
},
"required": ["title", "enablement", "steps"]
}
标题、描述和媒体
标题、描述和媒体都放置在入门页面左上角。只有标题是必需的。描述和媒体是可选的。如果未指定媒体,Podman 桌面将显示扩展在其 package.json
中设置的默认图标。
这是 JSON 的定义方式
"icon": "icon.png",
...
"onboarding": {
"title": "Podman Setup",
}
启用
启用子句允许 Podman 桌面确定何时应启用入门。当满足此条件时,用户将在资源页面中找到一个设置按钮。单击它将启动入门工作流程。
启用子句是必需的,必须使用 when 子句 编写。
在以下示例中,我们指定只有当用户的操作系统是 Linux 且 podmanIsNotInstalled
上下文值为 true 时,才需要启用入门。或者,如果用户的操作系统不同于 Linux,则 podmanMachineExists
上下文值必须为 false。本质上,如果用户在 Linux 上,则只有在未安装 podman 时才应启用入门;对于所有其他操作系统,如果不存在 Podman 机器,则应启用它。
"enablement": "(isLinux && onboardingContext:podmanIsNotInstalled) || (!isLinux && !onboardingContext:podmanMachineExists)"
步骤
steps 属性是必需的,它包含在工作流程期间将显示给用户的实际内容。
每个步骤都可以通过多种方式为入门过程做出贡献。您可以选择显示内容向用户解释概念,合并输入元素(如按钮或文本框)以鼓励用户互动,运行命令以执行安装,或展示要配置的设置。
让我们再看看它的模式
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"path": {
"type": "string"
},
"altText": {
"type": "string"
},
},
"command": {
"type": "string"
},
"completionEvents": {
"type": "array",
"items": {
"type": "string"
}
},
"content": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"highlight": {
"type": "boolean"
},
"when": {
"type": "string"
}
},
"required": ["value"]
}
}
},
"when": {
"type": "string"
},
"component": {
"type": "string",
"enum": ["createContainerProviderConnection", "createKubernetesProviderConnection"]
},
"state": {
"type": "string",
"enum": ["completed", "failed"]
}
},
"required": ["id", "title"]
一个步骤只有两个必需字段 - id 和 title。所有其他属性都是可选的。
Id
id 必须是唯一的,用于识别步骤,它永远不会直接显示给用户。
为了更轻松地分析用户执行的步骤的遥测数据,id 值必须遵守一些规则。为了帮助开发人员遵守这些规则,如果 Podman Destop 加载入门时不遵守这些规则,将显示警告。
规则是
- 对于定义命令的步骤,id 必须以
Command
结尾。 - 对于定义
state='failed'
的状态,id 必须以Failure
结尾。 - 对于定义
state='completed'
的状态,id 必须以Success
结尾。 - 对于任何其他步骤,id 必须以
View
结尾。
标题、描述和媒体
标题、描述和媒体的工作方式与前面解释的相同。唯一的区别是它们的位置 - 它们将出现在主体中央。
注意:如果未指定媒体,Podman 桌面将显示提供入门的扩展的图标。
命令
command 字段允许您声明在步骤变为活动时必须运行的命令的名称。命令必须事先由扩展注册,否则会导致错误。
在下面的示例中,我们告诉 Podman 桌面在 checkPodmanInstalled
步骤变为活动时调用 podman.onboarding.checkPodmanInstalled
。根据结果,我们可以提示用户移动到另一个步骤或显示消息。
"commands": [
{
"command": "podman.onboarding.checkPodmanInstalled",
"title": "Podman: Check podman installation"
},
],
"onboarding": {
"title": "Podman Setup",
"steps": [
{
"id": "checkPodmanInstalled",
"title": "Checking for Podman installation",
"command": "podman.onboarding.checkPodmanInstalled",
},
...
],
...
}
在执行命令期间,用户将在标题旁边看到一个旋转器。
完成事件
CompletionEvents 定义应将步骤视为完成的条件。
它目前支持 onboardingContext
和 onCommand
事件。前者可用于评估上下文值,例如 onboardingContext:podmanIsInstalled
。后者检查命令是否已执行 - onCommand:podman.onboarding.installPodman
。
在命令完成执行后将用户推进到下一步的实际示例是
"commands": [
{
"command": "podman.onboarding.checkPodmanInstalled",
"title": "Podman: Check podman installation"
},
],
"onboarding": {
"title": "Podman Setup",
"steps": [
{
"id": "checkPodmanInstalled",
"title": "Checking for Podman installation",
"command": "podman.onboarding.checkPodmanInstalled",
"completionEvents": [
"onCommand:podman.onboarding.checkPodmanInstalled"
]
},
...
],
...
}
当 checkPodmanInstalled
步骤变为活动时,将调用命令 podman.onboarding.checkPodmanInstalled
。完成执行后,步骤将被视为完成,然后用户将被移动到下一个步骤。
以下另一个示例,这次使用上下文值
"commands": [
{
"command": "podman.onboarding.checkPodmanInstalled",
"title": "Podman: Check podman installation"
},
],
"onboarding": {
"title": "Podman Setup",
"steps": [
{
"id": "checkPodmanInstalled",
"title": "Checking for Podman installation",
"command": "podman.onboarding.checkPodmanInstalled",
"completionEvents": [
"onboardingContext:podmanVersion == 4.7.2"
]
},
...
],
...
}
当 checkPodmanInstalled
步骤变为活动时,将调用命令 podman.onboarding.checkPodmanInstalled
。一旦上下文值 podmanVersion
等于 4.7.2
,步骤将被标记为已完成,用户将被移动到下一个步骤。
您可能会想:谁或什么设置上下文值?如果您使用自定义上下文值,则应由您的扩展来设置它。按照上面的示例,我们可以在 podman.onboarding.checkPodmanInstalled
执行期间设置上下文值,例如
extensionApi.commands.registerCommand(
'podman.onboarding.checkPodmanInstalled',
async () => {
// do something
...
// set podmanVersion context value so we can mark the step as complete
extensionApi.context.setValue('podmanVersion', '4.7.2', 'onboarding');
}
)
更新上下文后,UI 将刷新,Podman 桌面会将用户移动到新步骤。
内容
content 属性是一个数组数组,其中父数组中的每个项目定义一行,子数组中的每个项目定义一个单元格。
content = [
['cell', 'cell'], //row
['cell', 'cell', 'cell'], //row
];
内容单元格条目的 JSON 模式是
"type": "object",
"properties": {
"value": {
"type": "string"
},
"highlight": {
"type": "boolean"
},
"when": {
"type": "string"
}
},
"required": ["value"]
Value 是唯一必需的字段,它可以是简单的字符串或 Markdown 字符串,用于呈现高级对象。
除了所有标准 Markdown 语法,Podman 桌面还提供了 3 个自定义 Markdown 组件:按钮、链接和警告列表。
1 - 您可以创建一个执行命令的按钮(语法 - :button[按钮名称]{command=command.example title="工具提示文本"}
)或表现得像链接(语法 - :button[按钮名称]{href=http://my-link title="工具提示文本"}
)。
例如
"value": ":button[Check requirements again]{command=podman.onboarding.checkPodmanRequirements}"
2 - 同样,您可以创建一个执行命令的链接(语法:link[命令链接名称]{command=command.example title="工具提示文本"}
)或像普通链接一样工作(语法 - :link[命令链接名称]{href=http://my-link title="工具提示文本"}
)
例如
"value": "To install Podman please follow these :link[installation instructions]{href=https://podman.org.cn/docs/installation#installing-on-linux}"
3 - 警告组件允许显示项目列表(语法 - :warnings[[item]]
),其中项目包括
"type": "object",
"properties": {
"state": {
"type": "string"
},
"description": {
"type": "string"
},
"command": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"title"
]
},
"docDescription": {
"type": "string"
},
"docLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"group": {
"type": "string"
}
},
"required": [
"title",
"url",
"group"
]
}
},
}
在package.json
中添加完整的列表可能会让人困惑,因此更好的方法是在运行时使用上下文值
"value": ":warnings[${onboardingContext:warningsMarkdown}]"
在运行时,${onboardingContext:warningsMarkdown}
将被后端填充的实际列表替换
const warnings = [];
...
const warning = {
state: res.successful ? 'successful' : 'failed',
description: res.description,
docDescription: res.docLinksDescription,
docLinks: res.docLinks,
command: res.fixCommand,
};
warnings.push(warning);
extensionApi.context.setValue('warningsMarkdown', warnings, 'onboarding');
highlight 和 when 属性是可选的。它们用于更改背景颜色或定义内容列何时可见。
组件
Podman Desktop 有一些内置组件可以完美地融入 onboarding 工作流程,例如 创建新连接
向导。如果您正在开发允许创建 Kubernetes 集群的扩展,重新创建用户可以添加名称、要使用的资源等的页面就没有意义了。这时,component 字段就派上用场了。
通过指定要导入的组件,所有元素、样式和操作都将嵌入到步骤中。
目前,Podman Desktop 仅支持 onboarding 的两种组件类型:createContainerProviderConnection
和 createKubernetesProviderConnection
。
Podman 扩展中可以看到一个示例,您可以在工作流程中创建 Podman 机器。
{
"id": "createPodmanMachine",
"title": "Create a Podman machine",
"when": "!onboardingContext:podmanMachineExists && !isLinux",
"completionEvents": [
"onboardingContext:podmanMachineExists"
],
"component": "createContainerProviderConnection"
},
注意:使用 component 字段时,应省略 content
何时
when 属性定义了何时显示步骤。您可以使用任何 when 子句,Podman Desktop 会在上下文发生变化时对其进行评估。
状态
state,如果设置,允许 Podman Desktop 区分正常步骤和特殊步骤。它用于将步骤与失败状态 (failed
) 或完成状态 (completed
) 关联。
注意:最后一个工作流程步骤应具有 completed
状态。
根据 state,Podman Desktop 可能会显示一些默认对象。
遇到失败状态的步骤时,Podman Desktop 会显示一个 重试
按钮,允许用户重新启动工作流程。
{
"id": "podmanFailedInstallation",
"title": "Failed installing Podman",
"when": "onboardingContext:podmanFailedInstallation",
"state": "failed"
},
{
"id": "podmanSuccessfullySetup",
"title": "Podman successfully setup",
"when": "onboardingContext:podmanIsInstalled",
"state": "completed"
}