formily-request-monorepo
Version:
A flexible, lightweight, non-intrusive plugin for extending formily schema request data.
146 lines (114 loc) • 3.28 kB
Markdown
---
nav: { title: '指南', order: 1 }
group: { title: '基础', order: 2 }
title: 配置概述
order: 1
toc: content
---
# 配置概述
## 基础使用
formily-request 提供了一套灵活的配置系统，让你能够轻松地处理各种请求场景。以下是一个基本的配置示例：
```json
{
"x-request": {
"url": "https://api.example.com/data",
"method": "POST",
"params": { "keyword": "" }
}
}
```
这个简单的配置就能满足大多数的基础请求场景。对于更复杂的需求，你可以使用数据转换和条件控制等高级特性：
```typescript
{
"x-request": {
"url": "https://api.example.com/data",
"format": "{{ data => data.map(item => ({ label: item.name, value: item.id })) }}",
"ready": "{{ !!$form.values.parentId }}"
}
}
```
:::info
完整的配置项说明请参考 [API 文档](/api)
:::
## 全局配置
通过 `fxr.register()` 方法，可以设置全局配置，影响所有使用 formily-request 的表单字段。
### 基础 URL 配置
设置 API 的基础 URL，避免在每个请求中重复配置完整 URL：
```typescript
import fxr from 'formily-request';
import { Schema } from '@formily/react';
fxr.use(Schema).register({
// 全局基础URL
baseURL: 'https://api.example.com',
});
// 在 schema 中使用相对路径
{
'x-request': {
url: '/users', // 实际请求 https://api.example.com/users
}
}
```
在不同环境中可以灵活配置：
```typescript
fxr.register({
baseURL:
process.env.NODE_ENV === 'production' ? 'https://api.example.com' : '/api', // 本地开发时使用代理
});
```
### 认证与请求头配置
配置跨域请求时的凭证和请求头信息：
```typescript
fxr.register({
// 跨域请求时是否携带凭证（cookies）
credentials: 'include', // 'omit' | 'same-origin' | 'include'
// 自定义请求头
headers: {
Authorization: 'Bearer token',
'X-Custom-Header': 'custom-value',
},
});
```
这些配置会应用到所有请求中，适用于需要统一认证的场景：
```typescript
// 在登录后设置全局认证信息
const setGlobalAuth = (token) => {
fxr.register({
headers: {
Authorization: `Bearer ${token}`,
},
});
};
```
### 错误处理配置
通过 `onLog` 回调函数可以实现全局统一的错误处理机制：
```typescript
fxr.register({
debug: true, // 开启调试模式
onLog: (type, message, data) => {
// type: 'info' | 'error' | 'group' | 'groupEnd'
if (type === 'error') {
const error = data;
message.error(error.message || '请求失败');
// 根据错误类型进行不同处理
if (error instanceof TypeError) {
// 处理网络错误
console.error('网络请求错误:', error);
} else if (error.status === 401) {
// 处理认证错误
router.push('/login');
}
}
},
});
```
`onLog` 回调函数接收三个参数：
- `type`: 日志类型，可能的值为 'info' | 'error' | 'group' | 'groupEnd'
- `message`: 日志消息
- `data`: 额外的数据，当 type 为 'error' 时，data 为错误对象
### 调试配置
通过全局配置开启调试模式，查看请求过程中的详细信息：
```typescript
fxr.register({
debug: true,
});
```