H-Components 组件库

安装

npm install h-components
# 或
yarn add h-components
# 或
pnpm add h-components

使用

全局注册（推荐）

import { createApp } from 'vue'
import App from './App.vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import HComponents from 'h-components'
import 'h-components/styles/index.scss'  // 重要：必须导入样式

const app = createApp(App)
app.use(ElementPlus)
app.use(HComponents)  // 现在不会有类型警告了
app.mount('#app')

按需导入

<template>
  <div>
    <HButton type="primary">按钮</HButton>
    <HInput v-model="value" placeholder="请输入" />
  </div>
</template>

<script setup lang="ts">
import { HButton, HInput } from 'h-components'
import 'h-components/styles/index.scss'  // 重要：必须导入样式

const value = ref('')
</script>

Hooks 使用

<template>
  <div>
    <HButton @click="resetForm">重置表单</HButton>
    <HInput v-model="formData.name" placeholder="姓名" />
    <HInput v-model="formData.email" placeholder="邮箱" />
  </div>
</template>

<script setup lang="ts">
import { useResetFormRef, useComRef } from 'h-components'

// 使用 useResetFormRef 管理表单状态
const initialFormData = { name: '', email: '' }
const [formData, resetForm] = useResetFormRef(initialFormData)

// 使用 useComRef 管理组件引用
const buttonRef = useComRef<HTMLElement>()
</script>

编辑器自动导入配置

重要：必须配置以下内容才能实现自动导入

1. TypeScript 配置 (tsconfig.json)

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "types": ["vue", "h-components"],
    "typeRoots": [
      "./node_modules/@types",
      "./node_modules/h-components/components"
    ]
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "node_modules/h-components/components/global.d.ts",
    "node_modules/h-components/components/auto-imports.d.ts"
  ]
}

2. VSCode 配置 (.vscode/settings.json)

{
  "typescript.preferences.includePackageJsonAutoImports": "on",
  "typescript.suggest.autoImports": true,
  "typescript.preferences.importModuleSpecifier": "relative"
}

3. Vite 配置 (vite.config.ts) - 可选

import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      'h-components': 'h-components/components'
    }
  },
  optimizeDeps: {
    include: ['h-components']
  }
})

自动导入使用示例

配置完成后，你可以直接在模板中使用组件和 hooks，无需手动导入：

<template>
  <div>
    <!-- 编辑器会自动提示这些组件 -->
    <HButton type="primary">按钮</HButton>
    <HInput v-model="value" placeholder="输入框" />
    <HTable :data="tableData" :columns="columns" />
    <HDialog v-model="dialogVisible" title="对话框">
      对话框内容
    </HDialog>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 编辑器会自动提示这些 hooks
const [formData, resetForm] = useResetFormRef({ name: '', email: '' })
const buttonRef = useComRef<HTMLElement>()

const value = ref('')
const dialogVisible = ref(false)
const tableData = ref([])
const columns = ref([])
</script>

包文件结构

npm 包包含以下文件：

h-components/
├── components/
│   ├── **/*.ts          # TypeScript 源文件
│   ├── **/*.d.ts        # 类型声明文件
│   ├── **/*.vue         # Vue 组件文件
│   ├── **/*.scss        # 样式文件
│   ├── index.ts         # 主入口文件
│   ├── global.d.ts       # 类型声明入口
│   ├── auto-imports.d.ts # 自动导入配置
│   ├── global.d.ts      # 全局类型声明
│   ├── package.json     # 组件包配置
│   ├── tsconfig.json    # TypeScript 配置
│   └── README.md        # 使用说明
├── package.json         # 主包配置
├── .npmrc              # npm 配置
└── README.md           # 主说明文档

可用组件

