创建高级前端扩展

要开始创建您的扩展，您首先需要一个包含文件的目录，这些文件从扩展的源代码到所需的扩展特定文件不等。此页面提供有关如何使用更高级的前端设置扩展的信息。

在开始之前，请确保您已安装最新版本的 Docker Desktop。

扩展文件夹结构

创建新扩展的最快速方法是运行 docker extension init my-extension，如快速入门中所述。这将在 my-extension 中创建一个新目录，其中包含一个功能齐全的扩展。

提示
docker extension init 生成基于 React 的扩展。但您仍然可以使用它作为您自己的扩展的起点，并使用任何其他前端框架，如 Vue、Angular、Svelte 等，甚至可以使用原生 Javascript。

虽然您可以从空目录或 react-extension 示例文件夹开始，但强烈建议您从 docker extension init 命令开始，并根据需要进行更改。

.
├── Dockerfile # (1)
├── ui # (2)
│   ├── public # (3)
│   │   └── index.html
│   ├── src # (4)
│   │   ├── App.tsx
│   │   ├── index.tsx
│   ├── package.json
│   └── package-lock.lock
│   ├── tsconfig.json
├── docker.svg # (5)
└── metadata.json # (6)

包含构建扩展并在 Docker Desktop 中运行扩展所需的一切。
包含您的前端应用程序源代码的高级文件夹。
未编译或动态生成的资产存储在此处。这些可以是静态资产，如徽标或 robots.txt 文件。
src 或源文件夹包含所有 React 组件、外部 CSS 文件和动态资产，这些资产被引入组件文件。
在 Docker Desktop 仪表板的左侧菜单中显示的图标。
一个文件，它提供有关扩展的信息，例如名称、描述和版本。

调整 Dockerfile

注意
使用 docker extension init 时，它会创建一个 Dockerfile，其中已经包含 React 扩展所需的內容。

创建扩展后，您需要配置 Dockerfile 来构建扩展并配置用于填充市场中扩展卡的标签。以下是一个 React 扩展的 Dockerfile 示例

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM node:18.9-alpine3.15 AS client-builder
WORKDIR /ui
# cache packages in layer
COPY ui/package.json /ui/package.json
COPY ui/package-lock.json /ui/package-lock.json
RUN --mount=type=cache,target=/usr/src/app/.npm \
    npm set cache /usr/src/app/.npm && \
    npm ci
# install
COPY ui /ui
RUN npm run build

FROM alpine
LABEL org.opencontainers.image.title="My extension" \
    org.opencontainers.image.description="Your Desktop Extension Description" \
    org.opencontainers.image.vendor="Awesome Inc." \
    com.docker.desktop.extension.api.version="0.3.3" \
    com.docker.desktop.extension.icon="https://docker.net.cn/wp-content/uploads/2022/03/Moby-logo.png" \
    com.docker.extension.screenshots="" \
    com.docker.extension.detailed-description="" \
    com.docker.extension.publisher-url="" \
    com.docker.extension.additional-urls="" \
    com.docker.extension.changelog=""

COPY metadata.json .
COPY docker.svg .
COPY --from=client-builder /ui/build ui

注意
在示例 Dockerfile 中，您可以看到镜像标签 com.docker.desktop.extension.icon 设置为图标 URL。扩展市场在安装扩展之前会显示此图标。Dockerfile 还包括 COPY docker.svg . 用于将图标文件复制到镜像中。此第二个图标文件用于在安装扩展后在仪表板中显示扩展 UI。

重要
我们还没有为 Vue 提供可用的 Dockerfile。填写表格并告诉我们您是否想要 Vue 的 Dockerfile。

重要
我们还没有为 Angular 提供可用的 Dockerfile。填写表格并告诉我们您是否想要 Angular 的 Dockerfile。

重要
我们还没有为 Svelte 提供可用的 Dockerfile。填写表格并告诉我们您是否想要 Svelte 的 Dockerfile。

配置元数据文件

为了在 Docker Desktop 中为您的扩展添加选项卡，您必须在扩展目录的根目录中的 metadata.json 文件中进行配置。

{
  "icon": "docker.svg",
  "ui": {
    "dashboard-tab": {
      "title": "UI Extension",
      "root": "/ui",
      "src": "index.html"
    }
  }
}

title 属性是在 Docker Desktop 仪表板的左侧菜单中显示的扩展名称。root 属性是扩展容器文件系统中前端应用程序的路径，系统使用它将应用程序部署到主机上。src 属性是 root 文件夹内前端应用程序的 HTML 入口点的路径。

有关 metadata.json 中 ui 部分的更多信息，请参阅元数据。

构建扩展并安装它

现在您已经配置了扩展，您需要构建 Docker Desktop 将用于安装它的扩展镜像。

docker build --tag=awesome-inc/my-extension:latest .

这将构建一个标记为 awesome-inc/my-extension:latest 的镜像，您可以运行 docker inspect awesome-inc/my-extension:latest 查看有关它的更多详细信息。

最后，您可以安装扩展并查看它是否出现在 Docker Desktop 仪表板中。

docker extension install awesome-inc/my-extension:latest

使用扩展 API 客户端

