ice.js 路由系统深度解析：从基础到高级应用

ice.js 路由系统深度解析：从基础到高级应用

ice ICE是阿里巴巴开源的一款企业级中后台搭建工具，提供了丰富的组件库、模板以及可视化拖拽功能，帮助企业快速构建高质量的企业级应用。 项目地址: https://gitcode.com/gh_mirrors/ice1/ice

前言

在现代前端开发中，路由系统是单页应用(SPA)的核心组成部分。作为阿里巴巴开源的 ice.js 框架，它提供了一套强大而灵活的路由解决方案，通过约定优于配置的理念，让开发者能够快速构建高性能的 Web 应用。本文将全面解析 ice.js 的路由系统，帮助开发者掌握其核心概念和最佳实践。

一、ice.js 路由基础

1.1 约定式路由设计

ice.js 采用了约定式路由的设计理念，这意味着开发者无需手动配置路由表，框架会根据项目目录结构自动生成路由信息。具体规则如下：

• 所有路由组件都应放置在 src/pages 目录下
• 每个 .(js|jsx|tsx) 文件对应一个路由地址
• 文件名决定了路由路径的映射关系

这种设计显著减少了样板代码，让开发者可以更专注于业务逻辑的实现。

1.2 路由组件规范

在 ice.js 中，每个页面都是一个路由组件，通过 export default 导出组件实现：

// src/pages/home.tsx
export default function HomePage() {
  return <div>欢迎来到首页</div>;
}

路由组件支持配置页面级信息和数据加载逻辑，是页面开发的入口点。

二、路由类型详解

2.1 基础路由

最简单的路由形式就是直接在 pages 目录下创建文件：

src/pages/
├── index.tsx    -> /
└── about.tsx    -> /about

2.2 嵌套路由

ice.js 通过文件夹结构和布局组件支持嵌套路由：

src/pages/
├── layout.tsx       // 全局布局
└── user/
    ├── layout.tsx   // 用户相关页面布局
    ├── profile.tsx  -> /user/profile
    └── settings.tsx -> /user/settings

嵌套路由的优势在于：

1. 资源并行加载，提升性能
2. 路由跳转时只加载差异部分
3. 便于维护公共布局和逻辑

2.3 动态路由

对于需要参数的路由，可以使用 $ 前缀：

src/pages/
└── user/
    └── $id.tsx  -> /user/:id

在组件内可通过 useParams 获取参数：

import { useParams } from 'ice';

export default function UserDetail() {
  const { id } = useParams();
  // ...
}

2.4 通配路由

创建 $.tsx 文件作为通配路由，通常用于 404 页面：

src/pages/$.tsx  -> 匹配所有未定义路由

2.5 转义路由

默认情况下 index 会被转义为 /，如需保留可使用 []：

src/pages/[index].tsx       -> /index
src/pages/about/[index].tsx -> /about/index

三、布局系统

3.1 布局组件

布局组件是 ice.js 路由系统的强大特性，用于管理页面公共结构：

// src/pages/layout.tsx
import { Outlet } from 'ice';

export default function MainLayout() {
  return (
    <div className="app">
      <Header />
      <main>
        <Outlet />  {/* 子路由渲染位置 */}
      </main>
      <Footer />
    </div>
  );
}

布局组件分为两种级别：

1. 全局布局：位于 pages 根目录，影响所有页面
2. 页面级布局：位于子目录，影响该目录下所有页面

3.2 嵌套布局

布局组件可以多层嵌套，形成完整的页面结构：

全局布局
└── 用户模块布局
    ├── 用户详情页
    └── 用户设置页

这种设计使得公共元素的管理变得非常清晰。

四、路由导航

ice.js 提供多种导航方式：

4.1 编程式导航

import { history } from 'ice';

// 跳转
history.push('/target');
// 替换
history.replace('/target');
// 返回
history.goBack();

4.2 组件内导航

使用 useNavigate Hook：

import { useNavigate } from 'ice';

function MyComponent() {
  const navigate = useNavigate();
  
  return (
    <button onClick={() => navigate('/target')}>
      跳转
    </button>
  );
}

4.3 Link 组件

声明式导航：

import { Link } from 'ice';

<Link to="/about">关于我们</Link>

五、路由信息获取

5.1 获取 location 信息

import { useLocation } from 'ice';

function MyComponent() {
  const location = useLocation();
  // location包含 pathname、search、hash等
}

5.2 处理查询参数

import { useSearchParams } from 'ice';

function SearchPage() {
  const [params, setParams] = useSearchParams();
  
  // 获取参数
  const keyword = params.get('q');
  
  // 设置参数
  const updateParams = () => {
    setParams({ q: 'ice.js' });
  };
}

六、高级配置

6.1 忽略路由文件

通过配置忽略特定文件不被解析为路由：

// ice.config.mts
export default {
  routes: {
    ignoreFiles: [
      '**/components/**', // 忽略components目录
      'utils.tsx'        // 忽略特定文件
    ]
  }
};

6.2 自定义路由

对于特殊需求，可以手动定义路由：

// ice.config.mts
export default {
  routes: {
    defineRoutes: (route) => {
      route('/custom', 'special-page.tsx');
    }
  }
};

七、性能优化实践

ice.js 的路由系统内置了多项性能优化：

1. 并行加载：嵌套路由的资源会并行请求
2. 按需加载：路由跳转时只加载差异部分
3. 智能缓存：合理利用浏览器缓存机制

开发者可以通过以下方式进一步优化：

• 合理拆分路由，避免单个路由过大
• 使用嵌套路由共享公共布局
• 对不常访问的页面配置懒加载

八、小程序特别说明

小程序平台的路由处理略有不同：

1. 需要在 app.tsx 中通过 miniappManifest 显式声明路由顺序
2. 第一项路由将被作为小程序首页
3. 部分高级路由特性（如布局组件）不支持

// src/app.tsx
export const miniappManifest = {
  routes: [
    'index',        // 首页
    'user/profile'  // 用户页
  ]
};

结语

ice.js 的路由系统通过精心的设计，在开发效率和运行性能之间取得了良好的平衡。无论是简单的单层路由还是复杂的嵌套结构，都能优雅地支持。掌握这些路由技巧，将帮助你构建更加健壮和高效的 ice.js 应用。

ice ICE是阿里巴巴开源的一款企业级中后台搭建工具，提供了丰富的组件库、模板以及可视化拖拽功能，帮助企业快速构建高质量的企业级应用。 项目地址: https://gitcode.com/gh_mirrors/ice1/ice