用户游览对于 web 应用程序来说是一项非常宝贵的可用性功能。它们可以让您有效地吸引新用户，并提供分步指南来帮助他们了解软件。导览还可以作为重复任务或高级功能的快速参考。
目标：跨页面游览解决方案
我们的目标是创建一个解决方案，让您能够在 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 ( <> <button type="primary" onclick={() => setopen(true)}>begin tour</button> <divider /> <space> <button ref={ref1}>upload</button> <button ref={ref2} type="primary">save</button> <button ref={ref3} icon={<ellipsisoutlined />} /> </space> <tour open={open} onclose={() => setopen(false)} steps={steps} /> </> ); }; export default app;
虽然此实现对于单页面效果很好，但在 react 应用程序中跨页面游览的场景中却表现不佳。
我们的实现方式如下：
前置步骤，app.JSx，routes.jsx，routesnames.js :
import { routerprovider } from "react-router-dom"; import approuter from "./routes"; export default function app() { return <routerprovider router={approuter} />; }
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) => <tourprovider><applayout>{component}</applayout></tourprovider>; 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(<home />)), getroute(route_names.about, withapplayout(<about />)), getroute( "*", <result status="404" title="404" subtitle="sorry, the page you visited does not exist." /> ), ]); 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 ( <tourcontext.provider value={{ istouractive, settouractive, steps: app_tours }}> {children} </tourcontext.provider> ); }; export default tourcontext;
第 2 步：定义全球巡演步骤
我们使用 queryselector 通过自定义 data-tour-id 属性动态获取元素，而不是 react refs。
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 ( <tour open={istouractive} onclose={() => 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 ( <layout> <header> <link to="/home">home</link> <link to="/about">about</link> <button onclick={() => settouractive(true)}>start tour</button> </header> <content>{children}</content> <footer>© {new date().getfullyear()} my app</footer> <globaltour /> </layout> ); }; export default applayout;
第 5 步：添加步骤游览 id
由于我们的游览跨越多个页面，我们将为我们想要在步骤中突出显示的每个组件分配 data-tour-id
import { button, space } from "antd"; import { ellipsisoutlined } from "@ant-design/icons"; export const home = () => { return ( <> <button data-tour-id="upload" >upload</button> <button data-tour-id="save" type="primary"> save </button> <button data-tour-id="actions" icon={<ellipsisoutlined />} /> </> ); };
export const About = () => { return <div data-tour-id="about">About</div>; };
