Next.js 与 Chakra UI：构建优雅的未保存更改导航防护

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Next.js 与 Chakra UI：构建优雅的未保存更改导航防护

2025-11-18

浏览次数：次

返回列表

next.js 与 chakra ui：构建优雅的未保存更改导航防护

本文详细介绍了如何在 Next.js 应用中，结合 Chakra UI 实现一个健壮的页面导航防护机制。当用户在包含未保存更改的表单页面尝试离开时，系统将通过一个自定义 React Hook 拦截路由跳转，并弹出一个 Chakra UI 警告对话框，询问用户是否确认离开。该方案通过巧妙地利用 Next.js 路由事件和浏览器历史 API，确保用户在确认前不会丢失数据，并能准确地导航到其最初选择的路由。

在现代 Web 应用中，用户体验至关重要。当用户在表单中输入数据但尚未保存时，意外的页面导航可能导致数据丢失，从而带来糟糕的用户体验。为了解决这一问题，我们需要一种机制来检测未保存的更改，并在用户尝试离开页面时提供确认提示。本教程将指导您如何在 Next.js 应用中，利用 Chakra UI 的 AlertDialog 组件和自定义 Hook 来实现这一功能。

核心挑战：Next.js 路由拦截与用户确认

Next.js 提供了 router.events 来监听路由变化，例如 routeChangeStart。然而，仅仅监听这个事件并不能直接“阻止”路由跳转。当 routeChangeStart 事件触发时，Next.js 已经开始处理导航，并且通常会立即更新浏览器的 URL。为了真正阻止导航并等待用户确认，我们需要更高级的策略。

主要的挑战点在于：

停止路由跳转：在 routeChangeStart 发生后，如何有效地中断 Next.js 的路由进程。
保留目标路由：在用户确认离开后，如何让应用继续导航到用户最初点击的目标路由。
URL 同步：防止在对话框显示期间，浏览器地址栏短暂显示目标路由，然后又跳回当前路由。

解决方案：自定义 useN*igationObserver Hook

为了优雅地解决上述挑战，我们将创建一个名为 useN*igationObserver 的自定义 React Hook。这个 Hook 将负责监听路由事件、阻止默认导航行为、保存目标路由，并提供一个回调函数来允许组件在用户确认后恢复导航。

ChatCut

AI视频剪辑工具

1086 查看详情 ChatCut

useN*igationObserver Hook 实现

import { useRouter } from "next/router";
import { useCallback, useEffect, useRef } from "react";

// 用于欺骗 Next.js 路由的假错误信息
const errorMessage = "Please ignore this error.";

// 抛出假错误以中断 Next.js 路由
const throwFakeErrorToFoolNextRouter = () => {
  // eslint-disable-next-line no-throw-literal
  throw errorMessage;
};

// 拦截并阻止处理我们的假错误，防止其被报告到控制台
const rejectionHandler = (event: PromiseRejectionEvent) => {
  if (event.reason === errorMessage) {
    event.preventDefault();
  }
};

interface Props {
  shouldStopN*igation: boolean; // 是否应该阻止导航
  onN*igate: () => void; // 当导航被阻止时调用的回调函数（用于打开对话框）
}

const useN*igationObserver = ({ shouldStopN*igation, onN*igate }: Props) => {
  const router = useRouter();
  const currentPath = router.asPath; // 当前页面的完整路径
  const nextPath = useRef(""); // 存储用户尝试导航到的目标路径
  const n*igationConfirmed = useRef(false); // 标记用户是否已确认导航

  // 中断路由事件并抛出假错误
  const killRouterEvent = useCallback(() => {
    // 触发一个路由错误事件，Next.js 会捕获并停止导航
    router.events.emit("routeChangeError", "", "", { shallow: false });
    throwFakeErrorToFoolNextRouter(); // 抛出错误以强制中断
  }, [router]);

  useEffect(() => {
    // 每次组件重新渲染时重置确认状态
    n*igationConfirmed.current = false;

    const onRouteChange = (url: string) => {
      // 如果当前路径与目标路径不同，且导航未被确认
      if (currentPath !== url) {
        // 立即将浏览器历史记录的 URL 恢复到当前路径
        // 这是为了防止在对话框显示之前，URL 短暂地变为目标路径
        window.history.pushState(null, "", router.basePath + currentPath);
      }

      // 如果有未保存的更改 (shouldStopN*igation 为 true)
      // 且目标路径与当前路径不同，且导航未被用户确认
      if (
        shouldStopN*igation &&
        url !== currentPath &&
        !n*igationConfirmed.current
      ) {
        nextPath.current = url.replace(router.basePath, ""); // 存储目标路径
        onN*igate(); // 调用回调函数，通常用于打开确认对话框
        killRouterEvent(); // 阻止 Next.js 导航
      }
    };

    // 监听路由开始变化事件
    router.events.on("routeChangeStart", onRouteChange);
    // 监听未处理的 Promise 拒绝，用于捕获并阻止我们的假错误被报告
    window.addEventListener("unhandledrejection", rejectionHandler);

    return () => {
      // 组件卸载时移除事件监听器
      router.events.off("routeChangeStart", onRouteChange);
      window.removeEventListener("unhandledrejection", rejectionHandler);
    };
  }, [
    currentPath,
    killRouterEvent,
    onN*igate,
    router.basePath,
    router.events,
    shouldStopN*igation,
  ]);

  // 用户确认导航后调用此函数
  const confirmN*igation = () => {
    n*igationConfirmed.current = true; // 标记导航已确认
    router.push(nextPath.current); // 手动导航到之前存储的目标路径
  };

  return confirmN*igation;
};

