ListObjectsCommand

ListObjectsCommand 用于从您的 DID Space 中的指定路径检索对象列表，这些对象可以是文件或目录。它通过选项提供了灵活性，支持扁平化（仅列出直接子项）和递归（列出所有嵌套项）的目录遍历。

此命令对于需要显示文件夹内容、构建文件浏览器或遍历存储中特定部分所有文件的应用程序至关重要。

使用场景

使用 ListObjectsCommand 的常见场景包括：

为用户构建文件浏览器界面，以导航他们存储的文件。
通过首先列出远程对象来同步本地目录与远程目录。
对特定文件夹内的所有文件执行批量操作。
在上传或一系列文件操作后，验证目录的内容。

输入参数

该命令的构造函数接受一个包含以下属性的对象：

key string (default: /) — 您想列出其内容的目录路径。如果省略，则默认为根目录 ('/')。
recursive boolean — 如果设置为 true，该命令将递归地列出给定 key 下的所有对象。如果为 false 或未提供，则执行仅包含直接子项的扁平化列表。
ignoreDirectories boolean — 如果设置为 true，目录将从结果集中排除。此选项仅在 'recursive' 为 false 时有效。

输出

send 方法返回一个 promise，该 promise 会解析为一个包含命令输出的对象。

statusCode number — 响应的 HTTP 状态码。值为 200 表示成功。
data Object[] — 在指定 key 处找到的文件和目录的对象数组。
- 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 结合使用，以高效地获取仅包含文件的列表。