コンポーザブル API

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。 エラーを見つけましたか？ 問題を報告 →

情報

コンポーザブル API はバージョン >= 4.3 から利用可能です

DocSearch には、検索ボタンとモーダルをレンダリングする新しいコンポーザブル API が追加されました。この API は、 コンポーネントをページ内のどこにどのようにレンダリングするかを明示的に制御できるようにするために導入されました。

はじめに

コンポーザブル API は、ウェブサイト上で DocSearch をレンダリング・使用する方法に柔軟性を持たせるために導入されました。 これにより、コンポーネントをどの場所で、いつ、どのようにバンドルしてレンダリングするかをより細かく制御できます。

コンポーザブル API に伴い、2つの新しい NPM パッケージが追加されました：

• @docsearch/core - DocSearch のさまざまな状態を管理する共有コアロジック

• @docsearch/modal - DocSearch モーダルで使用される実際のコンポーネント

警告

コンポーザビリティの性質上、この API は React 環境内でのみ利用可能であり、@docsearch/js パッケージ内では利用できません。

はじめに

コンポーザブル API を使用するには、以下の3つのパッケージをインストールする必要があります：

npm

npm install @docsearch/core @docsearch/modal @docsearch/css

yarn

yarn add @docsearch/core @docsearch/modal @docsearch/css

pnpm

pnpm add @docsearch/core @docsearch/modal @docsearch/css

bun

bun add @docsearch/core @docsearch/modal @docsearch/css

またはお好みのパッケージマネージャーを使用して

実装方法

最もシンプルな実装は次のようになります：

import { DocSearch } from '@docsearch/core';
import { DocSearchButton, DocSearchModal } from '@docsearch/modal';
import '@docsearch/css/style.css';

export function Search() {
  return (
    <DocSearch>
      <DocSearchButton />
      <DocSearchModal
        indexName="YOUR_INDEX_NAME"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
      />
    </DocSearch>
  );
}

情報

実際のコンポーネントはグローバル状態と通信するために、必ず <DocSearch> プロバイダ内でレンダリングする必要があります。

このセットアップでは、以下の3つの異なるコンポーネントをレンダリングする必要があります：

• <DocSearch> は親要素で、すべての状態を子コンポーネントと制御・共有します

• <DocSearchButton /> は実際にレンダリングされるボタン要素で、DocSearch モーダルを開くトリガーとなります

• <DocSearchModal /> は検索フォーム、検索結果、Ask AI を含むメインモーダルです

Ask AI

コンポーザブル API で Ask AI を使用する方法は、通常の DocSearch の使用方法とよく似ています。必要なのは askAi 設定のみです：

import { DocSearch } from '@docsearch/core';
import { DocSearchButton, DocSearchModal } from '@docsearch/modal';
import '@docsearch/css/style.css';

export function Search() {
  return (
    <DocSearch>
      <DocSearchButton />
      <DocSearchModal
        indexName="YOUR_INDEX_NAME"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        // With just a simple assistant ID
        askAi="YOUR_ALGOLIA_ASSISTANT_ID"
        // Or with a more complex configuration
        askAi={{
          indexName: 'YOUR_MARKDOWN_INDEX', // Optional: use a different index for Ask AI
          apiKey: 'YOUR_SEARCH_API_KEY',     // Optional: use a different API key for Ask AI
          appId: 'YOUR_APP_ID',              // Optional: use a different App ID for Ask AI
          assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
          searchParameters: {
            facetFilters: ['language:en', 'version:1.0.0'], // Optional: filter Ask AI context
          },
        }}
      />
    </DocSearch>
  );
}

Ask AI の詳細と設定方法については、専用ドキュメントでご確認いただけます。

上級者向け

