管理資料夾預覽

DID Space 允許您為任何資料夾設定自訂預覽。此功能讓您能夠定義資料夾在應用程式中的呈現方式，將簡單的檔案列表轉變為豐富的互動式體驗，例如畫廊、文件預覽，甚至是迷你應用程式。這是透過資料夾 .meta 目錄中一個特殊的 preview.yml 檔案來管理。

本指南將引導您使用 SDK 管理資料夾預覽的三個主要操作：

設定預覽：在單一操作中建立或更新資料夾的預覽設定，並上傳其相關資產（例如 index.html、CSS、JavaScript 檔案）。
擷取預覽：取得特定資料夾的預覽設定。
刪除預覽：從資料夾中移除自訂預覽。

設定資料夾預覽

若要設定或更新資料夾預覽，您需要使用 PutPreviewObjectCommand。這個強大的指令不僅會寫入 preview.yml 設定，還會上傳預覽所需的所有必要資源檔案（如 HTML、CSS 和 JS）。

輸入參數

key string (required) — 資料夾的路徑。必須以結尾斜線 (/) 結束。
data PreviewTemplate (required) — 包含預覽設定的物件。此物件將被轉換為 YAML 並儲存在 .meta/preview.yml 中。
name string (required) — 預覽的名稱。
description string — 預覽的簡短描述。
entry string (required) — 預覽的進入點檔案，通常是 index.html 檔案。
resources PutObjectCommandInput[] (default: []) — 作為預覽一部分上傳的檔案物件陣列。每個資源的 key 都必須以資料夾的 key 作為前綴。
metadata object (default: {}) — 與預覽關聯的自訂元資料記錄。
hash string — 物件的 IPFS CID v1 雜湊值，用於資料完整性驗證。

範例

以下範例示範如何為名為 my-gallery/ 的資料夾建立一個簡單的 HTML 預覽。我們將隨預覽設定一同上傳一個 index.html 和一個 style.css 檔案。

Set a Folder Preview

import { SpaceClient, PutPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function setFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const folderKey = 'my-gallery/';

  const input = {
    key: folderKey,
    // 這個 'data' 物件將成為 '.meta/preview.yml' 的內容
    data: {
      name: 'My Image Gallery',
      description: 'A simple preview for my image collection.',
      entry: 'index.html', // 預覽的進入點
    },
    // 在同一個指令中上傳預覽資產
    resources: [
      {
        key: `${folderKey}index.html`,
        body: Buffer.from(
          '<!DOCTYPE html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>Welcome to My Gallery</h1></body></html>'
        ),
        contentType: 'text/html',
      },
      {
        key: `${folderKey}style.css`,
        body: Buffer.from('body { background-color: #f0f0f0; color: #333; }'),
        contentType: 'text/css',
      },
    ],
  };

  const command = new PutPreviewObjectCommand(input);
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully set folder preview!');
  } else {
    console.error('Failed to set folder preview:', output.statusMessage);
  }
}

setFolderPreview();

此指令執行後，my-gallery/ 資料夾將會有一個 .meta/preview.yml 檔案，並包含 index.html 和 style.css。

擷取資料夾預覽

若要取得現有資料夾預覽的設定，請使用 GetPreviewObjectCommand。此指令會讀取 .meta/preview.yml 檔案並回傳其解析後的內容。

輸入參數

key string (required) — 資料夾的路徑。必須以結尾斜線 (/) 結束。

輸出

指令的輸出在 data 屬性中包含已解析的 PreviewTemplate 物件。

data PreviewTemplate — .meta/preview.yml 檔案的解析後內容。

範例

Get a Folder Preview

import { SpaceClient, GetPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function getFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new GetPreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Preview configuration:', output.data);
  } else {
    console.error('Failed to get folder preview:', output.statusMessage);
  }
}

getFolderPreview();

範例回應

如果指令成功，output.data 看起來會像這樣：

Example Response

{
  "name": "My Image Gallery",
  "description": "A simple preview for my image collection.",
  "entry": "index.html"
}

刪除資料夾預覽

如果您想移除自訂預覽並將資料夾還原為其預設外觀，請使用 DeletePreviewObjectCommand。此指令會刪除 .meta/preview.yml 檔案，但不會影響資料夾中的任何其他檔案，包括您可能已上傳的資源檔案。

輸入參數

key string (required) — 資料夾的路徑。必須以結尾斜線 (/) 結束。

範例

Delete a Folder Preview

import { SpaceClient, DeletePreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function deleteFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new DeletePreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully deleted folder preview!');
  } else {
    console.error('Failed to delete folder preview:', output.statusMessage);
  }
}

deleteFolderPreview();

透過使用這三個指令，您可以完全管理自訂資料夾預覽，以便在您的 DID Space 驅動的應用程式中創造更豐富、更具吸引力的使用者體驗。