export { useN*igationObserver };

Hook 工作原理详解

shouldStopN*igation: 这是一个布尔值，表示当前页面是否有未保存的更改，决定是否需要阻止导航。
onN*igate: 当导航被阻止时，此回调函数会被调用。它通常用于触发 Chakra UI 的 AlertDialog 显示。
router.events.on("routeChangeStart", onRouteChange): 这是核心监听器。当用户点击链接或使用浏览器前进/后退按钮时，Next.js 会触发此事件。
window.history.pushState(null, "", router.basePath + currentPath): 关键一步！在 routeChangeStart 触发后，Next.js 会立即更新浏览器 URL。为了防止用户在看到对话框之前看到 URL 变化，我们立即将 URL 恢复到当前页面的路径。
killRouterEvent():
- router.events.emit("routeChangeError", "", "", { shallow: false });：通过手动触发一个路由错误事件，我们告诉 Next.js 路由系统发生了一个错误，从而有效地阻止了当前的路由跳转。
- throwFakeErrorToFoolNextRouter()：为了确保路由彻底中断，我们抛出一个自定义的错误。这个错误并不会真正导致应用崩溃，因为它会被 rejectionHandler 捕获并阻止。
rejectionHandler: 这是一个全局的 unhandledrejection 事件监听器，它的作用是捕获我们抛出的“假错误”，并通过 event.preventDefault() 阻止浏览器将这个错误报告到控制台，从而保持控制台的清洁。
nextPath.current: 当导航被阻止时，目标 URL 会被存储在这个 useRef 中。
confirmN*igation(): 这个函数由 Hook 返回，并在用户在对话框中选择“是”时被调用。它会将 n*igationConfirmed.current 设置为 true，然后使用 router.push(nextPath.current) 手动导航到之前存储的目标路径。

在组件中集成导航防护

现在，我们将在一个 Next.js 页面组件中集成 useN*igationObserver Hook 和 Chakra UI 的 AlertDialog。

假设我们有一个 RecordEditing 组件，用于编辑记录。

import { useState, useEffect } from "react";
import {
  Box,
  Grid,
  GridItem,
  Input,
  Flex,
  Button,
  useColorModeValue,
  useDisclosure,
  AlertDialog,
  AlertDialogBody,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogContent,
  AlertDialogOverlay,
} from "@chakra-ui/react";
import { useRouter } from "next/router";
import isDeepEqual from "deep-equal"; // 用于深度比较对象
import { useN*igationObserver } from "@/hooks/useN*igationObserver"; // 导入自定义 Hook

// 假设的类型定义和辅助函数
interface IRecordEditData {
  title: string;
  url: string;
  username: string;
  password?: string;
}
interface IRecordEditingProps {
  type: "new" | "edit";
  record: IRecordEditData;
  user: { id: string };
}
const postMethod = async (url: string, data: any) => { /* ... */ };
const updateMethod = async (url: string, data: any) => { /* ... */ };
const showMsg = (message: string, options: { type: string }) => { /* ... */ };
const TopN* = ({ title, type }: { title: string; type: string }) => { /* ... */ return <Box>{title}</Box>; };
const PasswordEditor = ({ password, setPassword }: { password: string; setPassword: (p: string) => void }) => { /* ... */ return <Input value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />; };


