为 React Apps 设计和实现 Ant Design Global App Tour。

# Web 开发 # JavaScript # 编程 # React

用户导览是网络应用程序的一项宝贵的可用性功能。它们可让您有效地引导新用户，提供分步指南以帮助他们了解软件。导览还可作为重复任务或高级功能的快速参考。

目标：跨页面导览解决方案

我们的目标是创建一个解决方案，让您能够在 React 应用程序中创建跨多个页面的入门体验。它看起来是这样的：

Ant Design Tour：本地解决方案

Ant Design 提供了 **Tour** 组件来创建交互式导览，但它有一些限制：

它在单个组件内本地工作。

它严重依赖于 React refs，这使得跨多页面的应用程序的灵活性较差。

以下是官方文档中的一个示例，演示了基本的本地实现：

import React, { useRef, useState } from 'react';
import { EllipsisOutlined } from '@ant-design/icons';
import { Button, Divider, Space, Tour } from 'antd';

const App = () => {
  const ref1 = useRef(null);
  const ref2 = useRef(null);
  const ref3 = useRef(null);

  const [open, setOpen] = useState(false);

  const steps = [
    { title: 'Upload File', description: 'Put your files here.', target: () => ref1.current },
    { title: 'Save', description: 'Save your changes.', target: () => ref2.current },
    { title: 'Other Actions', description: 'Click to see other actions.', target: () => ref3.current },
  ];

  return (
    <>

虽然此实现对于单个页面效果很好，但在 React 应用程序中的跨页面游览场景中它就显得不足了。

以下是我们实现的方法：

预步骤，app.jsx，routes.jsx，routesNames.js：

import { RouterProvider } from "react-router-dom";
import AppRouter from "./routes";

export default function App() {
  return ;
}

export const ROUTE_NAMES = {
  HOME: "/",
  ABOUT: "/about",
};

import AppLayout from "./AppLayout";
import { createBrowserRouter } from "react-router-dom";
import { ROUTE_NAMES } from "./routeNames";
import { Home } from "./components/Home";
import { About } from "./components/About";
import { Result } from "antd";
import {TourProvider} from "./TourContext";

const GetItem = (label, key, icon, to, children = [], type) => {
  return !to
    ? {
      key,
      icon,
      children,
      label,
      type,
    }
    : {
      key,
      icon,
      to,
      label,
    };
};

const GetRoute = (path, element, params = null) => {
  return {
    path,
    element,
  };
};

const WithAppLayout = (Component) => {Component};

export const routeItems = [
  GetItem("Home", "home", null, ROUTE_NAMES.HOME),
  GetItem("About", "about", null, ROUTE_NAMES.ABOUT),
];

const AppRouter = createBrowserRouter([
  GetRoute(ROUTE_NAMES.HOME, WithAppLayout()),
  GetRoute(ROUTE_NAMES.ABOUT, WithAppLayout()),
  GetRoute(
    "*",
    
  ),
]);

export default AppRouter;

步骤 1：设置全球旅游背景

我们使用 React Context 来管理旅游的全局状态，包括活动的旅游步骤。

import React, { createContext, useState, useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { APP_TOURS } from "./steps";

const TourContext = createContext();

export const TourProvider = ({ children }) => {
  const [isTourActive, setTourActive] = useState(false);
  const navigate = useNavigate();

  useEffect(() => {
    if (isTourActive) {
      navigate("/home"); // Redirect to the starting point of the tour
    }
  }, [isTourActive, navigate]);

  return (
    
      {children}
    
  );
};

export default TourContext;

第 2 步：定义全球游览步骤

我们不使用 React refs，而是使用 `querySelector` 通过自定义 `data-tour-id` 属性动态获取元素。

const getTourStepElement = (id) => document.querySelector(`[data-tour-id="${id}"]`);

export const APP_TOURS = {
  "/home": [
    { title: "Upload File", description: "Put your files here.", target: () => getTourStepElement("upload") },
    { title: "Save", description: "Save your changes.", target: () => getTourStepElement("save") },
    { type: "navigate", to: "/about", title: "About Us", description: "Learn more about us." },
  ],
  "/about": [
    { title: "About Us", description: "Here's what we are all about.", target: () => getTourStepElement("about") },
  ],
};

步骤 3：创建全球游览组件

该组件动态处理跨页面的导航和步骤。

import React, { useContext } from "react";
import { Tour } from "antd";
import { useNavigate } from "react-router-dom";
import TourContext from "./TourContext";

export const GlobalTour = () => {
  const { isTourActive, steps, setTourActive } = useContext(TourContext);
  const navigate = useNavigate();

  return (
     setTourActive(false)}
      steps={steps}
      onChange={(current) => {
        const step = steps[current];
        if (step.type === "navigate") {
          navigate(step.to);
        }
      }}
    />
  );
};

步骤 4：集成到应用程序布局

游览与布局无缝集成，可从任何页面访问。

import React, { useContext } from "react";
import { Layout, Button } from "antd";
import { Link } from "react-router-dom";
import TourContext from "./TourContext";
import { GlobalTour } from "./GlobalTour";

const { Header, Content, Footer } = Layout;

const AppLayout = ({ children }) => {
  const { setTourActive } = useContext(TourContext);

  return (
    
      
        Home
        About
        
      
      {children}
      © {new Date().getFullYear()} My App
      
    
  );
};

export default AppLayout;

第 5 步：添加步骤游览 ID

由于我们的游览跨越多个页面，我们将为想要在步骤中突出显示的每个组件分配 data-tour-id

import { Button, Space } from "antd";
import { EllipsisOutlined } from "@ant-design/icons";
export const Home = () => {
  return (
    <>

export const About = () => {
  return About;
};

CLIS.CC