Skip to content

Commit 09bfdca

Browse files
author
qiqiboy
committed
feat: add useAnimatedRoutes
1 parent 2ff39cf commit 09bfdca

10 files changed

+667
-424
lines changed

‎README.md‎

Lines changed: 122 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,25 @@
11
# react-animated-router
22

3-
react 路由切换动画，支持嵌套路由 (nested routers)和动态路由（dynamic routers）。
3+
react 路由切换动画，支持嵌套路由 (nested routers)和动态路由（dynamic routers），对于`[email protected]`的路由嵌套有较好的支持，开箱即用！
44

5-
> 当前版本要求`react-router-dom`为`v6`版本，如果您还在使用`v4`或`v5`，请查看 [[email protected]](https://github.com/qiqiboy/react-animated-router/tree/0.2.4)
5+
> 当前版本要求`react-router-dom`为`v6`版本，如果您还在使用`v4`或`v5`，请查看安装 [[email protected]](https://github.com/qiqiboy/react-animated-router/tree/0.2.4)
6+
7+
<!-- vim-markdown-toc GFM -->
8+
9+
- [安装](#安装)
10+
- [如何使用](#如何使用)
11+
- [`AnimatedRouter`组件模式调用](#animatedrouter组件模式调用)
12+
- [`useAnimatedRoutes` Hooks 模式调用](#useanimatedroutes-hooks-模式调用)
13+
- [参数说明](#参数说明)
14+
- [自定义动画](#自定义动画)
15+
- [FAQ](#faq)
16+
17+
<!-- vim-markdown-toc -->
618

719
### 安装
820

921
```bash
10-
npm install react-animated-router --save
22+
npm install react-animated-router@latest --save
1123
```
1224

1325
你可以直接通过`npm/yarn`安装，依赖包里带一个左右滑入滑出效果的`animate.css`，如果要使用该效果，需要在项目中一并引入。
@@ -30,34 +42,76 @@ import 'react-animated-router/animate.css'; //导入默认的切换动画样式
3042
// 自己项目中的AnimatedRouter模块
3143
import 'react-animated-router/animate.css'; //导入样式文件
3244

33-
export { default } from 'react-animated-router'; //直接将react-animated-route作为默认导出
45+
export { default, useAnimatedRoutes } from 'react-animated-router'; //直接将react-animated-router作为默认导出
3446
```
3547

3648
然后就可以直接引用该文件来使用 AnimatedRouter 了，不必每次都引入`animate.css`。
3749

3850
### 如何使用
3951

52+
`react-animated-router`提供了与`Routes`和`useRoutes`类似的组件和 hooks 两种用法：
53+
54+
#### `AnimatedRouter`组件模式调用
55+
4056
`AnimatedRouter`是一个标准的 React 组件，它可以给一组`Route`组件增加动画切换效果，将它放入你的项目中，然后在需要支持动画的地方，使用`AnimatedRouter`替换你的`Routes`组件即可。
4157

42-
**`AnimatedRouter` 对于嵌套的路由声明也有效！**
58+
```javascript
59+
import React, { Component } from 'react';
60+
import { render } from 'react-dom';
61+
import { BrowserRouter, Routes, Route } from 'react-router-dom';
62+
import { useAnimatedRoutes } from 'react-animated-router';
63+
import 'react-animated-router/animate.css'; //导入默认的切换动画样式，如果需要其它切换样式，可以导入自己的动画样式定义文件
64+
65+
import Login from 'modules/Login';
66+
import Signup from 'modules/Signup';
67+
import NestLayout from 'modules/NestLayout';
68+
import Nested from 'modules/Nested';
69+
70+
function App() {
71+
/** 假如你的代码如此，则可直接使用最下方代码代替，即直接使用 AnimatedRouter 替换掉 Routes
72+
* return (
73+
* <Routes>
74+
* <Route path="login" element={<Login />} />
75+
* <Route path="signup" element={<Signup />} />
76+
* <Route path="nested" element={<NestLayout />}>
77+
* <Route path="1" element={<Nested id="1" />} />
78+
* <Route path="2" element={<Nested id="2" />} />
79+
* </Route>
80+
* </Routes>
81+
* );
82+
**/
83+
84+
return (
85+
<AnimatedRouter>
86+
<Route path="login" element={<Login />} />
87+
<Route path="signup" element={<Signup />} />
88+
<Route path="nested" element={<NestLayout />}>
89+
<Route path="1" element={<Nested id="1" />} />
90+
<Route path="2" element={<Nested id="2" />} />
91+
</Route>
92+
</AnimatedRouter>
93+
);
94+
}
95+
96+
render(
97+
<BrowserRouter>
98+
<App />
99+
</BrowserRouter>,
100+
document.querySelector('#root')
101+
);
102+
```
103+
104+
#### `useAnimatedRoutes` Hooks 模式调用
43105

44-
| 属性 | 类型 | 默认值 | 描述 |
45-
| :-----------: | :-------------------: | :---------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46-
| location | `Location` 对象，可选 | 当前页面地址 | 等同于`Routes`的同名属性 |
47-
| prefix | 字符串，可选 | `animated-router` | 应用到 CSSTransition 组件的 classNames 前缀。如果要在同一个项目中使用不同的动画，可以通过设置前缀来定义不同的动画。关于如何自定义动画，请查看下方说明 |
48-
| timeout | 数字，可选 | 无 | 动画持续时间（毫秒），可以不传，默认为监听 transitionend 时间来判断动画结束。如果有动画异常，可以尝试设置该值，需要注意的是，该值应该与动画样式中定义的过渡时间一致 |
49-
| className | 字符串，可选 | 无 | 如果传入 className 则会添加到动画节点所在容器节点上 |
50-
| transitionKey | 字符串，可选 | 无 | 该属性用于标识路由动画节点，默认情况下为变换的路由所对应的`pathname`地址；`AnimatedRouter`已经智能处理了路由嵌套的情形，一般无需特定制定该参数。如果在嵌套路由场景中，要控制子路由变换时，父级路由的动画方式，可以传递该参数 |
51-
| component | 布尔，可选 | 'div' | AnimatedRouter 默认会 render 一个 div 节点，你可以通过该字段修改 render 的节点类型，例如，`component="section"`将会 render `<section>`节点。在 react v16+中，可以传入 `null` 来避免渲染该节点。 |
52-
| appear | 布尔，可选 | false | [文档：appear](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-appear)：是否启用组件首次挂载动画（启用的话将会触发 enter 进场动画） |
53-
| enter | 布尔，可选 | true | [文档：enter](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-enter)：是否启用进场动画 |
54-
| exit | 布尔，可选 | true | [文档：exit](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-exit)：是否启用离场动画 |
106+
> **请注意，名字是`useAnimatedRoutes`，不是`useAnimatedRouter`!!**
107+
108+
你可以将项目中的`useRoutes`使用`useAnimatedRoutes`代替，就可以给页面切换带来动画效果！
55109

56110
```javascript
57111
import React, { Component } from 'react';
58112
import { render } from 'react-dom';
59113
import { BrowserRouter, Routes, Route } from 'react-router-dom';
60-
import AnimatedRouter from 'react-animated-router'; //导入我们的的AnimatedRouter组件
114+
import { useAnimatedRoutes } from 'react-animated-router'; //导入我们的的AnimatedRouter组件
61115
import 'react-animated-router/animate.css'; //导入默认的切换动画样式，如果需要其它切换样式，可以导入自己的动画样式定义文件
62116

63117
import Login from 'modules/Login';
@@ -66,31 +120,18 @@ import NestLayout from 'modules/NestLayout';
66120
import Nested from 'modules/Nested';
67121

68122
function App() {
69-
render() {
70-
/** 假如你的代码如此，则可直接使用最下方代码代替，即直接使用 AnimatedRouter 替换掉 Routes
71-
* return (
72-
* <Routes>
73-
* <Route path="login"` element={<Login />} />
74-
* <Route path="signup" element={<Signup />} />
75-
* <Route path="nested" element={<NestLayout />}>
76-
* <Route path="1" element={<Nested id="1" />} />
77-
* <Route path="2" element={<Nested id="2" />} />
78-
* </Route>
79-
* </Routes>
80-
* );
81-
**/
82-
83-
return (
84-
<AnimatedRouter>
85-
<Route path="login"` element={<Login />} />
86-
<Route path="signup" element={<Signup />} />
87-
<Route path="nested" element={<NestLayout />}>
88-
<Route path="1" element={<Nested id="1" />} />
89-
<Route path="2" element={<Nested id="2" />} />
90-
</Route>
91-
</AnimatedRouter>
92-
);
93-
}
123+
return useAnimatedRoutes([
124+
{ path: 'login', element: <Login /> },
125+
{ path: 'signup', element: <Signup /> },
126+
{
127+
path: 'nested',
128+
element: <NestLayout />,
129+
children: [
130+
{ path: '1', element: <Nested id="1" /> },
131+
{ path: '2', element: <Nested id="2" /> }
132+
]
133+
}
134+
]);
94135
}
95136

96137
render(
@@ -101,6 +142,34 @@ render(
101142
);
102143
```
103144

145+
#### 参数说明
146+
147+
```typescript
148+
// TransitionActions 为 react-transition-group 定义
149+
interface AnimatedRouterProps extends TransitionActions {
150+
className?: string;
151+
transitionKey?: string | number;
152+
timeout?: number;
153+
prefix?: string;
154+
component?: React.ElementType | null;
155+
location?: Partial<Location> | string;
156+
}
157+
```
158+
159+
主要参数说明：
160+
161+
| 属性 | 类型 | 默认值 | 描述 |
162+
| :-----------: | :-----------------------: | :---------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163+
| prefix | `string`，可选 | `animated-router` | 应用到 CSSTransition 组件的 classNames 前缀。如果要在同一个项目中使用不同的动画，可以通过设置前缀来定义不同的动画。关于如何自定义动画，请查看下方说明 |
164+
| timeout | `number`，可选 | 无 | 动画持续时间（毫秒），可以不传，默认为监听 transitionend 时间来判断动画结束。如果有动画异常，可以尝试设置该值，需要注意的是，该值应该与动画样式中定义的过渡时间一致 |
165+
| className | `string`，可选 | 无 | 如果传入 className 则会添加到动画节点所在容器节点上 |
166+
| transitionKey | `string`，可选 | 无 | 开始该属性用于标识路由动画节点，默认情况下为变换的路由所对应的`pathname`地址；`AnimatedRouter`已经智能处理了路由嵌套的情形，一般无需特定制定该参数。如果在嵌套路由场景中，要控制子路由变换时，父级路由的动画方式，可以传递该参数 |
167+
| component | `boolean`，可选 | 'div' | AnimatedRouter 默认会 render 一个 div 节点，你可以通过该字段修改 render 的节点类型，例如，`component="section"`将会 render `<section>`节点。在 react v16+中，可以传入 `null` 来避免渲染该节点。 |
168+
| appear | `boolean`，可选 | false | [文档：appear](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-appear)：是否启用组件首次挂载动画（启用的话将会触发 enter 进场动画） |
169+
| enter | `boolean`，可选 | true | [文档：enter](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-enter)：是否启用进场动画 |
170+
| exit | `boolean`，可选 | true | [文档：exit](http://reactcommunity.org/react-transition-group/transition-group#TransitionGroup-prop-exit)：是否启用离场动画 |
171+
| location | `Location` `string`，可选 | 当前页面地址 | 等同于`Routes`的同名属性，一般无需指定，除非你要渲染匹配与当前页面地址不一样路由 |
172+
104173
### 自定义动画
105174

106175
如果不希望使用左右滑入动画，则可以自定义自己的路由动画。可以将默认的 animate.scss(css) 复制进自己的项目，然后修改不同阶段的样式值即可。
@@ -123,5 +192,15 @@ render(
123192

124193
### FAQ
125194

126-
- **Q: 动画执行异常？**
195+
- **Q: 动画执行异常？**
127196
A: 可以尝试设置 timeout 属性，并保持与动画样式中定义的过渡时间一致（默认的 animate.scss 中为 300）
197+
198+
- **Q: 控制台有警告？**
199+
A: 如果使用路由嵌套，开发环境下在控制台可能会出现如下警告，这不会对实际路由渲染有任何影响。如果有您有更好地实现可以消除该警告，请`PR`
200+
201+
```bash
202+
router.ts:11 You rendered descendant <Routes> (or called `useRoutes()`) at
203+
"/invoices/" (under <Route path="">) but the parent route path has no trailing "*".
204+
This means if you navigate deeper,the parent won't match anymore and
205+
therefore the child routes will never render.
206+
```

‎dist/AnimatedRouter.d.ts‎

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,7 @@
1-
import React, { ReactType } from 'react';
2-
import { Location, RouteObject } from 'react-router';
3-
import { TransitionActions } from 'react-transition-group/Transition';
1+
import React from 'react';
2+
import { AnimatedRouterProps } from './useAnimatedRoutes';
43
import './animate.scss';
5-
interface AnimatedRouterProps extends TransitionActions {
6-
className?: string;
7-
transitionKey?: string | number;
8-
timeout?: number;
9-
prefix?: string;
10-
component?: ReactType | null;
11-
location?: Location;
12-
children: React.ReactNode | RouteObject[];
13-
}
4+
export * from './useAnimatedRoutes';
145
/**
156
* @desc 路由动画组件
167
* @author qiqiboy
@@ -20,6 +11,6 @@ interface AnimatedRouterProps extends TransitionActions {
2011
* import 'react-animated-router/animate.css';
2112
*/
2213
declare const AnimatedRouter: React.FC<AnimatedRouterProps & {
23-
_parentPath?: string;
14+
children: React.ReactNode;
2415
}>;
2516
export default AnimatedRouter;

0 commit comments

Comments
 (0)