const RecordEditing: React.FC<IRecordEditingProps> = ({
  type,
  record,
  user,
}) => {
  const [recordObj, setRecordObj] = useState<IRecordEditData>(record);
  const [password, setPassword] = useState<string>(record.password || "");
  const [isDirty, setIsDirty] = useState<boolean>(false); // 标记是否有未保存的更改

  // 初始记录状态，用于比较
  const defaultRecord = { ...record, password };

  const title = type === "new" ? "New Record" : "Edit Record";
  const router = useRouter();
  const { recordId } = router.query;
  const buttonBg = useColorModeValue("#dbdbdb", "#2a2c38");

  // Chakra UI useDisclosure Hook 管理对话框状态
  const { isOpen, onOpen, onClose } = useDisclosure();

  // 使用自定义导航观察者 Hook
  const n*igate = useN*igationObserver({
    shouldStopN*igation: isDirty, // 只有当 isDirty 为 true 时才阻止导航
    onN*igate: () => onOpen(), // 导航被阻止时，打开 Chakra UI 对话框
  });

  // 检查输入是否与初始记录不同，并更新 isDirty 状态
  const setDirtyInputs = () => {
    if (!isDeepEqual(defaultRecord, { ...recordObj, password })) {
      setIsDirty(true);
    } else {
      setIsDirty(false);
    }
  };

  // 处理输入变化
  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setRecordObj((prevState) => ({
      ...prevState,
      [e.target.id]: e.target.value,
    }));
  };

  // 在 recordObj 或 password 变化时检查脏状态
  useEffect(() => {
    setDirtyInputs();
  }, [recordObj, password]);


  // 处理表单提交
  const handleSubmit = async () => {
    setIsDirty(false); // 提交后清除脏状态
    try {
      if (type === "new") {
        await postMethod(`/api/user/${user.id}/records`, {
          ...recordObj,
          password,
        });
        showMsg("Record s*ed", { type: "success" });
      } else {
        await updateMethod(`/api/user/${user.id}/records/${recordId}`, {
          ...recordObj,
          password,
        });
        showMsg("Record updated", { type: "success" });
      }
      router.push("/"); // 保存成功后导航到主页
    } catch (error) {
      showMsg("Something went wrong", { type: "error" });
    }
  };

  return (
    <Box py="60px">
      <TopN* title={title} type="backAndTitle" />
      <Box>
        <Grid gridTemplateColumns="3fr 6fr" gap="10px" py="10px">
          {/* 示例输入字段 */}
          <GridItem w="100%" h="10">
            <Flex align="center" h="100%">
              Title
            </Flex>
          </GridItem>
          <GridItem w="100%" h="10">
            <Input
              id="title"
              value={recordObj.title}
              placeholder="Record title"
              onChange={handleInputChange}
              _focusVisible={{ border: "2px solid", borderColor: "teal.200" }}
            />
          </GridItem>
          <GridItem w="100%" h="10">
            <Flex align="center" h="100%">
              Url
            </Flex>
          </GridItem>
          <GridItem w="100%" h="10">
            <Input
              id="url"
              value={recordObj.url}
              placeholder="Website url (optional)"
              onChange={handleInputChange}
              _focusVisible={{ border: "2px solid", borderColor: "teal.200" }}
            />
          </GridItem>
          <GridItem w="100%" h="10">
            <Flex align="center" h="100%">
              Username
            </Flex>
          </GridItem>
          <GridItem w="100%" h="10">
            <Input
              id="username"
              value={recordObj.username}
              placeholder="Username or email"
              onChange={handleInputChange}
              _focusVisible={{ border: "2px solid", borderColor: "teal.200" }}
            />
          </GridItem>
        </Grid>
      </Box>
      <PasswordEditor password={password} setPassword={setPassword} />
      <Box mt="20px">
        <Button
          type="submit"
          w="100%"
          background={buttonBg}
          _focus={{ background: buttonBg }}
          onClick={handleSubmit}
        >
          S*e Record
        </Button>
      </Box>

      {/* Chakra UI AlertDialog for uns*ed changes */}
      <AlertDialog
        motionPreset="slideInBottom"
        leastDestructiveRef={undefined} // 可以指向 "No" 按钮的 ref
        onClose={onClose}
        isOpen={isOpen}
        isCentered
      >
        <AlertDialogOverlay />
        <AlertDialogContent>
          <AlertDialogHeader>
            您确定要离开此页面吗？
          </AlertDialogHeader>
          <AlertDialogBody>
            您有未保存的更改。如果您离开此页面，所有未保存的更改都将丢失！
          </AlertDialogBody>
          <AlertDialogFooter>
            <Button onClick={onClose}>
              否 (留在当前页)
            </Button>
            <Button
              onClick={() => {
                onClose(); // 关闭对话框
                n*igate(); // 调用 Hook 返回的函数，继续导航到目标页
              }}
              colorScheme="red"
              ml={3}
            >
              是 (离开此页)
            </Button>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </Box>
  );
};

