Expo-Router v2带对象参数的类型化路由实现咨询

一、路由文件命名规则 #

如果你的参数是查询参数（即通过?key=value拼接在URL后的参数，如示例中的id/description等），路由文件直接按正常页面命名即可。比如目标页面是home，就创建app/home.tsx，不需要用[slug].tsx这类动态路径命名（动态路径命名适用于路径参数，比如/user/123中的123）。

二、自定义路由参数类型实现类型校验 #

Expo Router默认的自动类型生成只覆盖动态路径参数，复杂查询参数需要手动扩展类型。在项目中创建类型声明文件（如app/types/router.d.ts），扩展Expo Router的内置类型：

// app/types/router.d.ts
import 'expo-router';

// 定义所有页面的参数类型映射
type RouteParams = {
  home: {
    id: string | number;
    description: string;
    age: string | number;
    name: string;
  };
  // 可添加其他页面的参数类型，比如：
  // user: { userId: string; role: 'admin' | 'user' }
};

// 扩展Expo Router的Link和Router类型
declare module 'expo-router' {
  interface LinkProps<T extends string = string> {
    href: {
      pathname: T;
      params: RouteParams[T];
    };
  }

  interface Router {
    push<T extends string>(href: {
      pathname: T;
      params: RouteParams[T];
    }): void;
  }
}

三、类型化的router.push和<Link>使用 #

配置完类型后，router.push和<Link>的href会自动触发类型校验，参数缺失或类型不匹配时TypeScript会直接报错：

import { router, Link } from 'expo-router';

// 正确用法：参数完全匹配类型
router.push({
  pathname: 'home',
  params: {
    id: 1,
    description: '测试描述',
    age: 25,
    name: '张三'
  }
});

// <Link>组件同样支持类型校验
<Link 
  href={{
    pathname: 'home',
    params: { id: 2, description: '', age: 30, name: '李四' }
  }}
>
  跳转到Home页
</Link>

四、目标页面接收并处理参数 #

useLocalSearchParams返回的参数默认都是字符串类型（因为URL查询参数本质是字符串），需要手动转换为对应类型，同时可以用类型断言约束参数结构：

// app/home.tsx
import { useLocalSearchParams } from 'expo-router';

// 定义页面参数类型（和RouteParams中的home字段一致）
type HomeParams = {
  id: string;
  description: string;
  age: string;
  name: string;
};

const Home = () => {
  // 获取带类型约束的查询参数
  const params = useLocalSearchParams<HomeParams>();

  // 转换为业务所需的类型
  const id = Number(params.id);
  const age = Number(params.age);
  const description = params.description || '';
  const name = params.name || '';

  return (
    <>
      <p>ID: {id}</p>
      <p>姓名: {name}</p>
      <p>年龄: {age}</p>
      <p>描述: {description}</p>
    </>
  );
};

export default Home;

关键说明 #

• 路径参数 vs 查询参数：如果参数是单个标识（如用户ID），推荐用动态路径参数（[id].tsx）；如果是多个字段组成的对象，用查询参数更灵活。
• 类型一致性：确保RouteParams中的类型和页面接收时的转换逻辑一致，避免类型错误。

内容的提问来源于stack exchange，提问作者Guilherme