Refine v5 Ant Design Create 组件完全指南属性详解与源码级实践【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读本文围绕 Refine v5 中refinedev/antd包的Create组件展开它在 Ant Design 技术栈下为新建/创建页面提供标准化的页面布局标题、面包屑、返回按钮与保存按钮均由它统一托管本身不包含业务逻辑。读完本文你将掌握Create全部 14 个属性的用法、默认行为与自定义方案并能结合源码理解它如何与useForm、useSelect、资源解析和全局配置协同工作直接用于搭建可复用的创建页。一、Create是什么只提供布局不包含逻辑官方文档对Create的定义非常明确Createprovides us a layout to display the page. It does not contain any logic but adds extra functionalities like action buttons and giving titles to the page.翻译过来即Create是创建页的布局容器它不包含任何业务逻辑但额外提供了动作按钮和页面标题等增强功能。你可以把它理解为创建页的外壳顶部是PageHeader负责渲染标题、返回按钮goBack与面包屑breadcrumb中间是包裹children的Card内容区底部是SaveButton所在的 footer 动作区。这一点在源码中得到了直接印证。packages/antd/src/components/crud/create/index.tsx 中Create组件的整体结构为return ( div {...(wrapperProps ?? {})} PageHeader backIcon{goBackFromProps} onBack{back} title{...} breadcrumb{...} extra{Space wrap {...(headerButtonProps ?? {})}...headerButtons.../Space} {...(headerProps ?? {})} Spin spinning{isLoading} Card variantborderless actions{[Space{...footerButtons...}/Space]} {...(contentProps ?? {})} {children} /Card /Spin /PageHeader /div );从源码结构看Create的 DOM 层级为div PageHeader Spin Card children其中headerButtons挂载在 PageHeader 的extra插槽footerButtons则通过 antdCard的actions插槽渲染。这就是为什么创建页天然自带标题、返回和保存按钮——这些都属于布局能力而表单提交等业务逻辑由你在children中通过useForm自行实现。最小可运行示例文档给出了一个完整可运行的创建页示例结合useForm与useSelect。在 examples/base-antd/src/pages/posts/create.tsx 中可以看到与文档几乎一致的真实示例import { Create, useForm, useSelect } from refinedev/antd; import { Form, Input, Select } from antd; const PostCreate: React.FC () { const { formProps, saveButtonProps } useFormIPost(); const { selectProps: categorySelectProps } useSelectICategory({ resource: categories, pagination: { mode: server }, }); return ( Create saveButtonProps{saveButtonProps} Form {...formProps} layoutvertical Form.Item labelTitle nametitle rules{[{ required: true }]} Input / /Form.Item Form.Item labelCategory name{[category, id]} rules{[{ required: true }]} Select {...categorySelectProps} / /Form.Item Form.Item labelStatus namestatus rules{[{ required: true }]} Select options{[ { label: Published, value: published }, { label: Draft, value: draft }, { label: Rejected, value: rejected }, ]} / /Form.Item /Form /Create ); };要点拆解useFormIPost()返回的saveButtonProps直接透传给Create保存按钮因此具备提交表单、处理加载态的能力useSelectICategory({ resource: categories })返回的selectProps展开到 antdSelect上实现关联分类下拉Form.Item的name{[category, id]}说明该表单提交的数据结构为{ category: { id } }与数据提供方约定一致。在路由层面Create默认假定当前路由是/:resource/create例如/posts/create对应posts资源的创建页文档示例中resources配置为{ name: posts, list: /posts, create: /posts/create }。关于 Swizzle 自定义文档中特别提示Create组件可以通过Refine CLI执行 swizzle 操作把组件源码弹出到你的项目中直接修改。这适合需要深度定制组件内部结构而非仅通过属性的场景。二、标题属性titletitle用于设置Create页面顶部的标题。如果不传title组件默认使用Create前缀 资源的单数形式名称例如资源为/posts/create时默认标题是Create post。从源码看标题的默认逻辑是这样的packages/antd/src/components/crud/create/index.tsxtitle{ title ?? translate( ${identifier}.titles.create, Create ${getUserFriendlyName( resource?.meta?.label ?? identifier, singular, )}, ) }三个细节值得注意优先使用 i18n 翻译键${identifier}.titles.create支持国际化翻译缺省时回退为Create 资源单数友好名单数化通过useUserFriendlyName完成resource?.meta?.label可覆盖默认资源名。自定义标题只需一行Create titleCustom Title pRest of your page here/p /Create三、保存按钮saveButtonPropsCreate默认自带一个提交表单的保存按钮。若要定制它使用saveButtonPropsCreate saveButtonProps{{ size: small }} pRest of your page here/p /Create源码中保存按钮的组装逻辑packages/antd/src/components/crud/create/index.tsxconst saveButtonProps: SaveButtonProps { ...(isLoading ? { disabled: true } : {}), ...saveButtonPropsFromProps, htmlType: submit, }; const defaultFooterButtons ( SaveButton {...saveButtonProps} / / );这意味着当isLoading为true时保存按钮自动被禁用disabled: true你传入的saveButtonProps会合并进去且htmlType恒为submit保证按钮能触发表单提交saveButtonProps的类型来自refinedev/antd的SaveButtonProps可接受 antdButton的任意属性size、type、loading、onClick等。关于SaveButton的完整用法可参考仓库中的 packages/antd/src/components/buttons 目录及相关文档 documentation/docs/ui-integrations/ant-design/components/buttons/save-button/index.md。四、资源绑定resource与identifierCreate默认从路由读取资源信息即 URL 中的:resource段。如果你希望创建页绑定自定义资源可以显式传入resourceconst CustomPage: React.FC () { return ( Create resourceposts pRest of your page here/p /Create ); };源码中通过useResourceParams({ resource: resourceFromProps })解析资源packages/antd/src/components/crud/create/index.tsx这决定了默认标题中的资源名以及面包屑的数据来源。同名资源的identifier文档特别指出如果存在多个同名资源可以传identifier来替代name作为主匹配键。identifier只用于匹配资源定义数据提供方的方法仍会使用Refine/组件中定义的name进行请求。这在多租户、多数据源场景中非常实用。五、返回按钮goBackgoBack用于自定义或禁用返回按钮import { Button } from antd; const PostCreate: React.FC () { const BackButton () Button←/Button; return ( Create goBack{BackButton /} pRest of your page here/p /Create ); };从源码可以看到goBack被作为backIcon传给 PageHeader同时onBack绑定useBack()PageHeader backIcon{goBackFromProps} onBack{back} ... /默认情况下goBack的值为 antd 的ArrowLeft /见文档 API Reference 中goBack-defaultArrowLeft /点击后调用useBack()返回上一页。一个容易被忽略的行为文档强调如果路由没有:action参数或 action 是list即使传了goBack属性返回按钮也不会显示。此时需要用headerProps覆盖import { useBack } from refinedev/core; import { Button } from antd; const PostCreate: React.FC () { const back useBack(); const BackButton () Button←/Button; return ( Create goBack{BackButton /} headerProps{{ onBack: back }} pRest of your page here/p /Create ); };这里headerProps.onBack手动接管了 PageHeader 的返回回调从而绕开默认的显示条件。六、加载状态isLoadingisLoading用于切换Create的加载状态Create isLoading{true} pRest of your page here/p /Create源码实现有两处联动packages/antd/src/components/crud/create/index.tsxisLoading为true时自动禁用保存按钮disabled: true内容区被Spin spinning{isLoading}包裹显示 antd 的加载动画。当创建页需要等待初始数据例如异步获取默认值时用它提升交互体验非常合适。七、面包屑breadcrumbbreadcrumb用于自定义或禁用面包屑。默认情况下Create使用refinedev/antd包导出的Breadcrumb组件import { Create, Breadcrumb } from refinedev/antd; const PostCreate: React.FC () { return ( Create breadcrumb{ div style{{ padding: 3px 6px, border: 2px dashed cornflowerblue }} Breadcrumb / /div } pRest of your page here/p /Create ); };源码中的优先级逻辑packages/antd/src/components/crud/create/index.tsxconst breadcrumb typeof breadcrumbFromProps undefined ? globalBreadcrumb : breadcrumbFromProps;传了breadcrumb属性就用你自定义的内容没传则回退到useRefineContext()中的全局面包屑配置options.breadcrumb这意味着可以在Refine/组件上统一配置所有页面的面包屑全局配置也没有时才渲染组件自身的Breadcrumb /。所以禁用面包屑的正确姿势是传入breadcrumb{null}或breadcrumb{/}而不是不传。八、外层与内容容器wrapperProps、contentPropswrapperProps用于定制Create/最外层包装元素。refinedev/antd的包装元素就是普通的div/因此wrapperProps可以接收div/支持的一切属性style、className、id等Create wrapperProps{{ style: { backgroundColor: cornflowerblue, padding: 16px }, }} pRest of your page here/p /CreatecontentProps用于定制内容区antdCard组件。因为内容区就是 antd 的Card所以contentProps接收CardProps可参考 antdCard文档Create contentProps{{ style: { backgroundColor: cornflowerblue, padding: 16px }, }} pRest of your page here/p /Create类型上CreateProps定义于 packages/antd/src/components/crud/types.ts其中wrapperProps对应HTMLDivElement属性、contentProps对应CardProps、headerProps对应PageHeaderProps。这些类型约束可以在 packages/ui-types/src/types/crud.tsx 的RefineCrudCreateProps泛型定义中找到源头。九、头部定制headerPropsheaderProps用于定制页面头部基于 antd ProComponents 的PageHeader可以设置subTitle、style等Create headerProps{{ subTitle: This is a subtitle, style: { backgroundColor: cornflowerblue, padding: 16px }, }} pRest of your page here/p /Create源码中headerProps在 PageHeader 之后展开{...(headerProps ?? {})}因此它可以覆盖前面已设置的title、backIcon、onBack、breadcrumb、extra等任意 PageHeader 属性。这就是上一节通过headerProps.onBack强制显示返回按钮能生效的原因。十、头部按钮headerButtons与headerButtonPropsheaderButtons头部按钮默认为空源码中defaultButtons: null。headerButtons接受两种形式React.ReactNode直接渲染渲染函数({ defaultButtons }) React.ReactNode可以在保留默认按钮的基础上追加自定义按钮。Create headerButtons{({ defaultButtons }) ( {defaultButtons} Button typeprimaryCustom Button/Button / )} pRest of your page here/p /Create注意与Edit/Show不同Create头部没有内置的默认按钮所以这里的defaultButtons为null。headerButtonProps用于定制头部按钮的包裹元素。源码中头部按钮被包在Space wrap {...(headerButtonProps ?? {})}中packages/antd/src/components/crud/create/index.tsx因此headerButtonProps接收 antdSpace的属性size、wrap、style等Create headerButtonProps{{ style: { backgroundColor: cornflowerblue, padding: 16px }, }} headerButtons{Button typeprimaryCustom Button/Button} pRest of your page here/p /Create十一、底部按钮footerButtons与footerButtonPropsfooterButtons默认情况下Create底部只有一个SaveButton。footerButtons接受两种形式React.ReactNode渲染函数({ defaultButtons, saveButtonProps }) React.ReactNode。保留默认保存按钮并追加自定义按钮Create footerButtons{({ defaultButtons }) ( {defaultButtons} Button typeprimaryCustom Button/Button / )} pRest of your page here/p /Create完全自定义复用saveButtonProps保留保存行为import { Create, SaveButton } from refinedev/antd; import { Button } from antd; Create footerButtons{({ saveButtonProps }) ( SaveButton {...saveButtonProps} typeprimary style{{ marginRight: 8 }} Save /SaveButton Button typeprimaryCustom Button/Button / )} pRest of your page here/p /Create源码中footerButtons渲染函数收到的参数packages/antd/src/components/crud/create/index.tsxfooterButtons({ defaultButtons: defaultFooterButtons, // SaveButton {...saveButtonProps} / saveButtonProps: saveButtonProps, })即defaultButtons就是默认的SaveButton {...saveButtonProps} /saveButtonProps是合并了isLoading禁用逻辑与htmlType: submit之后的最终 props。footerButtonProps用于定制底部按钮的包裹元素。源码中 footer 按钮包在Space style{{ float: right, marginRight: 24 }} {...(footerButtonProps ?? {})}中因此footerButtonProps同样接收 antdSpace属性Create footerButtonProps{{ style: { backgroundColor: cornflowerblue, padding: 16px }, }} pRest of your page here/p /Create十二、测试与验证组件的可靠性保障Create组件带有完整的单元测试位于 packages/antd/src/components/crud/create/index.spec.tsx。它通过crudCreateTests来自refinedev/ui-tests的共享 CRUD 测试套件覆盖了通用的 CRUD 页面行为并额外验证了自定义 footer 按钮时saveButtonProps依然可用这一关键行为it(should customize default buttons with default props, async () { const { queryByTestId } renderCreate( Create saveButtonProps{{ className: customize-test }} footerButtons{({ saveButtonProps }) { expect(saveButtonProps).toBeDefined(); return ( SaveButton {...saveButtonProps} / / ); }} /, ); expect(queryByTestId(RefineButtonTestIds.SaveButton)).toHaveClass( customize-test, ); });从源码与测试可以确认saveButtonProps会正确透传到footerButtons渲染函数且自定义后保存按钮仍保留测试 idRefineButtonTestIds.SaveButton与自定义 className这对二次封装组件和编写 e2e 测试都很友好。十三、API Reference属性速查文档末尾提供了由PropsTable生成的完整 API 表modulerefinedev/antd/Create核心属性汇总如下属性类型默认值作用titleReact.ReactNodeCreate {资源单数名}i18n 键${identifier}.titles.create设置页面标题saveButtonPropsSaveButtonProps—定制底部保存按钮htmlType恒为submitresourcestring从路由:resource读取指定资源同名资源可用identifier作主匹配键goBackReact.ReactNodeArrowLeft /自定义/禁用返回按钮isLoadingbooleanfalse控制加载态禁用保存按钮 内容区 SpinbreadcrumbReact.ReactNode全局配置或Breadcrumb /自定义/禁用面包屑wrapperPropsHTMLDivElement属性—定制最外层div/headerPropsPageHeaderProps—定制头部可覆盖 onBack 等contentPropsCardProps—定制内容区 CardheaderButtonsReactNode \| ({ defaultButtons }) ReactNodenull定制头部按钮headerButtonPropsSpaceProps—定制头部按钮包裹元素footerButtonsReactNode \| ({ defaultButtons, saveButtonProps }) ReactNode默认SaveButton /定制底部按钮footerButtonPropsSpaceProps—定制底部按钮包裹元素类型定义的源头在 packages/ui-types/src/types/crud.tsx 的RefineCrudCreatePropsantd 实现通过 packages/antd/src/components/crud/types.ts 的CreateProps将泛型具体化为SaveButtonProps / SpaceProps / div 属性 / PageHeaderProps / CardProps。总结Create是 Refine v5 Ant Design 集成中创建页的布局基石它用一套稳定的结构div PageHeader Spin Card统一了标题、返回、面包屑、加载态与保存按钮把布局职责从业务代码中完全剥离。实际开发中简单场景useForm返回saveButtonProps直接传入几行代码即可完成创建页定制场景14 个属性覆盖了从标题、按钮、面包屑到内外层样式的全部定制需求深度定制借助 Refine CLI 的 swizzle 能力可以把组件源码弹出到项目中直接改写。理解Create的属性与实现是掌握 Refine Ant Design 创建/编辑/查看三类基础视图Create/Edit/Show共享同一套 CRUD 布局抽象源码见 packages/antd/src/components/crud的第一步也是构建一致、可维护后台界面的关键。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考