vitarx-router 4.0.0-beta.1 → 4.0.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -482
- package/dist/{vite/auto-routes → auto-routes}/handleHotUpdate.d.ts +1 -1
- package/dist/{vite/auto-routes → auto-routes}/index.d.ts +0 -1
- package/dist/{vite/auto-routes → auto-routes}/index.js +0 -1
- package/dist/components/RouterView.d.ts +3 -3
- package/dist/core/router/manager.js +2 -0
- package/dist/core/router/router.js +3 -3
- package/dist/file-router/config/index.d.ts +7 -0
- package/dist/file-router/config/index.js +7 -0
- package/dist/file-router/config/resolve.d.ts +26 -0
- package/dist/file-router/config/resolve.js +73 -0
- package/dist/file-router/config/validate.d.ts +26 -0
- package/dist/file-router/config/validate.js +230 -0
- package/dist/file-router/constants.d.ts +21 -0
- package/dist/file-router/constants.js +21 -0
- package/dist/file-router/generator/generateRoutes.d.ts +51 -0
- package/dist/file-router/generator/generateRoutes.js +255 -0
- package/dist/file-router/generator/generateTypes.d.ts +40 -0
- package/dist/file-router/generator/generateTypes.js +150 -0
- package/dist/file-router/generator/index.d.ts +7 -0
- package/dist/file-router/generator/index.js +7 -0
- package/dist/file-router/global.d.ts +57 -0
- package/dist/file-router/index.d.ts +183 -0
- package/dist/file-router/index.js +522 -0
- package/dist/file-router/macros/astValueExtractor.d.ts +15 -0
- package/dist/file-router/macros/astValueExtractor.js +236 -0
- package/dist/file-router/macros/definePage.d.ts +45 -0
- package/dist/file-router/macros/definePage.js +224 -0
- package/dist/file-router/macros/index.d.ts +6 -0
- package/dist/file-router/macros/index.js +6 -0
- package/dist/file-router/parser/exportChecker.d.ts +8 -0
- package/dist/file-router/parser/exportChecker.js +186 -0
- package/dist/file-router/parser/filterUtils.d.ts +25 -0
- package/dist/file-router/parser/filterUtils.js +44 -0
- package/dist/file-router/parser/index.d.ts +7 -0
- package/dist/file-router/parser/index.js +7 -0
- package/dist/file-router/parser/parsePage.d.ts +23 -0
- package/dist/file-router/parser/parsePage.js +21 -0
- package/dist/file-router/types/hooks.d.ts +18 -0
- package/dist/file-router/types/hooks.js +1 -0
- package/dist/file-router/types/index.d.ts +3 -0
- package/dist/file-router/types/index.js +1 -0
- package/dist/file-router/types/options.d.ts +138 -0
- package/dist/file-router/types/options.js +1 -0
- package/dist/file-router/types/route.d.ts +102 -0
- package/dist/file-router/types/route.js +1 -0
- package/dist/file-router/utils/babelUtils.d.ts +29 -0
- package/dist/file-router/utils/babelUtils.js +46 -0
- package/dist/file-router/utils/fileReader.d.ts +11 -0
- package/dist/file-router/utils/fileReader.js +22 -0
- package/dist/file-router/utils/index.d.ts +11 -0
- package/dist/file-router/utils/index.js +11 -0
- package/dist/file-router/utils/logger.d.ts +54 -0
- package/dist/file-router/utils/logger.js +124 -0
- package/dist/file-router/utils/pathStrategy.d.ts +28 -0
- package/dist/{vite/core/namingStrategy.js → file-router/utils/pathStrategy.js} +18 -28
- package/dist/file-router/utils/pathUtils.d.ts +53 -0
- package/dist/file-router/utils/pathUtils.js +76 -0
- package/dist/plugin-vite/index.d.ts +43 -0
- package/dist/plugin-vite/index.js +67 -0
- package/package.json +23 -11
- package/dist/vite/auto-routes/definePage.d.ts +0 -10
- package/dist/vite/auto-routes/definePage.js +0 -10
- package/dist/vite/core/babelUtils.d.ts +0 -16
- package/dist/vite/core/babelUtils.js +0 -28
- package/dist/vite/core/configUtils.d.ts +0 -77
- package/dist/vite/core/configUtils.js +0 -142
- package/dist/vite/core/constants.d.ts +0 -11
- package/dist/vite/core/constants.js +0 -11
- package/dist/vite/core/generateRoutes.d.ts +0 -77
- package/dist/vite/core/generateRoutes.js +0 -245
- package/dist/vite/core/generateTypes.d.ts +0 -11
- package/dist/vite/core/generateTypes.js +0 -163
- package/dist/vite/core/index.d.ts +0 -40
- package/dist/vite/core/index.js +0 -46
- package/dist/vite/core/logger.d.ts +0 -23
- package/dist/vite/core/logger.js +0 -68
- package/dist/vite/core/namingStrategy.d.ts +0 -57
- package/dist/vite/core/parsePage.d.ts +0 -86
- package/dist/vite/core/parsePage.js +0 -975
- package/dist/vite/core/removeDefinePage.d.ts +0 -7
- package/dist/vite/core/removeDefinePage.js +0 -81
- package/dist/vite/core/scanPages.d.ts +0 -35
- package/dist/vite/core/scanPages.js +0 -535
- package/dist/vite/core/types.d.ts +0 -577
- package/dist/vite/core/validateOptions.d.ts +0 -29
- package/dist/vite/core/validateOptions.js +0 -140
- package/dist/vite/index.d.ts +0 -66
- package/dist/vite/index.js +0 -217
- /package/dist/{vite/auto-routes → auto-routes}/handleHotUpdate.js +0 -0
- /package/dist/{vite/core/types.js → file-router/global.js} +0 -0
package/README.md
CHANGED
|
@@ -7,28 +7,10 @@ Vitarx 前端框架官方路由解决方案,提供声明式路由配置、导
|
|
|
7
7
|
[](https://github.com/vitarx-lib/router)
|
|
8
8
|
[](https://router.vitarx.cn)
|
|
9
9
|
|
|
10
|
-
## 目录
|
|
11
|
-
|
|
12
|
-
- [特性](#特性)
|
|
13
|
-
- [安装](#安装)
|
|
14
|
-
- [快速开始](#快速开始)
|
|
15
|
-
- [路由模式](#路由模式)
|
|
16
|
-
- [路由配置](#路由配置)
|
|
17
|
-
- [导航方法](#导航方法)
|
|
18
|
-
- [导航守卫](#导航守卫)
|
|
19
|
-
- [组件](#组件)
|
|
20
|
-
- [组合式 API](#组合式-api)
|
|
21
|
-
- [路由对象](#路由对象)
|
|
22
|
-
- [路由选项](#路由选项)
|
|
23
|
-
- [TypeScript 支持](#typescript-支持)
|
|
24
|
-
- [文件路由](#文件路由)
|
|
25
|
-
- [API 参考](#api-参考)
|
|
26
|
-
- [License](#license)
|
|
27
|
-
|
|
28
10
|
## 特性
|
|
29
11
|
|
|
30
12
|
- 🚀 **多种路由模式** - 支持 Hash、History、Memory 三种路由模式
|
|
31
|
-
- 📁 **文件路由** - 基于 Vite
|
|
13
|
+
- 📁 **文件路由** - 基于 Vite 插件的文件系统路由自动生成,HMR 热更新支持
|
|
32
14
|
- 🔒 **导航守卫** - 完整的路由守卫机制,支持权限控制
|
|
33
15
|
- 🔄 **动态路由** - 支持动态参数、正则约束、可选参数
|
|
34
16
|
- 📦 **懒加载** - 内置组件懒加载支持
|
|
@@ -40,12 +22,7 @@ Vitarx 前端框架官方路由解决方案,提供声明式路由配置、导
|
|
|
40
22
|
## 安装
|
|
41
23
|
|
|
42
24
|
```bash
|
|
43
|
-
# 使用 npm
|
|
44
25
|
npm install vitarx-router
|
|
45
|
-
# 或者使用 yarn
|
|
46
|
-
yarn add vitarx-router
|
|
47
|
-
# 或者使用 pnpm
|
|
48
|
-
pnpm add vitarx-router
|
|
49
26
|
```
|
|
50
27
|
|
|
51
28
|
## 快速开始
|
|
@@ -53,10 +30,9 @@ pnpm add vitarx-router
|
|
|
53
30
|
### 1. 创建路由配置
|
|
54
31
|
|
|
55
32
|
```typescript
|
|
56
|
-
// src/router/index.ts
|
|
57
33
|
import { createRouter, defineRoutes } from 'vitarx-router'
|
|
58
|
-
import Home from '
|
|
59
|
-
import About from '
|
|
34
|
+
import Home from './pages/Home.jsx'
|
|
35
|
+
import About from './pages/About.jsx'
|
|
60
36
|
|
|
61
37
|
const routes = defineRoutes(
|
|
62
38
|
{ path: '/', component: Home },
|
|
@@ -69,7 +45,6 @@ export const router = createRouter({ routes })
|
|
|
69
45
|
### 2. 注册路由器
|
|
70
46
|
|
|
71
47
|
```typescript
|
|
72
|
-
// src/main.ts
|
|
73
48
|
import { createApp } from 'vitarx'
|
|
74
49
|
import { router } from './router'
|
|
75
50
|
import App from './App.jsx'
|
|
@@ -80,7 +55,6 @@ createApp(App).use(router).mount('#app')
|
|
|
80
55
|
### 3. 使用路由视图
|
|
81
56
|
|
|
82
57
|
```jsx
|
|
83
|
-
// App.jsx
|
|
84
58
|
import { RouterView } from 'vitarx-router'
|
|
85
59
|
|
|
86
60
|
export default function App() {
|
|
@@ -96,8 +70,6 @@ export default function App() {
|
|
|
96
70
|
}
|
|
97
71
|
```
|
|
98
72
|
|
|
99
|
-
---
|
|
100
|
-
|
|
101
73
|
## 路由模式
|
|
102
74
|
|
|
103
75
|
### Hash 模式(默认)
|
|
@@ -109,7 +81,6 @@ createRouter({
|
|
|
109
81
|
routes,
|
|
110
82
|
mode: 'hash'
|
|
111
83
|
})
|
|
112
|
-
// URL: https://example.com/#/user/123
|
|
113
84
|
```
|
|
114
85
|
|
|
115
86
|
### History 模式
|
|
@@ -121,7 +92,6 @@ createRouter({
|
|
|
121
92
|
routes,
|
|
122
93
|
mode: 'path'
|
|
123
94
|
})
|
|
124
|
-
// URL: https://example.com/user/123
|
|
125
95
|
```
|
|
126
96
|
|
|
127
97
|
**服务器配置(Nginx):**
|
|
@@ -139,13 +109,9 @@ location / {
|
|
|
139
109
|
```typescript
|
|
140
110
|
import { createMemoryRouter } from 'vitarx-router'
|
|
141
111
|
|
|
142
|
-
createMemoryRouter({
|
|
143
|
-
routes
|
|
144
|
-
})
|
|
112
|
+
createMemoryRouter({ routes })
|
|
145
113
|
```
|
|
146
114
|
|
|
147
|
-
---
|
|
148
|
-
|
|
149
115
|
## 路由配置
|
|
150
116
|
|
|
151
117
|
### 基本路由
|
|
@@ -155,8 +121,7 @@ import { defineRoutes } from 'vitarx-router'
|
|
|
155
121
|
|
|
156
122
|
const routes = defineRoutes(
|
|
157
123
|
{ path: '/', component: Home },
|
|
158
|
-
{ path: '/about', component: About }
|
|
159
|
-
{ path: '/contact', component: Contact }
|
|
124
|
+
{ path: '/about', component: About }
|
|
160
125
|
)
|
|
161
126
|
```
|
|
162
127
|
|
|
@@ -166,26 +131,16 @@ const routes = defineRoutes(
|
|
|
166
131
|
|
|
167
132
|
```typescript
|
|
168
133
|
const routes = defineRoutes(
|
|
169
|
-
// 基本动态参数
|
|
170
134
|
{ path: '/user/{id}', component: User },
|
|
171
|
-
|
|
172
|
-
// 可选参数
|
|
173
135
|
{ path: '/search/{query?}', component: Search },
|
|
174
|
-
|
|
175
|
-
// 带正则约束
|
|
176
136
|
{
|
|
177
137
|
path: '/post/{id}',
|
|
178
138
|
component: Post,
|
|
179
|
-
pattern: { id: /^\d+$/ }
|
|
139
|
+
pattern: { id: /^\d+$/ }
|
|
180
140
|
}
|
|
181
141
|
)
|
|
182
142
|
```
|
|
183
143
|
|
|
184
|
-
**参数说明:**
|
|
185
|
-
- `{id}` - 必填参数
|
|
186
|
-
- `{id?}` - 可选参数
|
|
187
|
-
- `pattern` - 正则约束,用于精确匹配
|
|
188
|
-
|
|
189
144
|
### 嵌套路由
|
|
190
145
|
|
|
191
146
|
```typescript
|
|
@@ -208,46 +163,24 @@ const routes = defineRoutes({
|
|
|
208
163
|
component: UserDetail
|
|
209
164
|
})
|
|
210
165
|
|
|
211
|
-
// 导航时使用名称
|
|
212
166
|
router.push({ index: 'user-detail', params: { id: '123' } })
|
|
213
167
|
```
|
|
214
168
|
|
|
215
169
|
### 路由别名
|
|
216
170
|
|
|
217
|
-
支持单个或多个别名:
|
|
218
|
-
|
|
219
171
|
```typescript
|
|
220
172
|
const routes = defineRoutes(
|
|
221
|
-
// 单个别名
|
|
222
173
|
{ path: '/home', component: Home, alias: '/main' },
|
|
223
|
-
|
|
224
|
-
// 多个别名
|
|
225
|
-
{ path: '/users', component: Users, alias: ['/members', '/people'] },
|
|
226
|
-
|
|
227
|
-
// 动态路由别名
|
|
228
|
-
{ path: '/users/{id}', component: User, alias: '/members/{id}' }
|
|
174
|
+
{ path: '/users', component: Users, alias: ['/members', '/people'] }
|
|
229
175
|
)
|
|
230
176
|
```
|
|
231
177
|
|
|
232
178
|
### 重定向
|
|
233
179
|
|
|
234
|
-
支持字符串、对象和函数形式的重定向:
|
|
235
|
-
|
|
236
180
|
```typescript
|
|
237
181
|
const routes = defineRoutes(
|
|
238
|
-
// 字符串重定向
|
|
239
182
|
{ path: '/home', redirect: '/' },
|
|
240
|
-
|
|
241
|
-
// 对象重定向
|
|
242
|
-
{ path: '/old-user/{id}', redirect: { index: 'user-detail' } },
|
|
243
|
-
|
|
244
|
-
// 函数重定向
|
|
245
|
-
{
|
|
246
|
-
path: '/search/{query}',
|
|
247
|
-
redirect: (to) => {
|
|
248
|
-
return { index: 'search-results', query: { q: to.params.query } }
|
|
249
|
-
}
|
|
250
|
-
}
|
|
183
|
+
{ path: '/old-user/{id}', redirect: { index: 'user-detail' } }
|
|
251
184
|
)
|
|
252
185
|
```
|
|
253
186
|
|
|
@@ -266,9 +199,7 @@ const routes = defineRoutes({
|
|
|
266
199
|
|
|
267
200
|
### 命名视图
|
|
268
201
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
```jsx
|
|
202
|
+
```tsx
|
|
272
203
|
const routes = defineRoutes({
|
|
273
204
|
path: '/settings',
|
|
274
205
|
component: {
|
|
@@ -282,32 +213,6 @@ const routes = defineRoutes({
|
|
|
282
213
|
<RouterView name="sidebar" />
|
|
283
214
|
```
|
|
284
215
|
|
|
285
|
-
### 路由参数注入
|
|
286
|
-
|
|
287
|
-
支持多种方式向组件注入参数:
|
|
288
|
-
|
|
289
|
-
```typescript
|
|
290
|
-
const routes = defineRoutes(
|
|
291
|
-
// 注入动态参数到组件 props
|
|
292
|
-
{ path: '/user/{id}', component: User, props: true },
|
|
293
|
-
|
|
294
|
-
// 注入静态对象
|
|
295
|
-
{ path: '/about', component: About, props: { showFooter: true } },
|
|
296
|
-
|
|
297
|
-
// 使用函数动态注入
|
|
298
|
-
{
|
|
299
|
-
path: '/search/{query}',
|
|
300
|
-
component: Search,
|
|
301
|
-
props: (route) => ({
|
|
302
|
-
query: route.params.query,
|
|
303
|
-
page: route.query.page
|
|
304
|
-
})
|
|
305
|
-
}
|
|
306
|
-
)
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
---
|
|
310
|
-
|
|
311
216
|
## 导航方法
|
|
312
217
|
|
|
313
218
|
### push
|
|
@@ -315,27 +220,12 @@ const routes = defineRoutes(
|
|
|
315
220
|
跳转到新路由,添加历史记录。
|
|
316
221
|
|
|
317
222
|
```typescript
|
|
318
|
-
// 路径导航
|
|
319
223
|
router.push({ index: '/user/123' })
|
|
320
|
-
|
|
321
|
-
// 命名导航
|
|
322
224
|
router.push({ index: 'user-detail', params: { id: '123' } })
|
|
323
|
-
|
|
324
|
-
// 带查询参数
|
|
325
225
|
router.push({ index: '/search', query: { q: 'keyword' } })
|
|
326
|
-
|
|
327
|
-
// 带 hash
|
|
328
|
-
router.push({ index: '/about', hash: '#section' })
|
|
329
|
-
|
|
330
|
-
// 也支持直接传入路径字符串
|
|
331
226
|
router.push('/user/123')
|
|
332
|
-
|
|
333
|
-
// 或传入 RouteLocation 对象
|
|
334
|
-
router.push(routeLocation)
|
|
335
227
|
```
|
|
336
228
|
|
|
337
|
-
**返回值:** `Promise<NavigateResult>`
|
|
338
|
-
|
|
339
229
|
### replace
|
|
340
230
|
|
|
341
231
|
替换当前路由,不添加历史记录。
|
|
@@ -344,43 +234,36 @@ router.push(routeLocation)
|
|
|
344
234
|
router.replace({ index: '/login' })
|
|
345
235
|
```
|
|
346
236
|
|
|
347
|
-
**返回值:** `Promise<NavigateResult>`
|
|
348
|
-
|
|
349
237
|
### go
|
|
350
238
|
|
|
351
239
|
前进/后退指定步数。
|
|
352
240
|
|
|
353
241
|
```typescript
|
|
354
|
-
router.go(-1)
|
|
355
|
-
router.go(1)
|
|
356
|
-
router.go(2)
|
|
357
|
-
router.go() // 刷新当前页面
|
|
242
|
+
router.go(-1)
|
|
243
|
+
router.go(1)
|
|
244
|
+
router.go(2)
|
|
358
245
|
```
|
|
359
246
|
|
|
360
247
|
### back / forward
|
|
361
248
|
|
|
362
|
-
后退/前进一步。
|
|
363
|
-
|
|
364
249
|
```typescript
|
|
365
|
-
router.back()
|
|
366
|
-
router.forward()
|
|
250
|
+
router.back()
|
|
251
|
+
router.forward()
|
|
367
252
|
```
|
|
368
253
|
|
|
369
254
|
### 导航结果
|
|
370
255
|
|
|
371
|
-
所有导航方法返回 `NavigateResult` 对象:
|
|
372
|
-
|
|
373
256
|
```typescript
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
257
|
+
import { hasSuccess, NavState } from 'vitarx-router'
|
|
258
|
+
|
|
259
|
+
const result = await router.push({ index: '/home' })
|
|
260
|
+
|
|
261
|
+
if (hasSuccess(result)) {
|
|
262
|
+
console.log('导航成功')
|
|
380
263
|
}
|
|
381
264
|
```
|
|
382
265
|
|
|
383
|
-
|
|
266
|
+
**导航状态:**
|
|
384
267
|
|
|
385
268
|
| 状态 | 值 | 说明 |
|
|
386
269
|
|--------------|----|----------|
|
|
@@ -390,64 +273,22 @@ interface NavigateResult {
|
|
|
390
273
|
| `duplicated` | 8 | 重复导航 |
|
|
391
274
|
| `notfound` | 16 | 路由未匹配 |
|
|
392
275
|
|
|
393
|
-
**检查导航状态:**
|
|
394
|
-
|
|
395
|
-
```typescript
|
|
396
|
-
import { hasSuccess, hasState, NavState } from 'vitarx-router'
|
|
397
|
-
|
|
398
|
-
const result = await router.push({ index: '/home' })
|
|
399
|
-
|
|
400
|
-
// 检查是否成功
|
|
401
|
-
if (hasSuccess(result)) {
|
|
402
|
-
console.log('导航成功')
|
|
403
|
-
}
|
|
404
|
-
|
|
405
|
-
// 检查特定状态
|
|
406
|
-
if (hasState(result, NavState.aborted)) {
|
|
407
|
-
console.log('导航被阻止')
|
|
408
|
-
}
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
---
|
|
412
|
-
|
|
413
276
|
## 导航守卫
|
|
414
277
|
|
|
415
278
|
### 全局前置守卫
|
|
416
279
|
|
|
417
|
-
在路由跳转前执行,可用于权限验证。
|
|
418
|
-
|
|
419
280
|
```typescript
|
|
420
|
-
const router = createRouter({ routes })
|
|
421
|
-
|
|
422
281
|
router.beforeEach((to, from) => {
|
|
423
|
-
// 需要登录的页面
|
|
424
282
|
if (to.meta.requiresAuth && !isAuthenticated()) {
|
|
425
|
-
return { index: '/login' }
|
|
283
|
+
return { index: '/login' }
|
|
426
284
|
}
|
|
427
|
-
|
|
428
|
-
// 返回 false 取消导航
|
|
429
|
-
// return false
|
|
430
|
-
|
|
431
|
-
// 返回 void 或 true 继续导航
|
|
432
285
|
})
|
|
433
286
|
```
|
|
434
287
|
|
|
435
|
-
**守卫返回值:**
|
|
436
|
-
|
|
437
|
-
| 返回值 | 说明 |
|
|
438
|
-
|------------------|----------|
|
|
439
|
-
| `true` / `void` | 继续导航 |
|
|
440
|
-
| `false` | 取消导航 |
|
|
441
|
-
| `string` | 重定向到指定路径 |
|
|
442
|
-
| `NavigateTarget` | 重定向到目标路由 |
|
|
443
|
-
|
|
444
288
|
### 全局后置守卫
|
|
445
289
|
|
|
446
|
-
在路由跳转后执行,可用于更新页面标题等。
|
|
447
|
-
|
|
448
290
|
```typescript
|
|
449
291
|
router.afterEach((to, from) => {
|
|
450
|
-
// 更新页面标题
|
|
451
292
|
document.title = to.meta.title || '默认标题'
|
|
452
293
|
})
|
|
453
294
|
```
|
|
@@ -466,71 +307,22 @@ const routes = defineRoutes({
|
|
|
466
307
|
})
|
|
467
308
|
```
|
|
468
309
|
|
|
469
|
-
支持数组形式的多个守卫:
|
|
470
|
-
|
|
471
|
-
```typescript
|
|
472
|
-
const routes = defineRoutes({
|
|
473
|
-
path: '/admin',
|
|
474
|
-
component: Admin,
|
|
475
|
-
beforeEnter: [guard1, guard2]
|
|
476
|
-
})
|
|
477
|
-
```
|
|
478
|
-
|
|
479
310
|
### 组件内守卫
|
|
480
311
|
|
|
481
|
-
在组件内注册离开守卫和更新钩子:
|
|
482
|
-
|
|
483
312
|
```typescript
|
|
484
313
|
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vitarx-router'
|
|
485
314
|
|
|
486
315
|
export default function UserComponent() {
|
|
487
|
-
// 离开守卫
|
|
488
316
|
onBeforeRouteLeave((to, from) => {
|
|
489
|
-
|
|
490
|
-
if (!answer) return false
|
|
317
|
+
if (!window.confirm('确定要离开吗?')) return false
|
|
491
318
|
})
|
|
492
319
|
|
|
493
|
-
// 更新钩子
|
|
494
320
|
onBeforeRouteUpdate((to, from) => {
|
|
495
321
|
console.log('路由参数更新', to.params)
|
|
496
322
|
})
|
|
497
323
|
}
|
|
498
324
|
```
|
|
499
325
|
|
|
500
|
-
### 错误处理
|
|
501
|
-
|
|
502
|
-
```typescript
|
|
503
|
-
const router = createRouter({
|
|
504
|
-
routes,
|
|
505
|
-
onError: (error, to, from) => {
|
|
506
|
-
console.error('路由错误:', error)
|
|
507
|
-
}
|
|
508
|
-
})
|
|
509
|
-
```
|
|
510
|
-
|
|
511
|
-
### 404 处理
|
|
512
|
-
|
|
513
|
-
```typescript
|
|
514
|
-
const router = createRouter({
|
|
515
|
-
routes,
|
|
516
|
-
onNotFound: (target) => {
|
|
517
|
-
console.log('未找到路由:', target)
|
|
518
|
-
return { index: '/404' } // 重定向到 404 页面
|
|
519
|
-
}
|
|
520
|
-
})
|
|
521
|
-
```
|
|
522
|
-
|
|
523
|
-
或使用 `missing` 组件:
|
|
524
|
-
|
|
525
|
-
```typescript
|
|
526
|
-
const router = createRouter({
|
|
527
|
-
routes,
|
|
528
|
-
missing: NotFoundComponent
|
|
529
|
-
})
|
|
530
|
-
```
|
|
531
|
-
|
|
532
|
-
---
|
|
533
|
-
|
|
534
326
|
## 组件
|
|
535
327
|
|
|
536
328
|
### RouterView
|
|
@@ -538,13 +330,8 @@ const router = createRouter({
|
|
|
538
330
|
渲染匹配的路由组件。
|
|
539
331
|
|
|
540
332
|
```jsx
|
|
541
|
-
// 基本用法
|
|
542
333
|
<RouterView />
|
|
543
|
-
|
|
544
|
-
// 命名视图
|
|
545
334
|
<RouterView name="sidebar" />
|
|
546
|
-
|
|
547
|
-
// 自定义渲染
|
|
548
335
|
<RouterView>
|
|
549
336
|
{(component, props, route) => (
|
|
550
337
|
<Transition name="fade">
|
|
@@ -554,234 +341,111 @@ const router = createRouter({
|
|
|
554
341
|
</RouterView>
|
|
555
342
|
```
|
|
556
343
|
|
|
557
|
-
**Props:**
|
|
558
|
-
|
|
559
|
-
| 属性 | 类型 | 默认值 | 说明 |
|
|
560
|
-
|------------|------------|-------------|---------|
|
|
561
|
-
| `name` | `string` | `'default'` | 命名视图名称 |
|
|
562
|
-
| `children` | `function` | - | 自定义渲染函数 |
|
|
563
|
-
|
|
564
344
|
### RouterLink
|
|
565
345
|
|
|
566
346
|
声明式导航链接。
|
|
567
347
|
|
|
568
348
|
```jsx
|
|
569
|
-
// 基本用法
|
|
570
349
|
<RouterLink to="/">首页</RouterLink>
|
|
571
|
-
|
|
572
|
-
// 命名路由
|
|
573
350
|
<RouterLink to={{ index: 'user-detail', params: { id: '123' } }}>
|
|
574
351
|
用户详情
|
|
575
352
|
</RouterLink>
|
|
576
|
-
|
|
577
|
-
// 带查询参数
|
|
578
|
-
<RouterLink to={{ index: '/search', query: { q: 'keyword' } }}>
|
|
579
|
-
搜索
|
|
580
|
-
</RouterLink>
|
|
581
|
-
|
|
582
|
-
// 替换模式
|
|
583
353
|
<RouterLink to="/about" replace>关于</RouterLink>
|
|
584
|
-
|
|
585
|
-
// 激活类名
|
|
586
|
-
<RouterLink
|
|
587
|
-
to="/"
|
|
588
|
-
activeClass="active"
|
|
589
|
-
exactActiveClass="exact-active"
|
|
590
|
-
>
|
|
354
|
+
<RouterLink to="/" activeClass="active" exactActiveClass="exact-active">
|
|
591
355
|
首页
|
|
592
356
|
</RouterLink>
|
|
593
|
-
|
|
594
|
-
// 禁用状态
|
|
595
|
-
<RouterLink to="/about" disabled>禁用链接</RouterLink>
|
|
596
|
-
|
|
597
|
-
// 外部链接
|
|
598
|
-
<RouterLink to="https://example.com" target="_blank">
|
|
599
|
-
外部链接
|
|
600
|
-
</RouterLink>
|
|
601
357
|
```
|
|
602
358
|
|
|
603
|
-
**Props:**
|
|
604
|
-
|
|
605
|
-
| 属性 | 类型 | 默认值 | 说明 |
|
|
606
|
-
|--------------------|--------------------|----------|--------------------------|
|
|
607
|
-
| `to` | `string \| object` | - | 目标路由 |
|
|
608
|
-
| `replace` | `boolean` | `false` | 是否替换历史记录 |
|
|
609
|
-
| `disabled` | `boolean` | `false` | 是否禁用 |
|
|
610
|
-
| `activeClass` | `string` | - | 激活时应用的类名 |
|
|
611
|
-
| `exactActiveClass` | `string` | - | 精确匹配时应用的类名 |
|
|
612
|
-
| `ariaCurrentValue` | `string` | `'page'` | aria-current 属性值 |
|
|
613
|
-
| `callback` | `function` | - | 导航完成回调 |
|
|
614
|
-
| `viewTransition` | `boolean` | `false` | 是否使用 View Transition API |
|
|
615
|
-
|
|
616
|
-
---
|
|
617
|
-
|
|
618
359
|
## 组合式 API
|
|
619
360
|
|
|
620
361
|
### useRouter
|
|
621
362
|
|
|
622
363
|
获取路由器实例。
|
|
623
364
|
|
|
624
|
-
```
|
|
365
|
+
```typescript
|
|
625
366
|
import { useRouter } from 'vitarx-router'
|
|
626
367
|
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
const handleClick = () => {
|
|
631
|
-
router.push({ index: '/home' })
|
|
632
|
-
}
|
|
633
|
-
|
|
634
|
-
return <button onClick={handleClick}>跳转</button>
|
|
635
|
-
}
|
|
368
|
+
const router = useRouter()
|
|
369
|
+
router.push({ index: '/home' })
|
|
636
370
|
```
|
|
637
371
|
|
|
638
372
|
### useRoute
|
|
639
373
|
|
|
640
374
|
获取当前路由信息。
|
|
641
375
|
|
|
642
|
-
```
|
|
376
|
+
```typescript
|
|
643
377
|
import { useRoute } from 'vitarx-router'
|
|
644
378
|
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
// 路由参数
|
|
649
|
-
const userId = route.params.id
|
|
650
|
-
|
|
651
|
-
// 查询参数
|
|
652
|
-
const query = route.query
|
|
653
|
-
|
|
654
|
-
// 路由元数据
|
|
655
|
-
const meta = route.meta
|
|
656
|
-
|
|
657
|
-
return <div>用户ID: {userId}</div>
|
|
658
|
-
}
|
|
379
|
+
const route = useRoute()
|
|
380
|
+
const userId = route.params.id
|
|
381
|
+
const query = route.query
|
|
659
382
|
```
|
|
660
383
|
|
|
661
|
-
**参数:**
|
|
662
|
-
- `global` - 是否返回全局路由对象,默认 `false`
|
|
663
|
-
|
|
664
384
|
### useLink
|
|
665
385
|
|
|
666
|
-
|
|
386
|
+
创建链接助手。
|
|
667
387
|
|
|
668
|
-
```
|
|
388
|
+
```typescript
|
|
669
389
|
import { useLink } from 'vitarx-router'
|
|
670
390
|
|
|
671
|
-
|
|
672
|
-
const { href, route, isActive, isExactActive, navigate } = useLink({ to })
|
|
673
|
-
|
|
674
|
-
return (
|
|
675
|
-
<a
|
|
676
|
-
href={href.value}
|
|
677
|
-
onClick={navigate}
|
|
678
|
-
class={{ active: isActive.value, 'exact-active': isExactActive.value }}
|
|
679
|
-
>
|
|
680
|
-
<slot />
|
|
681
|
-
</a>
|
|
682
|
-
)
|
|
683
|
-
}
|
|
391
|
+
const { href, route, isActive, isExactActive, navigate } = useLink({ to: '/home' })
|
|
684
392
|
```
|
|
685
393
|
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
| 属性 | 类型 | 说明 |
|
|
689
|
-
|-----------------|-----------------------------------|-------------|
|
|
690
|
-
| `href` | `Computed<string>` | 链接 href 属性值 |
|
|
691
|
-
| `route` | `Computed<RouteLocation \| null>` | 匹配的路由信息 |
|
|
692
|
-
| `isActive` | `Computed<boolean>` | 是否部分匹配当前路由 |
|
|
693
|
-
| `isExactActive` | `Computed<boolean>` | 是否精确匹配当前路由 |
|
|
694
|
-
| `navigate` | `function` | 执行导航 |
|
|
695
|
-
|
|
696
|
-
---
|
|
697
|
-
|
|
698
|
-
## 路由对象
|
|
394
|
+
## 文件路由
|
|
699
395
|
|
|
700
|
-
|
|
396
|
+
配合 Vite 插件实现基于文件系统的路由自动生成。
|
|
701
397
|
|
|
702
|
-
|
|
398
|
+
### 安装配置
|
|
703
399
|
|
|
704
400
|
```typescript
|
|
705
|
-
|
|
706
|
-
href: string // 完整 href
|
|
707
|
-
path: RoutePath // 路由路径
|
|
708
|
-
hash: URLHash | '' // URL hash
|
|
709
|
-
params: URLParams // 路由参数
|
|
710
|
-
query: URLQuery // 查询参数
|
|
711
|
-
meta: RouteMetaData // 路由元数据
|
|
712
|
-
matched: RouteRecord[] // 匹配的路由记录
|
|
713
|
-
redirectFrom?: RouteLocation // 重定向来源
|
|
714
|
-
}
|
|
715
|
-
```
|
|
716
|
-
|
|
717
|
-
### RouteRecord
|
|
718
|
-
|
|
719
|
-
解析后的路由记录。
|
|
401
|
+
import VitarxRouter from 'vitarx-router/vite'
|
|
720
402
|
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
component?: NamedRouteComponent // 视图组件
|
|
732
|
-
beforeEnter?: NavigationGuard[] // 路由守卫
|
|
733
|
-
pattern?: ResolvedPattern[] // 动态参数匹配模式
|
|
734
|
-
params?: URLParams // 路由参数
|
|
735
|
-
query?: URLQuery // 查询参数
|
|
736
|
-
}
|
|
403
|
+
export default defineConfig({
|
|
404
|
+
plugins: [
|
|
405
|
+
VitarxRouter({
|
|
406
|
+
pages: 'src/pages',
|
|
407
|
+
pathStrategy: 'kebab',
|
|
408
|
+
importMode: 'lazy',
|
|
409
|
+
dts: 'router.d.ts'
|
|
410
|
+
})
|
|
411
|
+
]
|
|
412
|
+
})
|
|
737
413
|
```
|
|
738
414
|
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
## 路由选项
|
|
742
|
-
|
|
743
|
-
### RouterOptions
|
|
415
|
+
### 使用生成的路由
|
|
744
416
|
|
|
745
417
|
```typescript
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
suffix?: `.${string}` // URL 后缀
|
|
751
|
-
props?: boolean | InjectPropsHandler // 全局 props 注入
|
|
752
|
-
scrollBehavior?: BeforeScrollCallback // 滚动行为
|
|
753
|
-
beforeEach?: NavigationGuard | NavigationGuard[] // 全局前置守卫
|
|
754
|
-
afterEach?: AfterCallback | AfterCallback[] // 全局后置守卫
|
|
755
|
-
onNotFound?: NotFoundHandler | NotFoundHandler[] // 404 处理
|
|
756
|
-
onError?: NavErrorListener | NavErrorListener[] // 错误处理
|
|
757
|
-
missing?: RouteViewComponent // 未匹配时渲染的组件
|
|
758
|
-
}
|
|
418
|
+
import routes from 'virtual:vitarx-router:routes'
|
|
419
|
+
import { createRouter } from 'vitarx-router'
|
|
420
|
+
|
|
421
|
+
export const router = createRouter({ routes })
|
|
759
422
|
```
|
|
760
423
|
|
|
761
|
-
###
|
|
424
|
+
### 文件路由配置选项
|
|
762
425
|
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
426
|
+
| 选项 | 类型 | 默认值 | 说明 |
|
|
427
|
+
|------------------|---------------------------------------|---------------|----------|
|
|
428
|
+
| `pages` | `PageSource \| readonly PageSource[]` | `'src/pages'` | 页面来源配置 |
|
|
429
|
+
| `pathStrategy` | `'kebab' \| 'lowercase' \| 'raw'` | `'kebab'` | 路径命名策略 |
|
|
430
|
+
| `importMode` | `'lazy' \| 'sync'` | `'lazy'` | 组件导入模式 |
|
|
431
|
+
| `injectImports` | `readonly string[]` | - | 自定义导入语句 |
|
|
432
|
+
| `dts` | `boolean \| string` | `false` | 类型声明文件配置 |
|
|
433
|
+
| `layoutFileName` | `string` | `'_layout'` | 布局文件名 |
|
|
434
|
+
| `configFileName` | `string` | `'_config'` | 分组配置文件名 |
|
|
435
|
+
| `transform` | `CodeTransformHook` | - | 代码转换钩子 |
|
|
436
|
+
| `extendRoute` | `ExtendRouteHook` | - | 路由扩展钩子 |
|
|
771
437
|
|
|
772
|
-
|
|
438
|
+
详细配置请参考 [File Router 文档](src/file-router/README.md)。
|
|
773
439
|
|
|
774
440
|
## TypeScript 支持
|
|
775
441
|
|
|
776
442
|
### 扩展路由元数据类型
|
|
777
443
|
|
|
778
444
|
```typescript
|
|
779
|
-
// 在全局类型声明文件中
|
|
780
445
|
declare module 'vitarx-router' {
|
|
781
446
|
interface RouteMetaData {
|
|
782
447
|
title?: string
|
|
783
448
|
requiresAuth?: boolean
|
|
784
|
-
icon?: string
|
|
785
449
|
}
|
|
786
450
|
}
|
|
787
451
|
```
|
|
@@ -795,46 +459,8 @@ declare module 'vitarx-router' {
|
|
|
795
459
|
'/search': { query: { q: string } }
|
|
796
460
|
}
|
|
797
461
|
}
|
|
798
|
-
|
|
799
|
-
// 使用时会有类型提示
|
|
800
|
-
router.push({ index: 'user-detail', params: { id: '123' } })
|
|
801
|
-
router.push({ index: '/search', query: { q: 'keyword' } })
|
|
802
462
|
```
|
|
803
463
|
|
|
804
|
-
---
|
|
805
|
-
|
|
806
|
-
## 文件路由
|
|
807
|
-
|
|
808
|
-
配合 Vite 插件实现基于文件系统的路由自动生成。
|
|
809
|
-
|
|
810
|
-
### 安装配置
|
|
811
|
-
|
|
812
|
-
```typescript
|
|
813
|
-
// vite.config.ts
|
|
814
|
-
import VitarxRouter from 'vitarx-router/vite'
|
|
815
|
-
|
|
816
|
-
export default defineConfig({
|
|
817
|
-
plugins: [
|
|
818
|
-
VitarxRouter({
|
|
819
|
-
pagesDir: 'src/pages'
|
|
820
|
-
})
|
|
821
|
-
]
|
|
822
|
-
})
|
|
823
|
-
```
|
|
824
|
-
|
|
825
|
-
### 使用生成的路由
|
|
826
|
-
|
|
827
|
-
```typescript
|
|
828
|
-
import routes from 'virtual:vitarx-router:routes'
|
|
829
|
-
import { createRouter } from 'vitarx-router'
|
|
830
|
-
|
|
831
|
-
export const router = createRouter({ routes })
|
|
832
|
-
```
|
|
833
|
-
|
|
834
|
-
详细配置请参考 [Vite 插件文档](./src/vite/README.md)。
|
|
835
|
-
|
|
836
|
-
---
|
|
837
|
-
|
|
838
464
|
## API 参考
|
|
839
465
|
|
|
840
466
|
### 助手函数
|
|
@@ -851,54 +477,32 @@ export const router = createRouter({ routes })
|
|
|
851
477
|
| `useLink(options)` | 创建链接助手 |
|
|
852
478
|
| `onBeforeRouteLeave(guard)` | 注册离开守卫 |
|
|
853
479
|
| `onBeforeRouteUpdate(callback)` | 注册更新钩子 |
|
|
854
|
-
| `hasSuccess(result)` | 检查导航是否成功 |
|
|
855
|
-
| `hasState(result, status)` | 检查导航状态 |
|
|
856
480
|
|
|
857
481
|
### Router 实例方法
|
|
858
482
|
|
|
859
|
-
| 方法
|
|
860
|
-
|
|
861
|
-
| `push(target)`
|
|
862
|
-
| `replace(target)`
|
|
863
|
-
| `go(delta)`
|
|
864
|
-
| `back()`
|
|
865
|
-
| `forward()`
|
|
866
|
-
| `addRoute(route, parent?)`
|
|
867
|
-
| `removeRoute(index)`
|
|
868
|
-
| `hasRoute(index)`
|
|
869
|
-
| `matchRoute(target)`
|
|
870
|
-
| `
|
|
871
|
-
| `
|
|
872
|
-
| `
|
|
873
|
-
| `isReady()` | 等待路由器就绪 |
|
|
874
|
-
| `beforeEach(guard)` | 添加前置守卫 |
|
|
875
|
-
| `afterEach(callback)` | 添加后置回调 |
|
|
876
|
-
| `destroy()` | 销毁路由器 |
|
|
483
|
+
| 方法 | 说明 |
|
|
484
|
+
|----------------------------|-----------|
|
|
485
|
+
| `push(target)` | 跳转到新路由 |
|
|
486
|
+
| `replace(target)` | 替换当前路由 |
|
|
487
|
+
| `go(delta)` | 前进/后退指定步数 |
|
|
488
|
+
| `back()` | 后退一步 |
|
|
489
|
+
| `forward()` | 前进一步 |
|
|
490
|
+
| `addRoute(route, parent?)` | 添加路由 |
|
|
491
|
+
| `removeRoute(index)` | 移除路由 |
|
|
492
|
+
| `hasRoute(index)` | 检查路由是否存在 |
|
|
493
|
+
| `matchRoute(target)` | 匹配路由 |
|
|
494
|
+
| `beforeEach(guard)` | 添加前置守卫 |
|
|
495
|
+
| `afterEach(callback)` | 添加后置回调 |
|
|
496
|
+
| `destroy()` | 销毁路由器 |
|
|
877
497
|
|
|
878
498
|
### Router 实例属性
|
|
879
499
|
|
|
880
|
-
| 属性 | 类型 | 说明
|
|
881
|
-
|
|
882
|
-
| `route` | `ReadonlyObject<RouteLocation>` |
|
|
883
|
-
| `routes` | `RouteRecord[]` | 所有注册的路由记录
|
|
884
|
-
| `config` | `ResolvedRouterConfig` | 路由器配置
|
|
885
|
-
| `manager` | `RouteManager` | 路由管理器实例
|
|
886
|
-
|
|
887
|
-
### RouteManager 实例方法
|
|
888
|
-
|
|
889
|
-
| 方法 | 说明 |
|
|
890
|
-
|------------------------------|---------|
|
|
891
|
-
| `findByPath(path)` | 按路径查找路由 |
|
|
892
|
-
| `findByName(name)` | 按名称查找路由 |
|
|
893
|
-
| `find(index)` | 统一查找方法 |
|
|
894
|
-
| `matchByPath(path)` | 按路径匹配路由 |
|
|
895
|
-
| `matchByName(name, params?)` | 按名称匹配路由 |
|
|
896
|
-
| `match(index, params?)` | 统一匹配方法 |
|
|
897
|
-
| `addRoute(route, parent?)` | 添加路由 |
|
|
898
|
-
| `removeRoute(index)` | 移除路由 |
|
|
899
|
-
| `clearRoutes()` | 清空所有路由 |
|
|
900
|
-
|
|
901
|
-
---
|
|
500
|
+
| 属性 | 类型 | 说明 |
|
|
501
|
+
|-----------|---------------------------------|-----------|
|
|
502
|
+
| `route` | `ReadonlyObject<RouteLocation>` | 当前路由信息 |
|
|
503
|
+
| `routes` | `RouteRecord[]` | 所有注册的路由记录 |
|
|
504
|
+
| `config` | `ResolvedRouterConfig` | 路由器配置 |
|
|
505
|
+
| `manager` | `RouteManager` | 路由管理器实例 |
|
|
902
506
|
|
|
903
507
|
## License
|
|
904
508
|
|