Aller au contenu principal
Version : Stable (v4.x)

API Composable

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

info

L'API Composable est disponible à partir de la version >= 4.3

DocSearch propose une nouvelle API Composable pour afficher le bouton et la modal de recherche. Cette API a été introduite pour offrir un contrôle plus explicite sur l'emplacement et la manière dont les composants sont rendus dans une page.

Introduction​

L'API Composable a été conçue pour offrir plus de flexibilité dans l'affichage et l'utilisation de DocSearch sur votre site. Grâce à elle, vous bénéficiez d'un meilleur contrôle sur l'endroit, le moment et la façon de regrouper les composants et de les afficher.

L'API Composable s'accompagne de deux nouveaux packages NPM :

  • @docsearch/core - Logique centrale partagée pour gérer les différents états de DocSearch

  • @docsearch/modal - Les composants effectifs utilisés pour la modal DocSearch

avertissement

En raison de sa nature composable, cette API est uniquement disponible dans React, et non dans le package @docsearch/js.

Premiers pas​

Pour commencer à utiliser l'API Composable, vous devrez installer les trois packages suivants :

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

Ou avec votre gestionnaire de packages préféré

Mise en œuvre​

L'implémentation la plus simple serait la suivante :

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>
  );
}
info

Les composants effectifs DOIVENT être rendus dans le Provider <DocSearch> pour communiquer avec l'état global.

Cette configuration est légèrement plus complexe car elle implique maintenant trois composants distincts :

  • <DocSearch> est l'élément parent qui contrôle et partage tout l'état avec les composants enfants

  • <DocSearchButton /> est le bouton effectif qui s'affiche et déclenche l'ouverture de la modal DocSearch

  • <DocSearchModal /> est la modal principale contenant le formulaire de recherche, les résultats et Ask AI

Ask AI​

L'utilisation d'Ask AI avec l'API Composable est très similaire à l'utilisation classique de DocSearch. Seule la configuration askAi est nécessaire :

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

Vous trouverez plus d'informations sur Ask AI et sa configuration dans sa documentation dédiée.

Avancé​

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

Exports pour réduire le bundle​

Pour aider à réduire la taille initiale du bundle, le package @docsearch/modal expose également des exports explicites :

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

Voici un exemple basique de chargement différé du code DocSearchModal jusqu'au clic sur le bouton de recherche :

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

Composants​

<DocSearch />​

Le composant <DocSearch /> du package @docsearch/core est le gestionnaire d'état principal de DocSearch. Il utilise le Contexte React pour partager son état à travers les composants imbriqués.

Propriétés​

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 />​

Le bouton de recherche principal de DocSearch qui déclenche l'affichage de la modal.

Propriétés​

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 />​

La modal principale de recherche par mot-clé utilisée pour parcourir votre documentation.

Propriétés​

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;
  // ...
}

Une documentation plus complète des propriétés est disponible dans la référence API de DocSearch.