giime-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Giime 组件库使用规范

Giime Component Library Usage Specification

Giime 是基于 Element Plus 扩展和增强的内部组件库，所有

el-

组件都有对应的

gm-

版本。未列出的

gm-*

组件与

el-*

行为一致，可直接替换使用。

Giime is an internal component library extended and enhanced based on Element Plus. All

el-

components have corresponding

gm-

versions. Unlisted

gm-*

components have the same behavior as

el-*

components and can be directly replaced for use.

使用原则

Usage Principles

优先 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
```
。

Prioritize Giime:
```
el-button
```
→
```
gm-button
```
,
```
el-table
```
→
```
gm-table
```
, and so on. Giime unifies default behaviors on the basis of Element Plus (such as automatic loading, default filterable), which can reduce repeated configuration when used directly.
Special Requirements: You can use native Element Plus components when Giime cannot meet your needs.
Legacy Code Compatibility: Keep old code as it is, and write new code in accordance with this specification.
Use
GmConfirmBox
for secondary confirmation: Use
```
GmConfirmBox
```
for dangerous operations such as deletion, which automatically handles the loading and disabled state of the confirmation button to avoid duplicate submissions.
Use
GmCopy
for copy functions:
```
GmCopy
```
automatically handles clipboard API compatibility and prompts success/failure, no need to write try-catch manually.
Use
GmMessage
for message prompts:
```
GmMessage
```
merges identical messages by default (
```
grouping: true
```
), which avoids a large number of repeated prompts popping up in a short time, and provides a better experience than
```
ElMessage
```
.

核心增强特性（gm-* vs el-*）

Core Enhancement Features (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
不同。

The following components have enhanced behaviors compared to Element Plus, you need to understand the differences when using them:

Component	Enhancement Content
`gm-button`	Automatically handles loading for async `@click` ; automatically sets type='info' when disabled; automatic Clarity event tracking
`gm-select`	Default `filterable: true` ; recommended to use `:options` to pass in options
`gm-cascader`	Default `filterable: true`
`gm-table`	Added `tableId` attribute (injects TableCtx); default `scrollbarAlwaysOn: true`
`gm-upload`	Supports `v-model:fileList` two-way binding
`gm-image`	Added download progress, default toolbar (zoom/rotate/download), `download()` method
`gm-image-viewer`	Same as `gm-image` , added download progress and default toolbar
`gm-popover`	Added `before-enter` / `before-leave` / `after-enter` / `after-leave` events
`GmMessage`	Default `grouping: true` (merge identical messages); supports global `plain` configuration
`GmMessageBox`	Alert disables Esc and mask closing by default; confirm/prompt shows cancel button by default
`GmConfirmBox`	Secondary confirmation pop-up, automatically handles confirmation button loading and disabled state
`GmCopy`	Copy to clipboard, automatically prompts success/failure

Note:
gm-select-v2
does not enable
filterable
by default, which is different from
gm-select
.

常用代码模式

Common Code Patterns

二次确认删除

Secondary Confirmation for Deletion

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

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

异步按钮（自动 loading）

Async Button (Automatic Loading)

绑定异步函数即可，无需手动管理 loading 状态。当按钮仅执行

emit

而不返回 Promise 时，不会触发自动 loading：

vue

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

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

Just bind an async function, no need to manually manage the loading state. When the button only executes

emit

and does not return a Promise, automatic loading will not be triggered:

vue

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

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

选择器（:options 写法）

Selector (:options Syntax)

vue

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

vue

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

复制到剪切板

Copy to Clipboard

GmCopy(text);

GmCopy(text);

获取详细文档

Get Detailed Documentation

使用具体组件、Hook 或工具函数时，通过

giime-docs

MCP 获取详细用法：

调用
```
get-giime-docs-sidebar
```
获取完整目录（包含所有组件/Hook/工具函数的链接）
调用
```
get-giime-component-doc({ link })
```
获取对应的 Markdown 文档

如果

giime-docs

MCP 未配置，参考 mcp-setup.md 进行安装。

When using specific components, Hooks or utility functions, get detailed usage through the

giime-docs

MCP:

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

If the

giime-docs

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