• HButton - 按钮组件
• HInput - 输入框组件
• HSelect - 选择器组件
• HTable - 表格组件
• HForm - 表单组件
• HDialog - 对话框组件
• HDrawer - 抽屉组件
• HPagination - 分页组件
• HDatePicker - 日期选择器
• HTimePicker - 时间选择器
• HCheckbox - 复选框组件
• HRadio - 单选框组件
• HSwitch - 开关组件
• HSlider - 滑块组件
• HRate - 评分组件
• HColorPicker - 颜色选择器
• HAvatar - 头像组件
• HMap - 地图组件
• HTooltip - 文字提示组件
• HExport - 导出组件
• HDelete - 删除组件
• HDescriptions - 描述列表组件
• HCascader - 级联选择器
• HTransfer - 穿梭框组件
• HTreeSelect - 树选择器
• HVirtualizedSelect - 虚拟化选择器
• HAutocomplete - 自动完成组件
• HInputNumber - 数字输入框
• HTimeSelect - 时间选择
• HTimeSelectRange - 时间范围选择
• HDateTimePicker - 日期时间选择器
• HFormGroup - 表单组组件
• HFormRender - 表单渲染组件
• HContainer - 容器组件
• HCurd - CRUD 组件
• HCurdTable - CRUD 表格组件
• HDynamicTable - 动态表格组件

可用 Hooks

• useComRef - 组件引用管理 Hook
• useResetFormRef - 表单重置 Hook

useComRef

用于管理组件引用的 Hook。

import { useComRef } from 'h-components'

// 使用示例
const buttonRef = useComRef<HTMLElement>()

useResetFormRef

用于管理表单状态和重置功能的 Hook。

import { useResetFormRef } from 'h-components'

// 使用示例
const initialData = { name: '', email: '' }
const [formData, resetForm] = useResetFormRef(initialData, () => {
  console.log('表单已重置')
})

类型支持

本组件库提供完整的 TypeScript 类型支持，包括：

• 组件 Props 类型定义
• 事件类型定义
• 插槽类型定义
• 自动导入支持
• Vue 插件类型支持
• Hooks 类型支持

样式

组件库使用 SCSS 编写样式，支持主题定制。重要：必须导入样式文件：

import 'h-components/styles/index.scss'

故障排除

类型警告 "Argument of type ... is not assignable to parameter of type Plugin"

解决方案：

1. 确保导入了样式文件：import 'h-components/styles/index.scss'
2. 确保使用的是最新版本的组件库
3. 重启 TypeScript 服务（VSCode: Cmd+Shift+P -> "TypeScript: Restart TS Server"）

编辑器不提示组件或 Hooks

1. 检查 TypeScript 配置：确保 tsconfig.json 中包含了类型声明文件
2. 重启 TypeScript 服务：VSCode 中按 Cmd+Shift+P，输入 "TypeScript: Restart TS Server"
3. 检查安装：确保正确安装了组件库 npm install h-components
4. 检查版本：确保使用的是最新版本的组件库

类型错误

1. 检查 types 字段：确保 tsconfig.json 中的 types 字段包含了 h-components
2. 检查 typeRoots：确保 typeRoots 配置正确指向组件库目录
3. 检查 include 字段：确保 include 字段包含了必要的类型声明文件

样式不生效

1. 导入样式：确保导入了样式文件 import 'h-components/styles/index.scss'
2. 检查构建工具：确保构建工具（Vite/Webpack）正确配置了 SCSS 处理

自动导入不工作

1. 检查 VSCode 设置：确保 .vscode/settings.json 配置正确
2. 检查文件路径：确保 include 字段中的路径正确
3. 重启编辑器：有时候需要完全重启 VSCode

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm type-check

# 检查包文件
pnpm check-package

发布

# 构建项目
pnpm build

# 发布到 npm
npm publish

发布时会自动包含以下文件：

• 所有 TypeScript 源文件
• 所有类型声明文件
• 所有 Vue 组件文件
• 所有样式文件
• 配置文件（package.json, tsconfig.json 等）
• 文档文件（README.md）