Ant Design Pro路由参数完全指南：从查询参数到状态保持

Ant Design Pro路由参数完全指南：从查询参数到状态保持

【免费下载链接】ant-design-pro 👨🏻‍💻👩🏻‍💻 Use Ant Design like a Pro! 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-pro

你是否在使用Ant Design Pro开发时遇到过路由参数丢失、页面刷新后状态重置的问题？是否想知道如何优雅地在页面间传递数据并保持用户操作状态？本文将系统讲解路由参数管理的核心技巧，帮助你彻底解决这些痛点。读完本文后，你将掌握查询参数的获取与修改、动态路由参数的使用以及页面状态保持的完整方案。

路由配置基础

Ant Design Pro基于Umi框架，路由配置主要通过config/routes.ts文件实现。该文件定义了应用的所有路由规则，包括路径、组件映射、权限控制等关键信息。

// config/routes.ts 中的路由定义示例
{
  name: 'list.table-list',
  icon: 'table',
  path: '/list',
  component: './table-list',
}

在路由配置中，支持两种参数形式：

• 动态参数：使用:id形式定义，如/user/:id
• 通配符：使用*匹配任意路径，如/user/*

查询参数管理

查询参数（Query Parameters）是URL中?后的键值对，如/list?page=1&size=10，常用于分页、筛选等场景。在Ant Design Pro中，推荐使用React Router的useSearchParams钩子来管理查询参数。

获取查询参数

import { useSearchParams } from 'react-router-dom';

const TableList: React.FC = () => {
  // 获取当前查询参数
  const [searchParams] = useSearchParams();
  const currentPage = searchParams.get('page') || '1';
  const pageSize = searchParams.get('size') || '10';
  
  // 使用参数获取数据
  const { data } = useRequest(() => rule({
    page: Number(currentPage),
    size: Number(pageSize),
  }));
  
  // ...
};

修改查询参数

import { useSearchParams } from 'react-router-dom';

const TableList: React.FC = () => {
  const [searchParams, setSearchParams] = useSearchParams();
  
  // 分页变化时更新查询参数
  const handleTableChange = (pagination) => {
    searchParams.set('page', pagination.current.toString());
    searchParams.set('size', pagination.pageSize.toString());
    setSearchParams(searchParams);
  };
  
  return (
    <ProTable
      // ...
      onChange={handleTableChange}
    />
  );
};

动态路由参数

动态路由参数是URL路径的一部分，如/user/:id中的:id。在Ant Design Pro中，需要先在路由配置中定义动态参数，然后通过useParams钩子获取。

配置动态路由

// config/routes.ts
{
  path: '/user/:id',
  name: 'user.detail',
  component: './user/detail',
}

获取动态参数

// src/pages/user/detail/index.tsx
import { useParams } from 'react-router-dom';

const UserDetail: React.FC = () => {
  const { id } = useParams<{ id: string }>();
  
  const { data } = useRequest(() => fetchUserDetail(Number(id)));
  
  return (
    <div>
      <h1>用户详情 #{id}</h1>
      {/* 渲染用户信息 */}
    </div>
  );
};

状态保持策略

页面刷新或跳转后保持状态是常见需求，除了URL参数外，还有以下几种常用方案：

URL参数持久化

适合需要分享或收藏的场景，如列表页的筛选条件。实现方式可参考上文查询参数的使用，结合ProTable组件的onChange事件同步状态到URL。

本地存储

适合用户个性化设置等不需要分享的状态：

// 保存状态到localStorage
const saveState = (state) => {
  localStorage.setItem('table-filters', JSON.stringify(state));
};

// 从localStorage恢复状态
const loadState = () => {
  const saved = localStorage.getItem('table-filters');
  return saved ? JSON.parse(saved) : null;
};

全局状态管理

对于跨组件共享的状态，可使用Umi的useModel或Redux等状态管理方案：

// src/models/table.ts
export default {
  state: {
    filters: {},
  },
  reducers: {
    setFilters(state, { payload }) {
      return { ...state, filters: payload };
    },
  },
};

// 在组件中使用
const { filters } = useModel('table');

高级应用：路由参数与表单联动

在实际开发中，经常需要将表单筛选条件与URL参数同步。以表格列表页为例，实现筛选条件的URL化：

// src/pages/table-list/index.tsx
const TableList: React.FC = () => {
  const [searchParams, setSearchParams] = useSearchParams();
  const [form] = Form.useForm();
  
  // 初始化：从URL参数加载表单值
  useEffect(() => {
    const values: Record<string, any> = {};
    searchParams.forEach((value, key) => {
      if (['name', 'status', 'startTime', 'endTime'].includes(key)) {
        values[key] = value;
      }
    });
    form.setFieldsValue(values);
  }, [searchParams, form]);
  
  // 表单提交时更新URL参数
  const handleSearch = async () => {
    const values = await form.validateFields();
    const params = new URLSearchParams(searchParams);
    
    // 清除旧的筛选参数
    ['name', 'status', 'startTime', 'endTime'].forEach(key => {
      params.delete(key);
    });
    
    // 设置新的筛选参数
    Object.entries(values).forEach(([key, value]) => {
      if (value !== undefined && value !== null && value !== '') {
        params.set(key, value);
      }
    });
    
    // 重置页码
    params.set('page', '1');
    setSearchParams(params);
  };
  
  return (
    <ProTable
      search={false}
      form={form}
      toolBarRender={() => [
        <Button type="primary" onClick={handleSearch}>
          <FormattedMessage id="pages.searchTable.search" defaultMessage="Search" />
        </Button>
      ]}
      // ...
    />
  );
};

最佳实践总结

1. URL优先原则：重要的状态（如分页、关键筛选条件）应保存在URL中，支持页面刷新和分享

2. 参数命名规范：

   • 使用小写字母和下划线
   • 分页参数统一使用page和size
   • 日期范围使用startTime和endTime

3. 性能优化：

   • 使用useMemo缓存参数处理逻辑
   • 避免频繁修改URL导致的不必要渲染

4. 兼容性处理：

   • 为参数提供默认值
   • 处理参数类型转换异常

通过合理使用路由参数，不仅可以提升用户体验（支持前进/后退、页面刷新状态保持），还能实现页面状态的可分享性。Ant Design Pro的路由参数管理方案，结合了React Router的最新特性和Pro组件的最佳实践，帮助开发者轻松应对各种复杂场景。

更多路由配置细节，请参考官方文档：config/routes.ts

【免费下载链接】ant-design-pro 👨🏻‍💻👩🏻‍💻 Use Ant Design like a Pro! 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-pro