Giime 组件库使用规范
Giime 是基于 Element Plus 扩展和增强的内部组件库，所有 el- 组件都有对应的 gm- 版本。未列出的 gm-* 组件与 el-* 行为一致，可直接替换使用。
使用原则
- 优先 Giime：
el-button→gm-button，el-table→gm-table，以此类推。Giime 在 Element Plus 基础上统一了默认行为（如自动 loading、默认 filterable），直接使用可以减少重复配置。 - 特殊需求：Giime 无法满足时可用 Element Plus 原生组件。
- 旧代码兼容：旧代码保持原样，新代码按本规范编写。
- 二次确认用
GmConfirmBox：删除等危险操作使用GmConfirmBox，它会自动处理确认按钮的 loading 和禁用状态，避免重复提交。 - 复制用
GmCopy：GmCopy自动处理剪切板 API 兼容性并提示成功/失败，无需手写 try-catch。 - 消息提示用
GmMessage：GmMessage默认合并相同消息（grouping: true），避免短时间内弹出大量重复提示，体验优于ElMessage。
核心增强特性（gm-* vs el-*）
以下组件相对于 Element Plus 有增强行为，使用时需了解差异：
| 组件 | 增强内容 |
|---|---|
gm-button | 异步 @click 自动处理 loading；disabled 时自动 type='info'；自动 Clarity 事件追踪 |
gm-select | 默认 filterable: true；推荐使用 :options 传入选项 |
gm-cascader | 默认 filterable: true |
gm-table | 新增 tableId 属性（注入 TableCtx）；默认 scrollbarAlwaysOn: true |
gm-upload | 支持 v-model:fileList 双向绑定 |
gm-image | 新增下载进度、默认工具栏（缩放/旋转/下载）、download() 方法 |
gm-image-viewer | 同 gm-image，新增下载进度和默认工具栏 |
gm-popover | 新增 before-enter/before-leave/after-enter/after-leave 事件 |
GmMessage | 默认 grouping: true（相同消息合并）；支持全局 plain 配置 |
GmMessageBox | alert 默认禁止 Esc 和遮罩关闭；confirm/prompt 默认显示取消按钮 |
GmConfirmBox | 二次确认弹窗，自动处理确认按钮 loading 和禁用 |
GmCopy | 复制到剪切板，自动提示成功/失败 |
注意：gm-select-v2未默认开启filterable，与gm-select不同。
常用代码模式
二次确认删除
const handleDelete = () => {
GmConfirmBox({ message: '是否确认删除？' }, async () => {
await deleteItem();
GmMessage.success('删除成功');
});
};异步按钮（自动 loading）
绑定异步函数即可，无需手动管理 loading 状态：
<gm-button @click="handleSubmit">提交</gm-button>const handleSubmit = async () => {
await submitForm();
GmMessage.success('提交成功');
};gm-button 的自动 loading 依赖 @click 返回 Promise。$emit() 是同步的、不返回 Promise，不会触发自动 loading。子组件中的按钮需要执行父组件的异步操作时，使用 props 回调函数代替 emit：
<!-- ❌ emit 不返回 Promise，按钮无 loading -->
<gm-button @click="$emit('delete', row.id)">删除</gm-button>
<!-- ✅ props 回调返回 Promise，按钮自动 loading -->
<gm-button @click="onDelete(row.id)">删除</gm-button>// 子组件：用 props 接收异步回调
defineProps<{
onDelete: (id: string) => Promise<void>;
}>();
// 父组件：传入异步函数
// <ChildComponent :on-delete="handleDelete" />选择器（:options 写法）
<gm-select v-model="form.status" clearable :options="statusOptions" />复制到剪切板
GmCopy(text);获取详细文档
使用具体组件、Hook 或工具函数时，通过 giime-docs MCP 获取详细用法：
- 调用
get-giime-docs-sidebar获取完整目录（包含所有组件/Hook/工具函数的链接） - 调用
get-giime-component-doc({link})获取对应的 Markdown 文档
如果 giime-docs MCP 未配置，参考 mcp-setup.md 进行安装。