hgj-ui-components 组件库使用指南

LLM 使用指令（必读）

1. 强制触发：当任务涉及任何 el- 前缀组件或 @hgj/element-plus 时，必须调用并遵循本文档。
2. 严禁外参：标准组件（el-xxx）的 API 严禁使用 Element Plus 开源版的记忆，必须以本文档和源码类型定义为准。
3. 标记识别：
   • 🔧 = 本库独有属性（开源版不存在）
   • ⚠️ = 默认值/行为与 Element Plus 开源版不同
   • 🔄 = 用法模式与开源版不同（如属性回调替代事件）
4. 未知属性：当需要使用的属性未在本文档列出时，必须查阅组件库包源码类型定义 node_modules/@hgj/element-plus/es/components/<组件名(移除el-前缀)>/index.d.ts 进行查询，不得编造。

库概述

hgj-ui-components（包名 @hgj/element-plus，CSS 变量前缀 --hep-*）是海管家内部维护的 Vue 3 组件库，全局注册名统一为 ElXxx，模板中使用 。

重要警告：本库为内部独立维护的组件库，虽然大量组件名称与 Element Plus 开源版相同，但 API、默认值、行为均已发生显著变更。编写代码时严禁参考外部 Element Plus 开源文档，必须以本文档和类型定义为准。

自定义组件特别警告

以下 9 个组件是自定义或二次封装的，API 与库内标准组件差异极大，不可凭记忆编造：

高频业务场景速查

安装与导入（精简）

pnpm add @hgj/element-plus

注意：由于组件库存储在内部私有仓库项目中，因此需要在项目根目录的.npmrc为包管理器(npm或pnpm)配置registry:

# @hgj registry 指向公司私有库
@hgj:registry=http://nexus.hgj.net/repository/npm-internal/

推荐自动导入（安装 unplugin-vue-components + unplugin-auto-import + @hgj/element-plus-import-resolver）：

import HElementPlusResolver from '@hgj/element-plus-import-resolver'

export default defineConfig({
  plugins: [
    AutoImport({ resolvers: [HElementPlusResolver()] }),
    Components({ resolvers: [HElementPlusResolver()] }),
  ],
})

TypeScript Volar 支持：tsconfig.json 中加 "types": ["@hgj/element-plus/global"]

全局配置：通过 ElConfigProvider 传入 size、zIndex、nas（NasFile 依赖 nas.env）

详细配置（主题、国际化、Nuxt、手动导入）见 references/setup.md。

完整组件索引

以下标准组件虽然名称与 Element Plus 开源版相同，但 API、默认值和行为已发生显著变更，不应参考外部文档，请以本文档为准。 属性表中：🔧 = 本库独有属性；⚠️ = 默认值与开源版不同；🔄 = 用法模式与开源版不同。

自定义组件以 🔧 标记，API 与标准组件差异较大，务必查阅独立文档。

Basic 基础

文档：references/components-basic.md

Form 表单

文档：references/components-form.md

Data 数据展示

文档：references/components-data.md

Navigation 导航

文档：references/components-navigation.md

Feedback 反馈

文档：references/components-feedback.md

Auxiliary 辅助

文档：references/components-auxiliary.md

Layout 布局

文档：references/components-layout.md

功能关键词反查

信息检索指引

当需要查询某个组件的详细 API 时：

1. 自定义组件 — 查阅 references/.md（如 x-table.md、tabs-pro.md）
2. 标准组件 — 在上文索引中确认类别，再读对应 references/components-*.md
3. 业务场景 — 查阅 references/scene-*.md 了解跨组件组合用法
4. 类型定义 — 在源码 packages/components//src/.ts 中查看
5. 源码实现 — 当文档和类型定义都不足以解答时

Reference 文件导航