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 l’état, le contexte et le cycle de vie.

Étapes

Installez le package

Ajoutez @gitbook/embed dans votre projet React :

npm install @gitbook/embed

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

Importez les composants React

Importez GitBookProvider et GitBookFrame components:

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

Encapsulez votre application avec GitBookProvider

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

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

Ajoutez le composant GitBookFrame

Placez le composant frame à l’endroit où vous souhaitez que l’intégration apparaisse :

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

Personnalisez l’intégration

Passez des propriétés de configuration au composant frame :

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    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: 'Contacter le support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

Contrôlez l’intégration avec le hook useGitBook

Utilisez le useGitBook hook pour interagir avec l’intégration par programmation :

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('Comment commencer ?');
  };

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

Affichez l’intégration conditionnellement

N’affichez l’intégration que 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>
  );
}

Utilisation avec Next.js ou le 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 }
);

Propriétés et configuration

Propriétés de GitBookProvider :

Propriété

Tapez

Requis

Par défaut

Description

siteURL

string

Oui

S/O

L’URL de votre site de documentation GitBook (par exemple, https://docs.company.com).

children

ReactNode

Oui

S/O

Composants enfants à rendre dans le provider.

Propriétés de GitBookFrame :

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

Propriété

Tapez

Requis

Par défaut

Description

className

string

Non

null

Nom de classe CSS à appliquer au conteneur du frame.

style

objet

Non

{}

Styles en ligne à appliquer au conteneur du frame.

visitor

objet

Non

{}

Options d’accès authentifié (voir ci-dessous).

Hook useGitBook :

Renvoie 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 sous forme de propriétés sur <GitBookFrame>:

`tabs`

Remplacer les onglets affichés. Par défaut, la configuration de votre site est utilisée.

Tapez: ('assistant' | 'docs')[]

`actions`

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

Remarque: Cela s’appelait auparavant buttons. Utilisez actions .

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

`greeting`

Message de bienvenue affiché dans l’onglet Assistant.

Tapez: { title: string, subtitle: string }

`suggestions`

Questions suggérées affichées sur l’écran d’accueil de l’Assistant.

Tapez: string[]

`trademark`

Afficher ou masquer la marque GitBook dans l’interface intégrée — y compris le pied de page de l’intégration Docs et l’image de marque de l’Assistant.

Tapez: boolean
Par défaut: true

`tools`

Outils d’IA personnalisés pour étendre l’Assistant. Voir Création d’outils personnalisés pour plus de détails.

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

`visitor` (Accès authentifié)

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

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

Pièges courants

Ne pas encapsuler avec GitBookProvider – L’option GitBookFrame nécessite 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 propriété 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 enfant de GitBookProvider.
Plusieurs providers dans l’arbre – Évitez d’imbriquer plusieurs GitBookProvider instances, car cela peut provoquer des conflits de contexte.
Utilisation d’anciens noms de composants – Le composant est maintenant GitBookFrame, et non GitBookAssistantFrame.

Mis à jour il y a 1 mois

Ce contenu vous a-t-il été utile ?