Skip to content

Commit f3846e0

Browse files
haoziqaqhaoziqaq
committed
docs: update docs
1 parent a8b1ae1 commit f3846e0

File tree

4 files changed

+298
-16
lines changed

4 files changed

+298
-16
lines changed

‎README.md

-1
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,6 @@ const useAxle = createUseAxle({
302302
})
303303
304304
const [
305-
// response data
306305
users,
307306
// request runner/invoker
308307
getUsers,

‎README.zh-CN.md

-1
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,6 @@ const useAxle = createUseAxle({
302302
})
303303
304304
const [
305-
// 请求数据
306305
users,
307306
// 请求触发器
308307
getUsers,

‎packages/axle/README.md

+149-7
Original file line numberDiff line numberDiff line change
@@ -295,21 +295,27 @@ const axle = createAxle(/** @see https://axios-http.com **/)
295295
296296
const useAxle = createUseAxle({
297297
axle,
298-
// Optional value: Default immediate of the useAxle
299-
immediate: true,
298+
// Optional value: Default immediate of the useAxle, defaults true
299+
immediate: false,
300300
// Optional value: Default onTransform of the useAxle
301301
onTransform: (response) => response,
302302
})
303303
304-
const [users, getUsers, { loading, error, uploadProgress, downloadProgress, abort, resetValue }] = useAxle({
304+
const [
305+
users,
306+
// request runner/invoker
307+
getUsers,
308+
// extra properties
309+
{ loading, error, uploadProgress, downloadProgress, abort, resetValue }
310+
] = useAxle({
305311
// Request initial value
306312
value: [],
307313
// Request method
308314
method: 'get',
309315
// Request url can be a getter function
310316
url: '/user',
311-
// Whether to send the request immediately, defaults false
312-
immediate: true,
317+
// Whether to send the request immediately, defaults true
318+
immediate: false,
313319
// Whether the value needs to be reset before requesting, defaults false
314320
resetValue: true,
315321
// Whether to clone when resetting value, defaults false
@@ -367,13 +373,11 @@ const axle = createAxle(/** @see https://axios-http.com **/)
367373
const useAxle = createUseAxle({ axle })
368374
369375
const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
370-
value: [],
371376
method: 'get',
372377
url: '/user',
373378
})
374379
375380
const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
376-
value: [],
377381
method: 'get',
378382
url: '/role',
379383
})
@@ -406,3 +410,141 @@ function sendAllRequest() {
406410
<button @click="sendAllRequest">Send All Request</button>
407411
</template>
408412
```
413+
414+
### API Definition Enhancement
415+
416+
`createApi` is supported since `v0.9.0`, which is used to define APIs.
417+
418+
#### Define APIs
419+
420+
```ts
421+
import { createAxle } from '@varlet/axle'
422+
import { createUseAxle } from '@varlet/axle/use'
423+
import { createApi } from '@varlet/axle/api'
424+
425+
const axle = createAxle({
426+
baseURL: '/api',
427+
})
428+
429+
const useAxle = createUseAxle({
430+
axle,
431+
})
432+
433+
const api = createApi(axle, useAxle)
434+
435+
export const apiGetUsers = api<Response<User[]>>('/user', 'get')
436+
437+
export const apiGetUser = api<Response<User>>('/user/:id', 'get')
438+
439+
export const apiCreateUser = api<Response<User>, CreateUser>('/user', 'post')
440+
441+
export const apiUpdateUser = api<Response<User>, UpdateUser>('/user/:id', 'put')
442+
443+
export const apiDeleteUser = api<Response<User>>('/user/:id', 'delete')
444+
445+
export type Response<T> = {
446+
data: T
447+
code: number
448+
message: string
449+
success: boolean
450+
}
451+
452+
export interface User {
453+
id: string
454+
name: string
455+
}
456+
457+
export interface CreateUser {
458+
name: string
459+
}
460+
461+
export interface UpdateUser {
462+
name: string
463+
}
464+
```
465+
466+
#### Invoke APIs
467+
468+
```ts
469+
const route = useRoute()
470+
471+
const [users, getUsers] = apiGetUsers.use<Response<User[]>>(/** same as useAxle and extends pathParams **/)
472+
473+
const [user, getUser] = apiGetUser.use<Response<User>>({
474+
pathParams: () => ({ id: route.params.id }),
475+
})
476+
477+
async function handleCreate(params: CreateUser) {
478+
const { success } = await apiCreateUser.load(params)
479+
480+
if (success) {
481+
getUsers()
482+
}
483+
}
484+
485+
async function handleUpdate(params: UpdateUser, id: string) {
486+
const { success } = await apiUpdateUser.load(params, { id })
487+
488+
if (success) {
489+
getUsers()
490+
}
491+
}
492+
493+
async function handleDelete(id: string) {
494+
const { success } = await apiDeleteUser.load({}, { id })
495+
496+
if (success) {
497+
getUsers()
498+
}
499+
}
500+
```
501+
502+
### Runner Enhancement
503+
504+
Since `v0.10.0`, the `runner` will include all the extra properties, so we can further simplify the work.
505+
506+
before:
507+
508+
```html
509+
<script setup>
510+
const [users, getUsers, { loading: isUsersLoading }] = useAxle({
511+
method: 'get',
512+
url: '/user',
513+
})
514+
515+
const [posts, getPosts, { loading: isPostsLoading }] = useAxle({
516+
method: 'get',
517+
url: '/post',
518+
})
519+
</script>
520+
521+
<template>
522+
<span>{{ isUsersLoading ? 'loading...' : users }}</span>
523+
<span>{{ isPostsLoading ? 'loading...' : posts }}</span>
524+
<button @click="getUsers">Send Request</button>
525+
<button @click="getPosts">Send Request</button>
526+
</template>
527+
```
528+
529+
after:
530+
531+
```html
532+
<script setup>
533+
const [users, getUsers] = useAxle({
534+
method: 'get',
535+
url: '/user',
536+
})
537+
538+
const [posts, getPosts] = useAxle({
539+
method: 'get',
540+
url: '/post',
541+
})
542+
</script>
543+
544+
<template>
545+
<span>{{ getUsers.loading ? 'loading...' : users }}</span>
546+
<span>{{ getPosts.loading ? 'loading...' : posts }}</span>
547+
<button @click="getUsers">Send Request</button>
548+
<button @click="getPosts">Send Request</button>
549+
</template>
550+
```

‎packages/axle/README.zh-CN.md

+149-7
Original file line numberDiff line numberDiff line change
@@ -295,21 +295,27 @@ const axle = createAxle(/** @see https://axios-http.com **/)
295295
296296
const useAxle = createUseAxle({
297297
axle,
298-
// 可选项: useAxle 的默认 immediate
299-
immediate: true,
298+
// 可选项: useAxle 的默认 immediate, 默认值: true
299+
immediate: false,
300300
// 可选项: useAxle 的默认 onTransform
301301
onTransform: (response) => response,
302302
})
303303
304-
const [users, getUsers, { loading, error, uploadProgress, downloadProgress, abort }] = useAxle({
304+
const [
305+
users,
306+
// 请求触发器
307+
getUsers,
308+
// 附加属性
309+
{ loading, error, uploadProgress, downloadProgress, abort }
310+
] = useAxle({
305311
// 请求初始化数据
306312
value: [],
307313
// 请求方法
308314
method: 'get',
309315
// 请求地址, 可以是 getter 函数
310316
url: '/user',
311-
// 是否立即发送请求, 默认值: false
312-
immediate: true,
317+
// 是否立即发送请求, 默认值: true
318+
immediate: false,
313319
// 请求前是否需要重置 value, 默认值: false
314320
resetValue: true,
315321
// 重置 value 是否对 value 进行拷贝
@@ -367,13 +373,11 @@ const axle = createAxle(/** @see https://axios-http.com **/)
367373
const useAxle = createUseAxle({ axle })
368374
369375
const [users, getUsers, { loading: isUsersLoading, downloadProgress: usersDownloadProgress }] = useAxle({
370-
value: [],
371376
method: 'get',
372377
url: '/user',
373378
})
374379
375380
const [roles, getRoles, { loading: isRolesLoading, downloadProgress: rolesDownloadProgress }] = useAxle({
376-
value: [],
377381
method: 'get',
378382
url: '/role',
379383
})
@@ -406,3 +410,141 @@ function sendAllRequest() {
406410
<button @click="sendAllRequest">发送全部请求</button>
407411
</template>
408412
```
413+
414+
### API 定义增强
415+
416+
从 `0.9.0` 开始支持 `createApi`，以增强 API 定义能力。
417+
418+
#### 定义 API
419+
420+
```ts
421+
import { createAxle } from '@varlet/axle'
422+
import { createUseAxle } from '@varlet/axle/use'
423+
import { createApi } from '@varlet/axle/api'
424+
425+
const axle = createAxle({
426+
baseURL: '/api',
427+
})
428+
429+
const useAxle = createUseAxle({
430+
axle,
431+
})
432+
433+
const api = createApi(axle, useAxle)
434+
435+
export const apiGetUsers = api<Response<User[]>>('/user', 'get')
436+
437+
export const apiGetUser = api<Response<User>>('/user/:id', 'get')
438+
439+
export const apiCreateUser = api<Response<User>, CreateUser>('/user', 'post')
440+
441+
export const apiUpdateUser = api<Response<User>, UpdateUser>('/user/:id', 'put')
442+
443+
export const apiDeleteUser = api<Response<User>>('/user/:id', 'delete')
444+
445+
export type Response<T> = {
446+
data: T
447+
code: number
448+
message: string
449+
success: boolean
450+
}
451+
452+
export interface User {
453+
id: string
454+
name: string
455+
}
456+
457+
export interface CreateUser {
458+
name: string
459+
}
460+
461+
export interface UpdateUser {
462+
name: string
463+
}
464+
```
465+
466+
#### 调用 API
467+
468+
```ts
469+
const route = useRoute()
470+
471+
const [users, getUsers] = apiGetUsers.use<Response<User[]>>(/** 和 useAxle 一致并且扩展了 pathParams **/)
472+
473+
const [user, getUser] = apiGetUser.use<Response<User>>({
474+
pathParams: () => ({ id: route.params.id }),
475+
})
476+
477+
async function handleCreate(params: CreateUser) {
478+
const { success } = await apiCreateUser.load(params)
479+
480+
if (success) {
481+
getUsers()
482+
}
483+
}
484+
485+
async function handleUpdate(params: UpdateUser, id: string) {
486+
const { success } = await apiUpdateUser.load(params, { id })
487+
488+
if (success) {
489+
getUsers()
490+
}
491+
}
492+
493+
async function handleDelete(id: string) {
494+
const { success } = await apiDeleteUser.load({}, { id })
495+
496+
if (success) {
497+
getUsers()
498+
}
499+
}
500+
```
501+
502+
### 请求触发器增强
503+
504+
从 `v0.10.0` 开始, 请求触发器将包含附加属性中的全部属性。
505+
506+
增强前:
507+
508+
```html
509+
<script setup>
510+
const [users, getUsers, { loading: isUsersLoading }] = useAxle({
511+
method: 'get',
512+
url: '/user',
513+
})
514+
515+
const [posts, getPosts, { loading: isPostsLoading }] = useAxle({
516+
method: 'get',
517+
url: '/post',
518+
})
519+
</script>
520+
521+
<template>
522+
<span>{{ isUsersLoading ? 'loading...' : users }}</span>
523+
<span>{{ isPostsLoading ? 'loading...' : posts }}</span>
524+
<button @click="getUsers">Send Request</button>
525+
<button @click="getPosts">Send Request</button>
526+
</template>
527+
```
528+
529+
增强后:
530+
531+
```html
532+
<script setup>
533+
const [users, getUsers] = useAxle({
534+
method: 'get',
535+
url: '/user',
536+
})
537+
538+
const [posts, getPosts] = useAxle({
539+
method: 'get',
540+
url: '/post',
541+
})
542+
</script>
543+
544+
<template>
545+
<span>{{ getUsers.loading ? 'loading...' : users }}</span>
546+
<span>{{ getPosts.loading ? 'loading...' : posts }}</span>
547+
<button @click="getUsers">Send Request</button>
548+
<button @click="getPosts">Send Request</button>
549+
</template>
550+
```

0 commit comments

Comments
 (0)