前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载Configurable是 react-admin 提供的核心可配置性组件把任意子组件包裹进Configurable并提供一个editor编辑组件终端用户即可在配置模式下通过 Inspector 面板实时修改该组件的偏好设置且偏好以唯一preferenceKey持久化到 Store。阅读本文后你将掌握Configurable的完整用法、usePreference/usePreferenceInput的底层机制、Inspector/InspectorButton的接入方式并能够基于仓库源码深入理解其上下文与持久化原理。什么是ConfigurableConfigurable使另一个组件对终端用户可配置。当用户进入配置模式后可以借助 Inspector检查器面板定制该组件的设置。它的典型应用场景包括允许非技术用户在 Dashboard 上调整展示区块的颜色、显隐某些信息块、选择列表要显示的列等。从源码看Configurable本身不负责偏好数据的读写它的职责是三件事见 Configurable.tsx为子组件与编辑组件创建一个共享的PreferenceKeyContext让两侧都能拿到同一个命名空间下的preferenceKey在配置模式下为子组件渲染一个悬浮的设置按钮一个SettingsIconPopover点击后把editor挂载到 Inspector在卸载时清理正在编辑的 editor 状态避免残留。内置的可配置组件部分 react-admin 组件已经具备可配置能力或者说拥有对应的可配置版本DatagridConfigurable让用户自定义表格要显示的列SimpleListConfigurable让用户自定义简单列表的字段SimpleFormConfigurable让用户自定义表单布局PageTitleConfigurable由Title组件内部使用。这些组件的实现均位于packages/ra-ui-materialui/src下例如list/datagrid/DatagridConfigurable.tsx、list/SimpleList/SimpleListConfigurable.tsx、form/SimpleFormConfigurable.tsx与layout/PageTitleConfigurable.tsx。阅读它们的源码是学习如何用Configurable封装自有组件的最佳范本。基本用法用Configurable包裹任意组件并定义它的editor编辑组件即可让用户通过界面定制它。注意每个可配置组件都需要一个唯一的preferenceKey该 key 用于把用户偏好持久化到 Storereact-admin 的本地存储抽象见 useStore 文档。import { Configurable } from react-admin; const ConfigurableTextBlock ({ preferenceKey textBlock, ...props }) ( Configurable editor{TextBlockEditor /} preferenceKey{preferenceKey} TextBlock {...props} / /Configurable );不要忘记向内部的子组件透传 props。Configurable会为preferenceKey创建一个 context使子组件和 editor 都能访问它。从源码实现Configurable.tsx看传入的preferenceKey实际会被加一个preferences.前缀后再存入 Storeconst prefixedPreferenceKey preferences.${preferenceKey};这意味着你传入textBlockStore 中实际的键是preferences.textBlock。同时Configurable只有在PreferencesEditorContext存在即配置模式框架已挂载时才会渲染设置按钮与编辑器相关逻辑若没有该 context它直接返回children即等价于普通组件。editor读写偏好editor 组件负责让用户编辑可配置组件的偏好设置。它通过usePreferencehook 实现读写——这是针对当前preferenceKey做了命名空间的useStore版本import { usePreference } from react-admin; const TextBlockEditor () { const [color, setColor] usePreference(color, #ffffff); // 等价于 // const [color, setColor] useStore(textBlock.color, #ffffff); return ( Box TypographyConfigure the text block/Typography TextField labelColor value{color} onChange{e setColor(e.target.value)} / /Box ); };子组件用同一个usePreferencehook 读取偏好const TextBlock ({ title, content }) { const [color] usePreference(color, #ffffff); return ( Box sx{{ bgcolor: color }} Typography varianth6{title}/Typography Typography{content}/Typography /Box ); };然后在你的应用中直接使用这个可配置组件import { ConfigurableTextBlock } from ./ConfigurableTextBlock; export const Dashboard () ( ConfigurableTextBlock titleWelcome to the administration contentLorem ipsum dolor sit amet, consectetur adipiscing elit. / );usePreference的底层实现在 usePreference.ts 中hook 从PreferenceKeyContext取出当前的preferenceKey然后把它作为useStore键的前缀return useStoreT( preferenceKey key ? ${preferenceKey}.${key} : preferenceKey ?? key, defaultValue );一个值得注意的约束usePreference必须在Configurable组件内部使用。如果脱离该 context 调用它会抛出如下错误源码见 usePreference.tsusePreference cannot be used outside of a Configurable component. Did you forget to wrap your component with ? If you dont want to use Configurable, you can use the useStore hook instead.因此如果你不需要配置能力直接用useStore即可不必强上Configurable。children被包裹的组件被包裹的组件可以是任意依赖usePreference的组件。可配置组件让用户能够定制自己的内容、外观look and feel以及行为。例如下面的TextBlock组件允许终端用户修改前景色与背景色import { usePreference } from react-admin; const TextBlock ({ title, content }) { const [color] usePreference(color, primary.contrastTest); const [bgcolor] usePreference(bgcolor, primary.main); return ( Box sx{{ color, bgcolor }} Typography varianth6{title}/Typography Typography{content}/Typography /Box ); };注意这里的默认值可以是 MUI 的主题色 token如primary.main即偏好未设置时回退到主题默认值。这得益于 Store 的未设置则返回默认值语义只有用户主动修改过偏好Store 中才会存在该键。editor定制编辑界面editor组件应让用户修改子组件的设置——通常通过表单控件完成。当用户进入配置模式并选中某个可配置组件时react-admin 会在 Inspector 面板中渲染对应的editor。editor 组件必须同样使用usePreference来读写指定偏好。例如为上面的TextBlock编写一个允许修改前景色和背景色的简单 editorimport { usePreference } from react-admin; const TextBlockEditor () { const [color, setColor] usePreference(color, primary.contrastTest); const [bgcolor, setBgcolor] usePreference(bgcolor, primary.main); return ( Box TypographyConfigure the text block/Typography TextField labelColor value{color} onChange{e setColor(e.target.value)} / TextField labelBackground Color value{bgcolor} onChange{e setBgcolor(e.target.value)} / /Box ); };用usePreferenceInput延迟提交在实际项目中不建议像上例那样每次输入都立即写入偏好——否则设置可能暂时处于非法值例如输入primary.main的过程中中间态prim是无效的。react-admin 提供了usePreferenceInputhook 解决这个问题。它返回一个包含{ value, onChange, onBlur, onKeyDown }的对象可以直接展开传递给输入组件import { usePreferenceInput } from react-admin; const TextBlockEditor () { const colorField usePreferenceInput(color, primary.contrastTest); const bgcolorField usePreferenceInput(bgcolor, primary.main); return ( Box TypographyConfigure the text block/Typography TextField labelColor {...colorField} / TextField labelBackground Color {...bgcolorField} / /Box ); };usePreferenceInput会在失焦blur或按下 Enter 键时才真正写入偏好。与usePreference一样它使用 context 中的preferenceKey对偏好做命名空间隔离。其内部实现usePreferenceInput.ts维护了一个本地useState作为输入框的临时值onChange只更新本地值空字符串时回退为defaultValue直到onBlur或 Enter 时才调用setValueFromStore提交。一个值得注意的交互细节按 Enter 提交后它还会把焦点移动到表单中的下一个输入项form.elements[index 1]?.focus()方便连续编辑多个设置项。preferenceKey同类型多实例的隔离preferenceKey参数用于指定该配置在用户偏好中存储的键。这允许你在同一页面上拥有多个同类型的可配置组件且各自独立配置。import { Configurable } from react-admin; const ConfigurableTextBlock ({ preferenceKey, ...props }) ( Configurable editor{TextBlockInspector /} preferenceKey{preferenceKey} TextBlock {...props} / /Configurable );然后在应用中为每个组件设置唯一的preferenceKeyimport { ConfigurableTextBlock } from ./ConfigurableTextBlock; export const Dashboard () ( ConfigurableTextBlock preferenceKeytextBlock1 titleWelcome to the administration contentLorem ipsum dolor sit amet, consectetur adipiscing elit. / ConfigurableTextBlock preferenceKeytextBlock2 titleSecurity reminder contentNullam bibendum orci tortor, a posuere arcu sollicitudin ac / / );用户将可以独立定制每一个组件分别对应 Store 中的preferences.textBlock1.*与preferences.textBlock2.*。InspectorButton进入配置模式把InspectorButton加入AppBar即可让用户进入配置模式并打开配置编辑面板import { AppBar, TitlePortal, InspectorButton } from react-admin; const MyAppBar () ( AppBar TitlePortal / InspectorButton / /AppBar );从源码InspectorButton.tsx看这是一个设置了 Tooltip 的IconButton点击时在enable()与disable()之间切换配置模式未开启时调用enable()进入配置模式已开启时调用disable()并清空当前选中的preferenceKey退出。它渲染一个SettingsIcon默认标签文案为ra.configurable.configureMode即Configure mode并支持通过label属性覆盖。配置模式下的交互进入配置模式后对应PreferencesEditorContextProvider中的isEnabled状态每个被Configurable包裹的组件会获得一个外框高亮样式。从 Configurable.tsx 的样式定义可以看到三种状态类RaConfigurable-root基础根样式position: relative; display: inline-blockRaConfigurable-editMode配置模式下使用theme.palette.warning.main渲染 2px 轮廓线hover 时透明度加深RaConfigurable-editorActive当该组件的 editor 正在 Inspector 中显示时轮廓线变为不透明实线。鼠标悬停在处于配置模式的组件上时右上角会出现一个设置图标Popover默认openButtonLabel为ra.configurable.customize点击它即把对应editor挂载到 Inspector 并设为当前选中项。Inspector配置编辑面板react-admin 提供的默认布局Layout已经内置了Inspector组件。只有当你使用自定义布局时才需要手动把Inspector添加到布局中// in src/MyLayout.js import * as React from react; import { Box } from mui/material; import { AppBar, Menu, Sidebar, Inspector } from react-admin; const MyLayout ({ children, dashboard }) ( Box sx{{ display: flex, flexDirection: column, zIndex: 1, minHeight: 100vh, backgroundColor: theme.palette.background.default, position: relative }} Box overflowXauto sx{{ display: flex, flexDirection: column }} AppBar / Box sx{{ display: flex, flexGrow: 1 }} Sidebar Menu hasDashboard{!!dashboard} / /Sidebar Box sx{{ display: flex, flexDirection: column, flexGrow: 2, p: 3, marginTop: 4em, paddingLeft: 5 }} {children} /Box /Box /Box Inspector / /Box ); export default MyLayout;Inspector 的行为细节源码级Inspector 的实现位于 Inspector.tsx它的行为比一个面板要丰富得多面板位置可拖拽且持久化Inspector 默认停靠在屏幕右缘面板位置通过useStore(ra.inspector.position, ...)存储源码 Inspector.tsx用户拖拽后位置会被记住窗口缩放时若面板移出屏幕会自动修正回可视区域内。标题与编辑内容面板顶部显示标题可由useSetInspectorTitle相关机制动态设置内容区域包裹在PreferenceKeyContextProvider value{preferenceKey}中渲染editor若当前没有 editor则回退渲染InspectorRoot。一键重置偏好当存在preferenceKey时面板标题栏会出现删除按钮点击后调用useRemoveItemsFromStore(preferenceKey)清除该组件全部偏好并通过自增version强制重绘 editor使其回到默认值源码 Inspector.tsx。关闭面板点击关闭按钮即调用disable()退出配置模式。状态管理PreferencesEditorContextInspectorButton、Configurable、Inspector三者通过PreferencesEditorContext协同工作。该 context 由 PreferencesEditorContextProvider.tsx 提供核心状态包括状态含义isEnabled是否处于配置模式editor当前 Inspector 中渲染的编辑组件preferenceKey当前被选中的可配置组件的偏好键title/titleOptionsInspector 面板标题path当前配置路径Configurable在点击设置按钮时会以prefixedPreferenceKey带preferences.前缀为 key 克隆editor并调用setEditor、setPreferenceKey见 Configurable.tsx。源码注释说明给 editor 带上key: prefixedPreferenceKey是为了在切换两个同类型但 key 不同的编辑器时强制销毁重建避免useStore延迟一拍而影响 editor 中非受控输入框的使用。测试验证行为即契约Configurable的关键行为都有对应的单元测试覆盖见 Configurable.spec.tsx这些用例同时也是一份很好的行为文档选中组件后显示对应 editor进入配置模式 → 鼠标悬停组件 → 点击设置图标 → Inspector 中渲染Text block编辑器设置显示默认值编辑器打开时输入框的值等于usePreference指定的默认值如#ffffff修改设置立即生效例如切换Show date开关后页面中对应的日期文本消失关闭 Inspector 后设置保留偏好已写入 Store不会随面板关闭而丢失卸载时清理 editor被配置的组件卸载后其 editor 不会残留而卸载另一个可配置组件时当前编辑器的 editor 不受影响。这些测试直接验证了偏好持久化到 Storeeditor 生命周期跟随选中组件等核心承诺可作为你自行封装可配置组件时的参考。小结Configurable是 react-admin 将管理员能力下沉给终端用户的关键基础设施。围绕它你需要掌握四个要素包裹用Configurable editor{...} preferenceKey...包裹目标组件并透传 props读写子组件与 editor 都用usePreference或输入型usePreferenceInput读写偏好键会自动带上preferences.preferenceKey.前缀写入 Store入口通过InspectorButton加入 AppBar让用户进入/退出配置模式载体默认布局已内置Inspector自定义布局需手动挂载该面板组件它负责渲染 editor、重置偏好与持久化面板位置。内置的DatagridConfigurable、SimpleListConfigurable、SimpleFormConfigurable与PageTitleConfigurable分别位于packages/ra-ui-materialui/src/list/datagrid/、list/SimpleList/、form/与layout/目录下是官方提供的可配置组件样板——从它们的源码出发你几乎可以零成本地把可配置能力扩展到任何自研组件上。赞分享前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载相关推荐React Starter Kit终极UI组件库shadcn/ui集成与自定义组件开发完整指南React Starter Kit终极UI组件库shadcn/ui集成与自定义组件开发完整指南 React Starter Kit是一个现代化的单页Web应用后端前端如何通过LLDAP自定义属性实现用户信息扩展完整配置指南如何通过LLDAP自定义属性实现用户信息扩展完整配置指南 LLDAP作为轻量级LDAP实现提供了强大的自定义属性功能让您能够灵活扩展用户和组的信息结构。无后端认证鉴权MCP Inspector 自定义主机与端口配置终极指南还在为MCP服务器测试时的端口冲突烦恼本文将为你揭秘ModelContextProtocol Inspector的自定义配置技巧助你轻松解决网络配置难题开发工具MCP Clients调试器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考