要使用扩展 API 并使用 Docker Desktop 执行操作，扩展必须首先导入 @docker/extension-api-client 库。要安装它，请运行以下命令

npm install @docker/extension-api-client

然后调用 createDockerDesktopClient 函数以创建用于调用扩展 API 的客户端对象。

import { createDockerDesktopClient } from '@docker/extension-api-client';

const ddClient = createDockerDesktopClient();

在使用 Typescript 时，您还可以将 @docker/extension-api-client-types 作为开发依赖项安装。这将为您提供扩展 API 的类型定义以及 IDE 中的自动完成。

npm install @docker/extension-api-client-types --save-dev

例如，您可以使用 docker.cli.exec 函数通过 docker ps --all 命令获取所有容器的列表，并在表格中显示结果。

将 ui/src/App.tsx 文件替换为以下代码


// ui/src/App.tsx
import React, { useEffect } from 'react';
import {
  Paper,
  Stack,
  Table,
  TableBody,
  TableCell,
  TableContainer,
  TableHead,
  TableRow,
  Typography
} from "@mui/material";
import { createDockerDesktopClient } from "@docker/extension-api-client";

//obtain docker destkop extension client
const ddClient = createDockerDesktopClient();

export function App() {
  const [containers, setContainers] = React.useState<any[]>([]);

  useEffect(() => {
    // List all containers
    ddClient.docker.cli.exec('ps', ['--all', '--format', '"{{json .}}"']).then((result) => {
      // result.parseJsonLines() parses the output of the command into an array of objects
      setContainers(result.parseJsonLines());
    });
  }, []);

  return (
    <Stack>
      <Typography data-testid="heading" variant="h3" role="title">
        Container list
      </Typography>
      <Typography
      data-testid="subheading"
      variant="body1"
      color="text.secondary"
      sx={{ mt: 2 }}
    >
      Simple list of containers using Docker Extensions SDK.
      </Typography>
      <TableContainer sx={{mt:2}}>
        <Table>
          <TableHead>
            <TableRow>
              <TableCell>Container id</TableCell>
              <TableCell>Image</TableCell>
              <TableCell>Command</TableCell>
              <TableCell>Created</TableCell>
              <TableCell>Status</TableCell>
            </TableRow>
          </TableHead>
          <TableBody>
            {containers.map((container) => (
              <TableRow
                key={container.ID}
                sx={{ '&:last-child td, &:last-child th': { border: 0 } }}
              >
                <TableCell>{container.ID}</TableCell>
                <TableCell>{container.Image}</TableCell>
                <TableCell>{container.Command}</TableCell>
                <TableCell>{container.CreatedAt}</TableCell>
                <TableCell>{container.Status}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </TableContainer>
    </Stack>
  );
}

重要
我们还没有为 Vue 提供示例。填写表格并告诉我们您是否想要 Vue 的示例。

重要
我们还没有 Angular 的示例。填写表格并让我们知道你是否需要一个 Angular 的示例。

重要
我们还没有 Svelte 的示例。填写表格并让我们知道你是否需要一个 Svelte 的示例。

针对前端代码实施的策略

扩展 UI 代码在独立的 Electron 会话中渲染，并且没有初始化 node.js 环境，也没有直接访问 Electron API。

这是为了限制对整体 Docker Dashboard 的潜在意外副作用。

扩展 UI 代码不能执行特权任务，例如对系统进行更改或生成子进程，除非使用扩展框架提供的 SDK API。扩展 UI 代码也可以通过扩展 SDK API 与 Docker Desktop 进行交互，例如导航到 Dashboard 中的各个位置。

扩展 UI 部分彼此隔离，每个扩展的扩展 UI 代码都在其自己的会话中运行。扩展不能访问其他扩展的会话数据。

localStorage 是浏览器 Web 存储机制之一。它允许用户将数据以键值对的形式保存在浏览器中，以便以后使用。localStorage 在浏览器（扩展窗格）关闭时不会清除数据。这使得它成为在导航出扩展到 Docker Desktop 的其他部分时持久化数据的理想选择。

如果你的扩展使用 localStorage 来存储数据，在 Docker Desktop 中运行的其他扩展无法访问你的扩展的本地存储。即使在 Docker Desktop 停止或重新启动后，扩展的本地存储也会保留。当扩展升级时，其本地存储会保留，而当它被卸载时，其本地存储会被完全删除。

重新构建扩展并更新它

由于你修改了扩展的代码，因此你必须重新构建扩展。

$ docker build --tag=awesome-inc/my-extension:latest .

构建完成后，你需要更新它。

$ docker extension update awesome-inc/my-extension:latest

现在你可以在 Docker Desktop Dashboard 的容器选项卡中看到后端服务在运行，并在你需要调试时查看日志。

提示
你可以启用热重载，避免每次修改代码后都重新构建扩展。

下一步是什么？

为你的扩展添加后端。
学习如何测试和调试你的扩展。
学习如何为你的扩展设置 CI。
详细了解扩展的架构。
有关构建 UI 的更多信息和指南，请参阅设计和 UI 样式部分。
如果你想为扩展设置用户身份验证，请参阅身份验证。