フォルダプレビューの管理

DID Spaceでは、任意のフォルダにカスタムプレビューを設定できます。この機能により、アプリケーションでフォルダがどのように表示されるかを定義でき、単純なファイルリストを、ギャラリー、ドキュメントプレビュー、あるいはミニアプリケーションのようなリッチでインタラクティブな体験に変えることができます。これは、フォルダの .meta ディレクトリ内にある特別な preview.yml ファイルによって管理されます。

このガイドでは、SDKを使用してフォルダプレビューを管理するための3つの主要な操作について説明します。

プレビューの設定: フォルダのプレビュー設定を作成または更新し、関連するアセット（例: 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: []) — プレビューの一部としてアップロードするファイルオブジェクトの配列。各リソースキーは、フォルダのキーで始まる必要があります。
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) — フォルダへのパス。末尾にスラッシュ (/) が必要です。

出力

コマンドの出力には、解析済みの PreviewTemplate オブジェクトが data プロパティに含まれています。

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();

これら3つのコマンドを使用することで、カスタムフォルダプレビューを完全に管理し、DID Spaceを利用したアプリケーションでよりリッチで魅力的なユーザーエクスペリエンスを作成できます。