Tour

Visite guidée avec mise en évidence par projecteur et navigation par étapes.

Importation

import { Tour } from 'asterui'

Exemples

Tour basique

Une visite guidée simple avec plusieurs étapes.

import { Tour, Button, Input, Card } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const searchRef = useRef<HTMLInputElement>(null);
  const profileRef = useRef<HTMLButtonElement>(null);
  const settingsRef = useRef<HTMLButtonElement>(null);
  
  const steps = [
    {
      target: searchRef,
      title: 'Search',
      description: 'Use the search bar to find content quickly.',
      placement: 'bottom' as const,
    },
    {
      target: profileRef,
      title: 'Profile',
      description: 'Click here to view and edit your profile.',
      placement: 'bottom' as const,
    },
    {
      target: settingsRef,
      title: 'Settings',
      description: 'Customize your experience in settings.',
      placement: 'left' as const,
    },
  ];
  
  return (
      <Card className="p-4">
        <div className="flex gap-4 items-center mb-4">
          <Input ref={searchRef} placeholder="Search..." className="flex-1" />
          <Button ref={profileRef}>Profile</Button>
          <Button ref={settingsRef}>Settings</Button>
        </div>
        <Button color="primary" onClick={() => setOpen(true)}>
          Start Tour
        </Button>
        <Tour
          open={open}
          steps={steps}
          onClose={() => setOpen(false)}
          onFinish={() => setOpen(false)}
        />
      </Card>
    )
}

export default App

Tour sans cible

Les étapes sans cible apparaissent centrées à l'écran.

import { Tour, Button } from 'asterui'
import { useState } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  
  const steps = [
    {
      title: 'Welcome!',
      description: 'This tour will guide you through the main features.',
    },
    {
      title: 'Getting Started',
      description: 'Follow along to learn how to use this application.',
    },
    {
      title: 'All Done!',
      description: 'You are ready to start using the app.',
    },
  ];
  
  return (
      <Button color="primary" onClick={() => setOpen(true)}>
        Start Intro
      </Button>
      <Tour
        open={open}
        steps={steps}
        onClose={() => setOpen(false)}
        type="primary"
      />
    )
}

export default App

Avec image de couverture

Ajoutez des images ou du contenu personnalisé au-dessus du titre de l'étape.

import { Tour, Button } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const buttonRef = useRef<HTMLButtonElement>(null);
  
  const steps = [
    {
      target: buttonRef,
      title: 'New Feature',
      description: 'Check out this amazing new feature we just added!',
      cover: (
        <img
          src="https://picsum.photos/320/160"
          alt="Feature preview"
          className="w-full h-40 object-cover"
        />
      ),
      placement: 'right' as const,
    },
  ];
  
  return (
      <Button ref={buttonRef} color="primary" onClick={() => setOpen(true)}>
        View Feature
      </Button>
      <Tour
        open={open}
        steps={steps}
        onClose={() => setOpen(false)}
        showSkip={false}
      />
    )
}

export default App

Placements

Contrôlez l'emplacement du popover par rapport à la cible.

Target

import { Tour, Button, Space } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const targetRef = useRef<HTMLDivElement>(null);
  const placements = ['top', 'right', 'bottom', 'left'] as const;
  const [placementIndex, setPlacementIndex] = useState(0);
  
  const steps = [
    {
      target: targetRef,
      title: `Placement: ${placements[placementIndex]}`,
      description: 'The popover can appear on any side of the target.',
      placement: placements[placementIndex],
    },
  ];
  
  return (
      <div className="flex flex-col items-center gap-4">
        <div
          ref={targetRef}
          className="w-24 h-24 bg-primary text-primary-content flex items-center justify-center rounded-lg"
        >
          Target
        </div>
        <Space>
          <Button onClick={() => setPlacementIndex((i) => (i + 1) % 4)}>
            Change Placement
          </Button>
          <Button color="primary" onClick={() => setOpen(true)}>
            Show Tour
          </Button>
        </Space>
        <Tour
          open={open}
          steps={steps}
          onClose={() => setOpen(false)}
          showIndicators={false}
        />
      </div>
    )
}

export default App

API

`Tour`

Propriété	Description	Type	Défaut
`open`	Si le tour est visible	`boolean`	`false`
`steps`	Configuration des étapes du tour	`TourStepProps[]`	`-`
`current`	Indice de l’étape actuelle (contrôlé)	`number`	`-`
`onChange`	Callback lorsque l’étape change	`(current: number) => void`	`-`
`onClose`	Callback lorsque le tour se ferme	`() => void`	`-`
`onFinish`	Callback lorsque le tour se termine	`() => void`	`-`
`mask`	Afficher le masque de superposition avec projecteur	`boolean`	`true`
`type`	Type de style de bouton	`'default' \| 'primary'`	`'default'`
`gap`	Écart entre le projecteur et la cible [rayon, décalage] ou nombre	`number \| [number, number]`	`8`
`showSkip`	Afficher le bouton ignorer	`boolean`	`true`
`showIndicators`	Afficher les indicateurs d’étape	`boolean`	`true`
`closeOnMaskClick`	Fermer au clic sur le masque	`boolean`	`true`
`closeOnEscape`	Fermer avec la touche Échap	`boolean`	`true`
`scrollIntoView`	Faire défiler la cible dans la vue	`boolean`	`true`
`prevButtonText`	Texte pour le bouton précédent	`React.ReactNode`	`'Previous'`
`nextButtonText`	Texte pour le bouton suivant	`React.ReactNode`	`'Next'`
`finishButtonText`	Texte pour le bouton terminer	`React.ReactNode`	`'Finish'`
`skipButtonText`	Texte pour le bouton ignorer	`React.ReactNode`	`'Skip'`
`zIndex`	Z-index pour la superposition du tour	`number`	`1000`

`TourStepProps`

Propriété	Description	Type	Défaut
`target`	Référence de l’élément cible ou fonction retournant l’élément	`RefObject<HTMLElement> \| (() => HTMLElement \| null) \| null`	`-`
`title`	Titre de l’étape	`React.ReactNode`	`-`
`description`	Description de l’étape	`React.ReactNode`	`-`
`cover`	Image de couverture ou contenu au-dessus du titre	`React.ReactNode`	`-`
`placement`	Placement du popover par rapport à la cible	`TourPlacement`	`'bottom'`
`className`	Classe personnalisée pour le popover de l’étape	`string`	`-`
`onOpen`	Appelé lorsque l’étape devient active	`() => void`	`-`
`onClose`	Appelé lors de la sortie de l’étape	`() => void`	`-`

Accessibilité

La boîte de dialogue du tour a role=“dialog” et aria-modal=“true”
Les touches fléchées permettent de naviguer entre les étapes
La touche Échap ferme le tour
Les indicateurs d’étape sont accessibles au clavier
Le focus est piégé dans le tour lorsqu’il est ouvert