API Composable

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

información

La API Composable está disponible desde la versión >= 4.3

DocSearch incluye una nueva API Composable para renderizar el botón y el modal de búsqueda. Esta API se introdujo para ofrecer un control más explícito sobre dónde y cómo se renderizan los componentes dentro de una página.

Introducción

La Composable API se introdujo para ofrecer mayor flexibilidad en cómo renderizas y usas DocSearch en tu sitio. Con ella, tienes más control sobre dónde, cuándo y cómo quieres agrupar los componentes y renderizarlos.

La API Composable incluye dos nuevos paquetes NPM:

• @docsearch/core - Lógica central compartida para gestionar los diferentes estados de DocSearch

• @docsearch/modal - Los componentes reales utilizados para el Modal de DocSearch

advertencia

Debido a la naturaleza de la composición, esta API solo está disponible en React, no dentro del paquete @docsearch/js.

Primeros pasos

Para comenzar a usar la API Composable, necesitarás instalar estos tres paquetes:

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

O utilizando tu gestor de paquetes preferido

Implementación

La implementación más simple sería la siguiente:

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

información

Los componentes reales DEBEN renderizarse dentro del Provider <DocSearch> para que puedan comunicarse con el estado global.

Esta configuración es ligeramente más compleja al requerir el renderizado de tres componentes diferentes:

• <DocSearch> es el elemento padre que controla y comparte todo el estado con los componentes hijos

• <DocSearchButton /> es el botón que se renderiza y activa la apertura del Modal de DocSearch

• <DocSearchModal /> es el modal principal que contiene el formulario de búsqueda, resultados y Ask AI

Ask AI

Usar Ask AI con la API Composable es muy similar al uso estándar de DocSearch. Solo se requiere la configuración 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>
  );
}

Puedes encontrar más información sobre Ask AI y su configuración en su documentación dedicada.

Avanzado

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

Exportaciones para optimizar bundles

Para ayudar a reducir el tamaño inicial del bundle, el paquete @docsearch/modal también expone exportaciones explícitas:

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

Aquí un ejemplo básico de cómo retrasar la carga del código de DocSearchModal hasta que se haga clic en el botón de búsqueda:

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

Componentes

<DocSearch />

El componente <DocSearch /> del paquete @docsearch/core es el gestor principal de estado para DocSearch. Utiliza React Context para compartir su estado entre componentes anidados.

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

El botón principal de DocSearch que activa el Modal de búsqueda.

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

El modal principal de búsqueda por palabras clave para buscar en tu documentación.

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

Puedes encontrar más documentación sobre propiedades en la página de Referencia de la API DocSearch.