export default function AdvancedSearch(): JSX.Element {
  return (
    <DocSearch
      keyboardShortcuts={{
        '/': false, // Disable opening/closing the DocSearchModal with '/' key
      }}
    >
      <DocSearchButton
        translations={{ buttonText: 'Advanced Search' }} // Change the displayed text on the DocSearchButton
      />
      <DocSearchModal
        indexName="YOUR_INDEX_NAME"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        askAi={{ // Enable Ask AI
          assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
          searchParameters: {
            facetFilters: ['language:en'],
          },
        }}
        portalContainer='#algolia-search' // Custom element that the DocSearchModal will be rendered into
      />
    </DocSearch>
  );
}

バンドルサイズ削減用エクスポート

初期バンドルサイズの削減を支援するため、@docsearch/modal パッケージでは明示的なファイルエクスポートも提供しています：

import { DocSearchButton } from '@docsearch/modal/button';
import { DocSearchModal } from '@docsearch/modal/modal';

以下は、検索ボタンがクリックされるまで DocSearchModal のコード読み込みを遅延させる基本的な例です：

import { DocSearch } from '@docsearch/core';
import { DocSearchButton } from '@docsearch/modal/button';
import type { DocSearchModal as DocSearchModalType } from '@docsearch/modal/modal';
import { useState } from 'react';

let DocSearchModal: typeof DocSearchModalType | null = null;

async function importDocSearchModalIfNeeded() {
  if (DocSearchModal) {
    return;
  }

  const { DocSearchModal: Modal } = await import('@docsearch/modal/modal');

  DocSearchModal = Modal;
}

export default function DynamicModal() {
  const [modalLoaded, setModalLoaded] = useState(false);

  const loadModal = () => {
    importDocSearchModalIfNeeded().then(() => {
      setModalLoaded(true);
    });
  };

  return (
    <DocSearch>
      <DocSearchButton onClick={loadModal} />
      {modalLoaded && DocSearchModal && (
        <DocSearchModal
          indexName="YOUR_INDEX_NAME"
          appId="YOUR_APP_ID"
          apiKey="YOUR_SEARCH_API_KEY"
        />
      )}
    </DocSearch>
  );
}

コンポーネント

<DocSearch />

@docsearch/core パッケージの <DocSearch /> コンポーネントは、DocSearch 全体の主要な状態管理ハンドラです。 React Context を利用して、ネストされたコンポーネント間で状態を共有します。

Props

interface DocSearchProps {
  // React children to be rendered within the DocSearch Provider
  children: Array<JSX.Element | null> | JSX.Element | React.ReactNode | null;
  // Theme to be set enabling style changes for `light` or `dark` themes
  theme?: 'light' | 'dark';
  // Initial starting query for keyword search
  initialQuery?: string;
  // Manage supported keyboard shortcuts for opening/closing the DocSearch Modal
  keyboardShortcuts?: {
    'Ctrl/Cmd+K': boolean,
    '/': boolean,
  };
}

<DocSearchButton />

DocSearch モーダルを起動する主要な検索ボタンです。

Props

interface DocSearchButtonProps {
  // Optional callback for when the button is clicked. The original click event is passed.
  onClick?: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
  // Translation strings specific to the button.
  translations: {
    buttonText?: string;
    buttonAriaLabel?: string;
  };
}

<DocSearchModal />

ドキュメントを検索するための主要なキーワード検索モーダルです。

Props

interface DocSearchModalProps {
  /**
   * Algolia application id used by the search client.
   */
  appId: string;
  /**
   * Public api key with search permissions for the index.
   */
  apiKey: string;
  /**
   * Name of the algolia index to query.
   *
   * @deprecated `indexName` will be removed in a future version. Please use `indices` property going forward.
   */
  indexName?: string;
  /**
   * List of indices and _optional_ searchParameters to be used for search.
   *
   * @see {@link https://docsearch.algolia.com/docs/api#indices}
   */
  indices?: Array<DocSearchIndex | string>;
  /**
   * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
   */
  askAi?: DocSearchAskAi | string;
  // ...
}

プロパティの詳細なドキュメントは DocSearch API リファレンス ページでご覧いただけます。