giime-components

Giime Component Library Usage Guidelines

Giime is an internal component library extended and enhanced based on Element Plus. All el- components have corresponding gm- versions. Unlisted gm-* components behave the same as el-* and can be used as direct replacements.

Usage Principles

1. Prefer Giime：el-button → gm-button，el-table → gm-table, and so on. Giime unifies default behaviors on top of Element Plus (such as automatic loading and default filterable), so using it directly reduces repeated configuration.
2. Special Requirements: When Giime cannot meet the need, native Element Plus components may be used.
3. Legacy Code Compatibility: Legacy code remains as is; new code is written according to these guidelines.
4. Use GmConfirmBoxfor secondary confirmation: For dangerous operations such as deletion, use GmConfirmBox, which automatically handles the loading and disabled state of the confirm button to avoid duplicate submissions.
5. Use GmCopy：GmCopy for copying, which automatically handles clipboard API compatibility and prompts success/failure, with no need to write try-catch manually.
6. Use GmMessage：GmMessage for message prompts, which by default merges identical messages (grouping: true), avoiding a large number of duplicate prompts popping up in a short time, providing a better experience than ElMessage。

Core Enhanced Features (gm-* vs el-*)

The following components haveenhanced behaviorrelative to Element Plus, and the differences need to be understood when using them:

Component	Enhancement
gm-button	For async @click , automatically handles loading; automatically sets type='info' when disabled; automatic Clarity event tracking
gm-select	Default filterable: true; recommended to use :options to pass options
gm-cascader	Default filterable: true
gm-table	Newly added tableId property (injects TableCtx); default scrollbarAlwaysOn: true
gm-upload	Supports v-model:fileList two-way binding
gm-image	New download progress, default toolbar (zoom/rotate/download),download() method
gm-image-viewer	Same as gm-image, with newly added download progress and default toolbar
gm-popover	Newly added before-enter/before-leave/after-enter/after-leave event
GmMessage	Default grouping: true(merges identical messages); supports global plain configuration
GmMessageBox	alert disables Esc and mask close by default; confirm/prompt show a cancel button by default
GmConfirmBox	Secondary confirmation dialog, automatically handles confirm button loading and disabled state
GmCopy	Copy to clipboard, automatically prompts success/failure

Note：gm-select-v2 is not enabled by default for filterable, unlike gm-select .

Common Code Patterns

Secondary Confirmation Delete

const handleDelete = () => {
  GmConfirmBox({ message: '是否确认删除？' }, async () => {
    await deleteItem();
    GmMessage.success('删除成功');
  });
};

Async Button (Automatic Loading)

Just bind an async function; there is no need to manually manage the loading state:

<gm-button @click="handleSubmit">提交</gm-button>

const handleSubmit = async () => {
  await submitForm();
  GmMessage.success('提交成功');
};

gm-button 's automatic loading depends on @click returning a Promise.$emit() is synchronous and does not return a Promise, so it will not trigger automatic loading. When a button in a child component needs to execute the parent component's async operation, use a props callback function instead of 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" />

Selector (:options syntax)

<gm-select v-model="form.status" clearable :options="statusOptions" />

Copy to clipboard

GmCopy(text);

Get detailed documentation

When using a specific component, Hook, or utility function, get detailed usage via giime-docs MCP:

1. Call get-giime-docs-sidebar to get the full directory (including links to all components/Hooks/utility functions)
2. Call get-giime-component-doc({ link }) to get the corresponding Markdown documentation

If giime-docs MCP is not configured, refer to mcp-setup.md for installation.