入门

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"
}

标题、描述和媒体​

启用​

步骤​

Id​

标题、描述和媒体​

命令​

完成事件​

内容​

组件​

何时​

状态​

标题、描述和媒体

启用

步骤

Id

标题、描述和媒体

命令

完成事件

内容

组件

何时

状态