Refine v5 Chakra UI Create 组件完全指南属性详解、源码剖析与实战【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineCreate是 Refine v5 在 Chakra UI 集成包refinedev/chakra-ui中提供的新建页面布局组件它本身不包含任何业务逻辑只负责渲染标题、面包屑、返回按钮、保存按钮和加载状态为表单提供一个统一、规范、可无障碍访问的页面骨架。本文将以该组件在 关联文档 中定义的全部属性为骨架结合 packages/chakra-ui 中的真实源码与测试用例讲解如何用useFormCreate快速搭建可用的新建记录页面以及如何按业务需求定制标题、按钮、面包屑与整体布局。Create是什么一个无逻辑的页面布局组件正如文档开篇所述Createprovides us a layout to display the page. It does not contain any logic and just adds extra functionalities like action buttons and being able to give titles to the page.Create只负责页面的壳——它把以下元素组合成一个标准的新建页布局顶部标题区默认标题为Create 资源单数名例如 posts 资源显示Create post返回按钮默认使用tabler/icons-react的IconArrowLeft图标面包屑导航默认使用refinedev/chakra-ui自带的Breadcrumb组件底部保存按钮默认使用SaveButton加载中的转圈指示器Spinner与内容区半透明遮罩。逻辑部分表单状态、校验、提交则由你作为 children 传入通常配合refinedev/react-hook-form的useForm一起使用。在 Chakra UI Create 组件源码 中可以看到组件接收并解构了全部定制属性const { children, saveButtonProps: saveButtonPropsFromProps, isLoading, resource: resourceFromProps, footerButtons: footerButtonsFromProps, footerButtonProps, headerButtons: headerButtonsFromProps, headerButtonProps, wrapperProps, contentProps, headerProps, goBack: goBackFromProps, breadcrumb: breadcrumbFromProps, title, } props;其中contentProps用于定制内容区包装元素对应源码第 170 行的Box opacity{isLoading ? 0.5 : undefined} {...contentProps}。完整用法表单 Create 的标准组合文档给出了一个典型的PostCreate页面用useForm拿到formLoading、saveButtonProps、register和表单错误用useSelect拉取categories资源的下拉选项然后把它们全部放进Create中import { Create } from refinedev/chakra-ui; import { FormControl, FormLabel, FormErrorMessage, Input, Select, } from chakra-ui/react; import { useSelect } from refinedev/core; import { useForm } from refinedev/react-hook-form; const PostCreate: React.FC () { const { refineCore: { formLoading }, saveButtonProps, register, formState: { errors }, } useForm(); const { options } useSelect({ resource: categories, }); return ( Create isLoading{formLoading} saveButtonProps{saveButtonProps} FormControl mb3 isInvalid{!!errors?.title} FormLabelTitle/FormLabel Input idtitle typetext {...register(title, { required: Title is required })} / FormErrorMessage{${errors?.title?.message}}/FormErrorMessage /FormControl FormControl mb3 isInvalid{!!errors?.status} FormLabelStatus/FormLabel Select idcontent placeholderSelect Post Status {...register(status, { required: Status is required, })} optionpublished/option optiondraft/option optionrejected/option /Select FormErrorMessage{${errors?.status?.message}}/FormErrorMessage /FormControl FormControl mb3 isInvalid{!!errors?.category} FormLabelCategory/FormLabel Select idcategoryId placeholderSelect Category {...register(category.id, { required: Category is required, })} {options?.map((option) ( option value{option.value} key{option.value} {option.label} /option ))} /Select FormErrorMessage{${errors?.category?.message}}/FormErrorMessage /FormControl /Create ); };要点isLoading{formLoading}提交或初始加载期间显示加载指示器并禁用保存按钮saveButtonProps{saveButtonProps}把表单的提交逻辑直接接到Create默认的保存按钮上无需自己写button onClick{...}资源posts与动作create由路由解析无需显式传入。仓库中真实的 form-chakra-ui-use-form 示例 与文档示例几乎一致额外多了Textarea内容字段、泛型useFormIPost, HttpError, IPost()以及useSelect的pagination: { mode: server }配置可作为直接可运行参考。属性详解titletitle用于设置页面标题。不传时组件默认以Create前缀 资源单数名拼接标题。例如posts资源默认显示Create post。从源码 renderTitle 实现 可以看到默认标题还经过translate处理优先查找${identifier}.titles.create的 i18n 翻译键找不到才回退到Create ${getUserFriendlyName(...)}的默认拼接。传title{false}可以完全隐藏标题传字符串或数字会渲染为Heading传任意ReactNode如自定义组件则原样渲染import { Create } from refinedev/chakra-ui; import { Heading } from chakra-ui/react; const PostCreate: React.FC () { return ( Create title{Heading sizelgCustom Title/Heading} pRest of your page here/p /Create ); };saveButtonPropsCreate默认渲染一个提交表单的保存按钮。若想定制它用saveButtonProps传入 Chakra UIButton支持的任何属性import { Create } from refinedev/chakra-ui; const PostCreate: React.FC () { return ( Create saveButtonProps{{ colorScheme: red }} pRest of your page here/p /Create ); };源码中的合并逻辑值得注意index.tsx 第 49-52 行当isLoading为true时会先注入disabled: true再与你传入的saveButtonProps合并你传入的属性优先级更高const saveButtonProps: SaveButtonProps { ...(isLoading ? { disabled: true } : {}), ...saveButtonPropsFromProps, };默认保存按钮由 SaveButton 提供它调用refinedev/core的useSaveButton()获取本地化标签使用colorSchemegreen配色、IconDeviceFloppy图标并带RefineButtonTestIds.SaveButton测试标识方便 e2e 与单测定位。resourceCreate默认从路由读取资源信息useResourceParams()。若页面路径与资源名不一致例如自定义页面可以显式指定resourceimport { Create } from refinedev/chakra-ui; const CustomPage: React.FC () { return ( Create resourceposts pRest of your page here/p /Create ); };这与共享测试中的行为一致crudCreateTests 专门验证了路由在/custom、显式传resourceposts时仍渲染出Create Post的场景。goBackgoBack用于定制或禁用左上角的返回按钮。传ReactNode会替换默认的IconArrowLeft图标传false或null则完全隐藏按钮import { Create } from refinedev/chakra-ui; import { IconMoodSmile } from tabler/icons-react; const PostCreate: React.FC () { return ( Create goBack{IconMoodSmile /} pRest of your page here/p /Create ); };源码 buttonBack 实现 展示了其内部逻辑当goBackFromProps为false或null时不渲染否则渲染一个aria-labelback的 ghost 图标按钮点击事件绑定useBack()返回的back函数仅在action为create等非 list 场景生效。isLoadingisLoading控制组件的加载状态为true时内容区中央显示Spinner、内容区透明度降为 0.5、保存按钮被禁用见上文saveButtonProps合并逻辑import { Create } from refinedev/chakra-ui; const PostCreate: React.FC () { return ( Create isLoading{true} pRest of your page here/p /Create ); };在实际应用中通常把useForm返回的formLoading直接透传进来如完整示例所示这样初次加载与提交期间会自动出现加载反馈。breadcrumbbreadcrumb用于定制或禁用页面面包屑。默认使用refinedev/chakra-ui的Breadcrumb组件。传null可移除传自定义节点可整体替换import { Create, Breadcrumb } from refinedev/chakra-ui; import { Box } from chakra-ui/react; const PostCreate: React.FC () { return ( Create breadcrumb{ Box borderColorblue borderStyledashed borderWidth2px Breadcrumb / /Box } pRest of your page here/p /Create ); };值得注意的优先级逻辑在源码 index.tsx 第 44-47 行只有未传breadcrumbFromProps时才回退到全局配置useRefineContext()中options.breadcrumb的值。对应的 Chakra 专属测试 验证了breadcrumb{null}时面包屑不渲染。wrapperPropswrapperProps定制最外层包装容器。refinedev/chakra-ui的 Create 外层包装是 Chakra 的Box渲染为卡片风格bgchakra-body-bg、圆角md、内边距px4 py3因此可以接收Box的一切样式属性import { Create } from refinedev/chakra-ui; const PostCreate: React.FC () { return ( Create wrapperProps{{ borderColor: blue, borderStyle: dashed, borderWidth: 2px, }} pRest of your page here/p /Create ); };headerPropsheaderProps定制标题区面包屑 返回按钮 标题所在的行的布局与样式import { Create } from refinedev/chakra-ui; const PostCreate: React.FC () { return ( Create headerProps{{ borderColor: blue, borderStyle: dashed, borderWidth: 2px, }} pRest of your page here/p /Create ); };headerButtonsheaderButtons定制头部按钮区位于标题右侧。它接受React.ReactNode或一个接收{ defaultButtons }的渲染函数——用渲染函数可以保留默认按钮并追加自己的按钮import { Create } from refinedev/chakra-ui; import { Button, HStack } from chakra-ui/react; const PostCreate: React.FC () { return ( Create headerButtons{({ defaultButtons }) ( HStack {defaultButtons} Button colorSchemeredCustom Button/Button /HStack )} pRest of your page here/p /Create ); };从 ActionButtonRenderer 类型 可以看出这种节点或渲染函数的形态是 Refine CRUD 组件的统一约定Create 的头部默认按钮为null源码第 74-80 行因此defaultButtons在这里通常是空。headerButtonPropsheaderButtonProps定制头部按钮区外层包装元素同样是一个Box的样式import { Create } from refinedev/chakra-ui; import { Button } from chakra-ui/react; const PostCreate: React.FC () { return ( Create headerButtonProps{{ borderColor: blue, borderStyle: dashed, borderWidth: 2px, p: 2, }} headerButtons{ Button colorSchemegreen variantoutline Custom Button /Button } pRest of your page here/p /Create ); };footerButtons默认情况下Create底部有一个SaveButton。footerButtons可整体定制底部按钮区同样支持ReactNode或渲染函数渲染函数的入参为{ defaultButtons, saveButtonProps }其中saveButtonProps便于你在自定义按钮上复用表单的保存逻辑import { Create } from refinedev/chakra-ui; import { Button, HStack } from chakra-ui/react; const PostCreate: React.FC () { return ( Create footerButtons{({ defaultButtons }) ( HStack borderColorblue borderStyledashed borderWidth2px p2 {defaultButtons} Button colorSchemered variantsolid Custom Button /Button /HStack )} pRest of your page here/p /Create ); };源码 index.tsx 第 82-89 行 的对应逻辑是footerButtons为函数时调用footerButtons({ defaultButtons: defaultFooterButtons, saveButtonProps })为节点时直接使用节点未传时使用默认的SaveButton {...saveButtonProps} /。footerButtonPropsfooterButtonProps定制底部按钮区外层包装元素的样式import { Create } from refinedev/chakra-ui; const PostCreate: React.FC () { return ( Create footerButtonProps{{ float: right, borderColor: blue, borderStyle: dashed, borderWidth: 2px, p: 2, }} pRest of your page here/p /Create ); };源码级剖析Create 的内部结构阅读 Chakra UI Create 组件源码 可以看清整个组件的 DOM 骨架Box wrapperProps // 卡片式外层 {isLoading Spinner /} // 居中加载指示器 Box headerProps // 头部行space-between 布局 Box minW{200} // 左面包屑 返回按钮 标题 {breadcrumb ?? Breadcrumb /} HStack{buttonBack}{renderTitle()}/HStack /Box Box headerButtonProps // 右headerButtons {headerButtons} /Box /Box Box opacity{isLoading ? 0.5 : undefined} contentProps {children} // 表单内容 /Box Box footerButtonProps // 底部footerButtons {footerButtons} /Box /Box几个值得关注的设计点资源与动作的自动解析组件通过refinedev/core的useResourceParams()拿到{ resource, action, identifier }再配合useUserFriendlyName()把identifier如posts转为用户友好的单数名post拼出默认标题Create post。这就是无需传任何 props 也能正确显示标题的原因。i18n 优先默认标题优先查找${identifier}.titles.create翻译键多语言项目只需在语言包中定义该键即可覆盖默认文案。加载即禁用保存isLoading同时驱动 Spinner、内容半透明和保存按钮禁用三个行为保证提交期间用户不会重复触发。无障碍与测试友好返回按钮带aria-labelback保存按钮带data-testidRefineButtonTestIds.SaveButton与classNameRefineButtonClassNames.SaveButton方便自动化测试与样式覆盖。类型体系一切属性皆有据可查refinedev/chakra-ui的CreateProps定义在 packages/chakra-ui/src/components/crud/types.ts它把 UI 无关的基类与 Chakra UI 具体类型做了泛型绑定export type CreateProps RefineCrudCreateProps SaveButtonProps, // saveButtonProps BoxProps, // headerButtonProps BoxProps, // footerButtonProps StackProps, // header 布局 BoxProps, // headerProps BoxProps // contentProps ;基类RefineCrudCreateProps定义于 refinedev/ui-types 的 crud 类型其中为每个属性都标注了默认值说明例如resource默认从 URL 的:resource读取title默认Create {resource.name}headerButtons默认nullfooterButtons默认SaveButton /isLoading布尔值控制加载态。这意味着所有 UI 集成Ant Design、MUI、Mantine、Chakra UI 等的 Create 组件都遵循同一套属性契约迁移 UI 库时心智模型可以平滑复用。测试验证行为有保障Create的行为由两层测试守护跨 UI 库共享测试packages/ui-tests/src/tests/crud/create.tsxcrudCreateTests(Create)会被每个 UI 库的 Create 组件复用覆盖了渲染 children、默认渲染保存按钮、footerButtons渲染自定义按钮、默认标题为 Create Post、title{false}隐藏标题、使用资源 label 而非 name、自定义 title、自定义 resource 等 8 个场景。Chakra 专属测试packages/chakra-ui/src/components/crud/create/index.spec.tsx验证面包屑的渲染与禁用以及footerButtons渲染函数能收到saveButtonProps并把它正确传给SaveButton通过检查className透传。如果你基于该组件二次开发这两层测试就是现成的行为规范。进阶用 Refine CLI 提取Swizzle组件文档提到Create支持通过Refine CLI的 swizzle 命令弹射到你的项目中再行定制。Refine CLI 位于仓库的 packages/cli执行 swizzle 后会把组件源码复制进你的项目之后你就可以彻底摆脱属性 API 的限制直接修改组件内部结构。适合需要深度定制布局、但不想维护大量 props 的业务场景。小结Create是一个纯布局组件标题、面包屑、返回按钮、保存按钮、加载态一应俱全业务逻辑由 children通常是useForm表单提供11 个定制属性title、saveButtonProps、resource、goBack、isLoading、breadcrumb、wrapperProps、headerProps、headerButtons、headerButtonProps、footerButtons、footerButtonProps足以覆盖从换颜色到整体重排的绝大多数定制需求源码层实现、类型与测试层共享测试、专属测试共同保证了组件的可用性与一致性完整可运行示例可参考 form-chakra-ui-use-form。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考