概述
主页快捷方式是高频操作的图标磁贴。在 PluginModule.register() 中通过 shortcut store 注册，而不是 AppRegistry。
- 从 @quan-erp/base-frontend 导入 useHomeShortcutStore 与 ShortcutItem
- 在 register() 中调用 useHomeShortcutStore().getState().add
- 用 <ShortcutItem> 包裹图标
- id 在所有插件中唯一（建议 `${metadata.name}/…`）
1. 注册快捷方式
在 frontend/src/index.tsx 的 register() 中调用 add()。
TSXfrontend/src/index.tsx
1import { ShoppingCart } from "lucide-react";
2import { ShortcutItem, useHomeShortcutStore } from "@quan-erp/base-frontend";
3import type { AppRegistryState, PluginModule } from "@quan-erp/shared-types";
4import metadata from "../module.metadata.json" with { type: "json" };
5
6const Plugin: PluginModule = {
7 register(_AppRegistry: AppRegistryState) {
8 useHomeShortcutStore().getState().add({
9 pluginName: metadata.name,
10 id: `${metadata.name}/pos`,
11 displayName: "POS",
12 component: (
13 <ShortcutItem>
14 <ShoppingCart size={25} />
15 </ShortcutItem>
16 ),
17 toLink: `/${metadata.name}/pos`,
18 async onClick() {
19 // optional — dialogs, scans, side effects
20 },
21 });
22 },
23};
24
25export default Plugin;2. 属性
Each add() entry configures one home tile.
- pluginName — 等于 module.metadata.json 的 name
- id — 唯一；推荐 `${metadata.name}/feature`
- displayName — 图标下方文案
- component — 必须用 <ShortcutItem> 包裹
- toLink — 可选路由（如 `/${metadata.name}/pos`）
- onClick — 可选异步处理
3. 导航模式
普通跳转用 toLink；打开对话框/扫码用 onClick。
- toLink 保持在插件路径命名空间下
- 与 AppRegistry.route 路径对齐
TSonClick-only (e.g. scan)
1useHomeShortcutStore().getState().add({
2 pluginName: metadata.name,
3 id: `${metadata.name}/scan`,
4 displayName: "Scan",
5 component: (
6 <ShortcutItem>
7 <ScanIcon size={25} />
8 </ShortcutItem>
9 ),
10 async onClick() {
11 // open scanner / dialog — no toLink required
12 },
13});关键规则
- 只在 register() 中注册 — 不要在页面 mount 时添加
- 缺少 ShortcutItem 会破坏布局
- id 必须全局唯一
- pluginName 必须等于 metadata.name
- 只用于高频操作
检查清单
- Import ShortcutItem + useHomeShortcutStore from @quan-erp/base-frontend
- add() in register() with pluginName, id, displayName, component
- Wrap icon in <ShortcutItem>
- Set toLink and/or onClick
- Verify tile after quan-erp watch and install
常见失败
- 看不到磁贴 — 未 add / pluginName 错误 / 未安装
- 图标布局坏 — 缺少 ShortcutItem
- 点击无效 — 未设 toLink/onClick 或路径不匹配
- 重复 — id 冲突
- 跳转错误 — toLink 与 route 不一致