如何开发 Halo 仪表盘组件：从注册到拖进 12 列网格

如何开发 Halo 仪表盘组件从注册到拖进 12 列网格【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/halo打开 Halo 的控制台仪表盘上摆着文章统计、待审评论、快捷操作这些格子——想再加一个展示自己业务数据的面板该从哪下手本文带你走一遍 Halo 仪表盘组件的完整链路读完你能写一个自己的组件把它注册进系统、拖进网格刷新页面后它就出现在仪表盘上。地图先行组件都放在哪整个仪表盘模块只占一个目录ui/console-src/modules/dashboard。可以按四个角色来认Dashboard.vue只读视图把保存好的布局画成 12 列网格DashboardDesigner.vue设计器拖拽、缩放、切换断点lg 1200 / md 996 / sm 768 / xs 480列数对应 12 / 12 / 6 / 4改完存回偏好widgets/内置组件的注册表加各自的 Vue 实现文章、评论、用户、iframe、快捷操作等 11 个预设components/卡片外壳WidgetCard、组件市场弹层、配置表单弹层这些公共件。先看懂链路一个格子是怎么被画出来的布局不是写死在前端代码里的。composables/use-dashboard-widgets-fetch.ts会去读当前用户的偏好group 为dashboard-widgets拿不到就用widgets/defaults.ts里的默认布局。所以布局数据本质是一串「id 坐标」x/y/w/h 描述它在网格里的位置和大小id 才是找到真正组件的钥匙。渲染时链路很短Dashboard.vue把「内置组件定义」和「插件贡献的组件定义」拼成一个列表通过provide往下传每个格子由WidgetViewItem.vue负责它用 item 里的 id 查表查到谁就画谁component :isgetWidgetDefinition(item.id)?.component :configitem.config /上面三行就是渲染核心按 id 查出组件定义动态渲染出来。剩下的都是外层grid-item在管——权限校验、行列坐标、minW/minH 这些都不用你操心。动手写一个做什么、为什么生效、怎么验证做什么。在widgets/presets/下新建一个 Vue 单文件组件比如MyWidget.vueUI 用现成的WidgetCard包一层即可。然后在widgets/index.ts的internalWidgetDefinitions数组里加一条记录{ id: core:my:widget, component: markRaw(MyWidget), group: core.dashboard.widgets.groups.other, defaultSize: { w: 3, h: 3, minW: 2, minH: 2 }, },这条注册信息告诉系统三件事组件是哪个markRaw防止响应式代理干扰组件引用、默认占几列几行、归到哪个分组。需要用户可配置项的话再加一个configFormKitSchema里面就是普通的 FormKit 表单字段设计器里会自动生成配置弹窗。为什么生效。回到上一条的链路仪表盘按 id 查表。你的新 id 一旦进了availableWidgetDefinitions设计器的组件市场和视图的渲染就都能认得它。id 拼错或重复结果不是报错而是那一格安静地空白——排查时先核对 id 是最快的一步。怎么验证。在ui目录跑make dev起本地控制台进仪表盘设计器打开组件市场你的组件出现在列表里说明注册成功。拖到网格上、调好大小、点保存再回到仪表盘主页面刷新——布局存在你的用户偏好里只读视图按当前断点取对应布局新格子就该出现了。进阶需要让插件把组件装进仪表盘如果你的组件是随控制台一起发布的上面就够用了这段可以直接跳过。如果你在做插件别去改核心代码——在插件的definePlugin里声明扩展点console:dashboard:widgets:create返回和你手写的一模一样的定义数组即可。控制台挂载时use-dashboard-extension-point.ts会遍历所有插件模块把大家返回的定义收拢起来并给每个 id 自动加上插件名前缀防止撞车。最后这批定义和内置列表拼在一起走完全相同的渲染流程。同一套扩展点模式在别处也能见到比如编辑器工具栏和工具箱里插进自定义条目机制和仪表盘完全一致看懂一处其余就都通了。上线 Checklist✅ id 全局唯一且与布局里保存的 id 严格一致✅defaultSize的 w 值不超过 12那是列数上限minW/minH 给合理下限✅ 需要权限控制时声明了permissions无权限用户不会看到该格子✅ 界面上的文案都走了 i18n key并同步补进 locale 文件✅cd ui make build打包通过make lint无报错✅ 重启 Halo 服务加载新 UI 资源后在仪表盘和设计器里各检查一遍动手吧注册表里加一条、设计器里拖一下你的第一个自定义仪表盘组件就上线了 【免费下载链接】haloHalo 是一款强大易用的开源建站工具从个人博客、知识库到企业官网、在线商城Halo 都能助您轻松实现一站式满足您的多样化建站需求。项目地址: https://gitcode.com/GitHub_Trending/ha/halo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考