建立高階前端擴充套件

要開始建立您的擴充套件，您首先需要一個包含檔案的目錄，這些檔案從擴充套件的原始碼到所需的擴充套件特定檔案不等。此頁面提供有關如何使用更高階的前端設定擴充套件的資訊。

在開始之前，請確保您已安裝最新版本的 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.tw/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 樣式部分。
如果你想為擴充套件設定使用者身份驗證，請參閱身份驗證。