管理文件夹预览

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 文件。

设置文件夹预览

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 文件的解析后内容。

示例

获取文件夹预览

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 将如下所示：

示例响应

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

删除文件夹预览

如果您想移除自定义预览并将文件夹恢复到其默认外观，请使用 DeletePreviewObjectCommand。此命令会删除 .meta/preview.yml 文件，但不会影响文件夹中的任何其他文件，包括您可能已上传的资源文件。

输入参数

key string (required) — 文件夹的路径。必须以斜杠（/）结尾。

示例

删除文件夹预览

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 驱动的应用程序中创造更丰富、更具吸引力的用户体验。