export default RecordEditing;

组件集成详解

isDirty 状态: useState(false) 用于跟踪表单数据是否与初始加载的数据不同。
defaultRecord: 在组件挂载时，将初始的 record 和 password 组合成一个 defaultRecord 对象。后续通过 isDeepEqual 库将其与当前表单状态进行深度比较，以准确判断 isDirty 状态。
useDisclosure(): Chakra UI 提供的 Hook，用于管理 AlertDialog 的 isOpen、onOpen 和 onClose 状态。
useN*igationObserver 的使用:
- shouldStopN*igation: isDirty：我们将 isDirty 状态传递给 Hook，只有当 isDirty 为 true 时，Hook 才会阻止导航。
- onN*igate: () => onOpen()：当 Hook 阻止导航时，它会调用 onN*igate 回调，我们在这里触发 AlertDialog 的打开。
- const n*igate = useN*igationObserver(...)：Hook 返回一个 n*igate 函数，当用户确认离开页面时，我们将调用此函数来恢复路由跳转。
setDirtyInputs(): 此函数负责比较 defaultRecord 和当前 recordObj 及 password 的状态，并更新 isDirty。
useEffect 监听脏状态: 通过 useEffect 监听 recordObj 和 password 的变化，并调用 setDirtyInputs 来实时更新 isDirty 状态。
handleSubmit(): 当用户点击“保存”按钮并成功提交表单后，需要将 isDirty 状态重置为 false，因为此时更改已经保存。
AlertDialog 交互:
- “否 (留在当前页)”按钮：直接调用 onClose() 关闭对话框，用户停留在当前页面。
- “是 (离开此页)”按钮：首先调用 onClose() 关闭对话框，然后调用 n*igate() 函数。这个 n*igate 函数就是 useN*igationObserver Hook 返回的 confirmN*igation，它会执行 router.push(nextPath.current)，将用户导航到他们最初尝试前往的页面。

注意事项与最佳实践

deep-equal 库: 在判断对象是否“脏”时，简单地比较引用是不够的。deep-equal 这样的库可以帮助您进行深层比较，确保所有嵌套属性都被考虑在内。
用户体验: 确保 AlertDialog 的提示信息清晰明了，让用户清楚了解离开页面将带来的后果。
错误处理: useN*igationObserver 中的“假错误”机制是一种高级的路由拦截技巧。理解其工作原理（routeChangeError 事件和 unhandledrejection 监听）对于调试和维护至关重要。
表单提交: 在表单成功提交后，务必将 isDirty 状态重置为 false，否则用户保存后仍然会收到离开页面的提示。
leastDestructiveRef: 在 AlertDialog 中，leastDestructiveRef 通常指向一个在对话框打开时获得焦点的元素，通常是“取消”或“否”按钮，以增强可访问性。在我们的例子中，由于没有特定的取消按钮，可以暂时设置为 undefined 或指向“否”按钮的 useRef。

总结

通过结合 Next.js 的路由事件、浏览器历史 API 以及 Chakra UI 的模态框组件，我们成功构建了一个强大且用户友好的导航防护系统。useN*igationObserver Hook 提供了一个可复用的解决方案，能够优雅地处理未保存更改的场景，从而显著提升 Next.js 应用的用户体验。这种模式不仅适用于表单页面，也可以扩展到任何需要用户确认才能离开的复杂交互场景。

以上就是Next.js 与 Chakra UI：构建优雅的未保存更改导航防护的详细内容，更多请关注其它相关文章！

# 海外营销推广平平台 # 跳转 # 抛出 # 这是 # 它会 # 这一 # 并在 # 汕头湖南网站优化推广 # 仙游营销推广 # 自定义 # 内蒙古网站优化推广 # 株洲网站建设公司名录 # 山西网站建设和讯动力 # 德州营销推广策划费用 # 北京首页关键词排名 # 什么是网站优化方案 # 石家庄网上推广网站 # win # word # html # js # go # 浏览器 # 回调函数 # ai # 路由 # react # 数据丢失 # 表单提交 # red # gate # 表单 # 对话框 # 回调