React

Utilisez des composants React préconstruits pour ajouter Docs Embed à votre application React

Pour les projets React, GitBook fournit des composants préconstruits qui rendent l'intégration de votre documentation simple et idiomatique. Les composants gèrent automatiquement la gestion d'état, le contexte et le cycle de vie.

Étapes

1

Installer le package

Ajouter @gitbook/embed à votre projet React :

npm install @gitbook/embed

Pour la référence complète de l'API et le code source, voir le @gitbook/embed package sur GitHub.

2

Importer les composants React

Importer le GitBookProvider et GitBookFrame composants :

import {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";

3

Envelopper votre application avec GitBookProvider

Ajoutez le provider à la racine de votre arbre de composants ou là où vous avez besoin de l'intégration :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <YourAppContent />
    </GitBookProvider>
  );
}

4

Ajouter le composant GitBookFrame

Placez le composant frame là où vous voulez que l'intégration apparaisse :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <div className="app">
        <YourAppContent />
        <GitBookFrame
          visitor={{
            token: 'your-jwt-token', // Optionnel : pour le contenu adaptatif ou l'accès authentifié
            unsignedClaims: { userId: '123' } // Optionnel : claims personnalisés pour des expressions dynamiques
          }}
        />
      </div>
    </GitBookProvider>
  );
}

5

Personnaliser l'intégration

Passez des props de configuration au composant frame :

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    tabs={['assistant', 'docs']}
    greeting={{ title: 'Bienvenue !', subtitle: 'Comment puis-je vous aider ?' }}
    suggestions={['Qu'est-ce que GitBook ?', 'Comment commencer ?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

6

Contrôler l'intégration avec le hook useGitBook

Utilisez le useGitBook hook pour interagir avec l'intégration de manière programmée :

import { useGitBook } from "@gitbook/embed/react";

function HelpButton() {
  const gitbook = useGitBook();
  const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
  
  const handleNavigate = () => {
    const iframe = document.createElement('iframe');
    iframe.src = frameURL;
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('How do I get started?');
  };

  return <button onClick={handleNavigate}>Obtenir de l'aide</button>;
}

7

Rendre l'intégration de manière conditionnelle

Afficher l'intégration seulement lorsque c'est nécessaire :

function App() {
  const [showEmbed, setShowEmbed] = useState(false);

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>Obtenir de l'aide</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

8

Utilisation avec Next.js ou rendu côté serveur

Importez dynamiquement les composants pour éviter les problèmes de SSR :

import dynamic from "next/dynamic";

const GitBookProvider = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookProvider),
  { ssr: false }
);

const GitBookFrame = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookFrame),
  { ssr: false }
);

Props & Configuration

Props de GitBookProvider :

Prop	Type	Requis	Par défaut	Description
siteURL	string	Oui	N/A	L'URL de votre site de documentation GitBook (par ex., https://docs.company.com).
children	ReactNode	Oui	N/A	Composants enfants à rendre à l'intérieur du provider.

Props de GitBookFrame :

Toutes les options de configuration peuvent être passées en props à <GitBookFrame>. Voir la section Configuration ci-dessous pour les options disponibles.

Prop	Type	Requis	Par défaut	Description
className	string	Non	null	Nom de classe CSS à appliquer au conteneur de la frame.
style	object	Non	{}	Styles en ligne à appliquer au conteneur de la frame.
visitor	object	Non	{}	Options d'accès authentifié (voir ci-dessous).

Hook useGitBook :

Retourne une GitBookClient instance avec les méthodes suivantes :

• getFrameURL(options?: { visitor?: {...} }) → string - Obtenir l'URL de l'iframe

• createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de frame

Le client de frame fournit :

• navigateToPage(path: string) → void

• navigateToAssistant() → void

• postUserMessage(message: string) → void

• clearChat() → void

• configure(settings: {...}) → void

• on(event: string, listener: Function) → () => void

Options de configuration

Les options de configuration sont disponibles en tant que props sur <GitBookFrame>:

onglets

Remplacez les onglets affichés. Par défaut, ils correspondent à la configuration de votre site.

• Type: ('assistant' | 'docs')[]

actions

Boutons d'action personnalisés rendus dans la barre latérale à côté des onglets. Chaque bouton d'action déclenche un rappel lorsqu'il est cliqué.

Remarque: Ceci était précédemment nommé buttons. Utilisez actions à la place.

• Type: Array<{ icon: string, label: string, onClick: () => void }>

greeting

Message de bienvenue affiché dans l'onglet Assistant.

• Type: { title: string, subtitle: string }

suggestions

Questions suggérées affichées dans l'écran de bienvenue de l'Assistant.

• Type: string[]

tools

Outils IA personnalisés pour étendre l'Assistant. Voir Création d'outils personnalisés pour les détails.

• Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

visitor (Accès authentifié)

Utilisé pour Contenu adaptatif et Accès authentifié.

• Type: { token?: string, unsignedClaims?: Record<string, unknown> }

Pièges courants

• Ne pas envelopper avec GitBookProvider – L'option GitBookFrame requiert un parent GitBookProvider pour fonctionner.

• Utilisation avec SSR sans import dynamique – Le composant utilise des API du navigateur et doit être importé dynamiquement dans Next.js ou d'autres frameworks SSR.

• siteURL ne correspondant pas à la documentation publiée – Assurez-vous que la siteURL prop correspond exactement à l'URL de votre site de documentation en ligne.

• Appeler useGitBook en dehors du provider – L'option useGitBook le hook doit être utilisé dans un composant qui est enfant de GitBookProvider.

• Plusieurs providers dans l'arbre – Évitez d'imbriquer plusieurs GitBookProvider instances, car cela peut causer des conflits de contexte.

• Utilisation d'anciens noms de composants – Le composant est maintenant GitBookFrame, pas GitBookAssistantFrame.