通用配置

在 ProComponents 我们在组件使用了与 table 的相同的定义,同时扩展了部分字段。让其可以满足更多需求。

字段名称类型说明
keyReact.key确定这个列的唯一值,一般用于 dataIndex 重复的情况
dataIndexReact.key | React.key[]与实体映射的 key,数组会被转化 [a,b] => Entity.a.b
valueTypeProFieldValueType数据的渲渲染方式,我们自带了一部分,你也可以自定义 valueType
titleReactNode |(props,type,dom)=> ReactNode标题的内容,在 form 中是 label
tooltipstring会在 title 旁边展示一个 icon,鼠标浮动之后展示
valueEnum(Entity)=> ValueEnum | ValueEnum支持 object 和 Map,Map 是支持其他基础类型作为 key
fieldProps(form,config)=>fieldProps| fieldProps传给渲染的组件的 props,自定义的时候也会传递
formItemProps(form,config)=>formItemProps | formItemProps传递给 Form.Item 的配置
renderText(text: any, record: Entity, index: number, action: ProCoreActionType) => any修改的数据是会被 valueType 定义的渲染组件消费
render(dom,entity,index, action, schema) => React.ReactNode自定义只读模式的 dom,render 方法只管理的只读模式,编辑模式需要使用 renderFormItem
renderFormItem(schema,config,form) => React.ReactNode自定义编辑模式,返回一个 ReactNode,会自动包裹 value 和 onChange
request(params,props) => Promise<{label,value}[]>从远程请求网络数据,一般用于选择类组件
paramsRecord<string, any>额外传递给 request 的参数,组件不做处理,但是变化会引起request 重新请求数据
hideInFormboolean在 Form 中隐藏
hideInTableboolean在 Table 中隐藏
hideInSearchboolean在 Table 的查询表单中隐藏
hideInDescriptionsboolean在 descriptions 中隐藏
rowPropsRowProps在开启 grid 模式时传递给 Row,仅在ProFormGroup, ProFormList, ProFormFieldSet 中有效
colPropsColProps在开启 grid 模式时传递给 Col

TypeScript 定义

export type ProSchema<T = unknown, U = string, Extra = unknown> = {
/** @name 确定这个列的唯一值 */
key?: React.ReactText;
/**
* 支持一个数组,[a,b] 会转化为 obj.a.b
*
* @name 与实体映射的key
*/
dataIndex?: string | number | (string | number)[];
/** 选择如何渲染相应的模式 */
valueType?: ((entity: T, type: ProSchemaComponentTypes) => U) | U;
/**
* 支持 ReactNode 和 方法
*
* @name 标题
*/
title?:
| ((
schema: ProSchema<T, U, Extra>,
type: ProSchemaComponentTypes,
dom: React.ReactNode,
) => React.ReactNode)
| React.ReactNode;
/** @name 展示一个 icon,hover 是展示一些提示信息 */
tooltip?: string | LabelTooltipType;
/** @deprecated 你可以使用 tooltip,这个更改是为了与 antd 统一 */
tip?: string;
render?: (
dom: React.ReactNode,
entity: T,
index: number,
action: ProCoreActionType,
schema: ProSchema<T, U, Extra>,
) => React.ReactNode;
/**
* 返回一个node,会自动包裹 value 和 onChange
*
* @name 自定义编辑模式
*/
renderFormItem?: (
item: ProSchema<T, U, Extra>,
config: {
index?: number;
value?: any;
onSelect?: (value: any) => void;
type: ProSchemaComponentTypes;
defaultRender: (newItem: ProSchema<T, U, Extra>) => JSX.Element | null;
},
form: FormInstance,
) => React.ReactNode;
/**
* 必须要返回 string
*
* @name 自定义 render
*/
renderText?: (text: any, record: T, index: number, action: ProCoreActionType) => any;
fieldProps?: any;
/** @name 映射值的类型 */
valueEnum?: ProSchemaValueEnumObj | ProSchemaValueEnumMap;
/** @name 从服务器请求枚举 */
request?: ProFieldRequestData<ProSchema>;
/** @name 从服务器请求的参数,改变了会触发 reload */
params?: {
[key: string]: any;
};
/** @name 隐藏在 descriptions */
hideInDescriptions?: boolean;
} & Extra;

valueType 列表

API

valueType 是 ProComponents 的灵魂,ProComponents 会根据 valueType 来映射成不同的表单项。以下是支持的常见表单项:

