ListObjectsCommand

ListObjectsCommand 用於從您 DID Space 中的指定路徑擷取物件列表，這些物件可以是檔案或目錄。它透過選項提供靈活性，可進行平面（僅列出直接子項目）和遞迴（列出所有巢狀項目）的目錄遍歷。

對於需要顯示資料夾內容、建立檔案瀏覽器或迭代儲存空間特定部分中所有檔案的應用程式而言，此命令至關重要。

使用案例

使用 ListObjectsCommand 的常見情境包括：

建立檔案總管介面，供使用者瀏覽其儲存的檔案。
透過先列出遠端物件來同步本機目錄與遠端目錄。
對特定資料夾中的所有檔案執行批次操作。
在上傳或一系列檔案操作後，驗證目錄的內容。

輸入參數

此命令的建構函式接受一個包含以下屬性的物件：

key string (default: /) — 您想列出其內容的目錄路徑。若省略，則預設為根目錄（'/'）。
recursive boolean — 若設定為 true，此命令將遞迴地列出給定路徑下的所有物件。若為 false 或未提供，則執行平面列表，僅列出直接的子項目。
ignoreDirectories boolean — 若設定為 true，結果集中將排除目錄。此選項僅在 'recursive' 為 false 時有效。

輸出

send 方法會回傳一個 promise，其解析值為一個包含該命令輸出的物件。

statusCode number — 回應的 HTTP 狀態碼。值為 200 表示成功。
data Object[] — 一個物件陣列，代表在指定路徑下找到的檔案和目錄。
- key string — 物件的完整路徑和名稱。
- type 'object' | 'directory' — 項目的類型。
- size number — 物件的大小（以位元組為單位）。對於目錄，此值通常為 0。
- lastModified string — 一個 ISO 8601 格式的日期字串，表示物件的最後修改時間。

範例回應（成功）

範例成功回應

{
  "statusCode": 200,
  "data": [
    {
      "key": "/photos/summer/beach.jpg",
      "type": "object",
      "size": 2048576,
      "lastModified": "2023-10-27T10:00:00.000Z"
    },
    {
      "key": "/photos/summer/mountains/",
      "type": "directory",
      "size": 0,
      "lastModified": "2023-10-26T15:30:00.000Z"
    }
  ]
}

程式碼範例

此範例示範如何初始化 SpaceClient 並使用 ListObjectsCommand 來列出目錄的內容。

範例

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

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

async function listMyFiles() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/', // 指定要列出的目錄
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully listed objects:');
    if (output.data.length > 0) {
      output.data.forEach((item) => {
        console.log(`- [${item.type}] ${item.key} (Size: ${item.size} bytes)`);
      });
    } else {
      console.log('The directory is empty.');
    }
  } else {
    console.error('Failed to list objects:', output);
  }
}

listMyFiles();

遞迴列表

若要列出 /shared-documents/ 中的所有檔案和子目錄，請將 recursive 選項設定為 true。

遞迴列表

async function listAllFilesRecursively() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/',
    recursive: true,
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('All nested objects:');
    output.data.forEach((item) => {
      console.log(`- ${item.key}`);
    });
  } else {
    console.error('Recursive listing failed:', output);
  }
}

listAllFilesRecursively();

最佳實踐與常見模式

效能：對於大型目錄，除非必要，否則應避免遞迴列表。平面列表速度明顯更快，因為它擷取的資料較少。
建立檔案樹：若要建構 UI 檔案樹，您可以先對根層級進行非遞迴呼叫。然後，當使用者展開每個子目錄時，再對其進行後續的非遞迴呼叫。或者，如果物件總數可控，也可以透過單次遞迴呼叫一次性擷取整個樹狀結構的狀態。
篩選檔案：如果您只需要處理特定目錄中的檔案（而非子目錄），可將非遞迴呼叫與 ignoreDirectories: true 結合使用，以高效地取得純檔案列表。