valueType说明
password密码输入框
money金额输入框
textarea文本域
date日期
dateTime日期时间
dateWeek
dateMonth
dateQuarter季度输入
dateYear年份输入
dateRange日期区间
dateTimeRange日期时间区间
time时间
timeRange时间区间
text文本框
select下拉框
treeSelect树形下拉框
checkbox多选框
rate星级组件
radio单选框
radioButton按钮单选框
progress进度条
percent百分比组件
digit数字输入框
second秒格式化
avatar头像
code代码框
switch开关
fromNow相对于当前时间
image图片
jsonCode代码框,但是带了 json 格式化
color颜色选择器
cascader级联选择器

这里 demo 可以来了解一下各个 valueType 的展示效果。

传入 function

只有一个值并不能表现很多类型,progress 就是一个很好的例子。所以我们支持传入一个 function。你可以这样使用:

const columns = {
title: '进度',
key: 'progress',
dataIndex: 'progress',
valueType: (item: T) => ({
type: 'progress',
status: item.status !== 'error' ? 'active' : 'exception',
}),
};

支持的返回值

progress

return {
type: 'progress',
status: 'success' | 'exception' | 'normal' | 'active',
};

money

return { type: 'money', locale: 'en-Us' };

percent

return { type: 'percent', showSymbol: true | false, precision: 2 };

如果我们带的 valueType 不能满足需求,我们可以用自定义 valueType 来自定义业务组件。

自定义 valueType

valueEnum

valueEnum 需要传入一个枚举,ProTable 会自动根据值获取响应的枚举,并且在 form 中生成一个下拉框。看起来是这样的:

const valueEnum = {
open: {
text: '未解决',
status: 'Error',
},
closed: {
text: '已解决',
status: 'Success',
},
};
// 也可以设置为一个function
const valueEnum = (row) =>
row.isMe
? {
open: {
text: '未解决',
status: 'Error',
},
closed: {
text: '已解决',
status: 'Success',
},
}
: {
open: {
text: '等待解决',
status: 'Error',
},
closed: {
text: '已回应',
status: 'Success',
},
};

这里值得注意的是在 form 中并没有 row,所以 row 的值为 null,你可以根据这个来判断要在 form 中显示什么选项。

当前列值的枚举

interface IValueEnum {
[key: string]:
| ReactNode
| {
text: ReactNode;
status: 'Success' | 'Error' | 'Processing' | 'Warning' | 'Default';
};
}

远程数据

支持组件 Select, TreeSelect, Cascader, Checkbox, Radio, RadioButton

支持参数 request,params,fieldProps.options, valueEnum 来支持远程数据,这几个属性分别有不同的用法。

valueEnum

valueEnum 是最基础的用法, 它支持传入一个 Object 或者是 Map,相比于 options 支持更加丰富的定义,比如在表格中常见的各种 badge

const valueEnum = {
all: { text: '全部', status: 'Default' },
open: {
text: '未解决',
status: 'Error',
},
closed: {
text: '已解决',
status: 'Success',
},
};

fieldProps.options

options 是 antd 定义的标准,但是只有部分组件支持, ProComponents 扩展了组件,使得 select, checkbox, radio, radioButton 都支持了 options, 他们的用法是相同的。

const options = [
{
label: 'item 1',
value: 'a',
},
{
label: 'item 2',
value: 'b',
},
{
label: 'item 3',
value: 'c',
},
];
// 或者不需要 label
const options = ['chapter', 'chapter2'];
// 列中定义
const columns = [
{
title: '创建者',
width: 120,
dataIndex: 'creator',
valueType: 'select',
fieldProps: {
options: [
{
label: 'item 1',
value: 'a',
},
{
label: 'item 2',
value: 'b',
},
{
label: 'item 3',
value: 'c',
},
],
},
},
];

requestparams

可以使用 debounceTime 调整请求防抖时间,默认为 10ms

大部分时候我们是从网络中获取数据,但是获取写一个 hooks 来请求数据还是比较繁琐的,同时还要定义一系列状态,所以我们提供了 requestparams 来获取数据。

  • request 是一个 promise,需要返回一个 options 相同的数据
  • params 一般而言 request 是惰性的,params 修改会触发 request 的重新请求。
const request = async () => [
{ label: '全部', value: 'all' },
{ label: '未解决', value: 'open' },
{ label: '已解决', value: 'closed' },
{ label: '解决中', value: 'processing' },
];
<ProFormSelect
name="select2"
label="Select"
params={{}}
valueType="select"
debounceTime={1000}
request={request}
placeholder="Please select a country"
/>;
// 列中定义
const columns = [
{
title: '创建者',
width: 120,
dataIndex: 'creator',
valueType: 'select',
request,
params: {},
},
];

在实际的使用中 request 增加了一个 5s 缓存,可能会导致数据更新不及时,如果需要频繁更新,建议使用 state+fieldProps.options