Imtes UI

Appearance

开发指南 ​

本指南将帮助你了解如何参与 Imtes UI 的开发，包括项目结构、开发流程和贡献指南。

项目结构 ​

imtes-labs/
├── packages/                 # 组件库源码
│   ├── components/          # 组件目录
│   │   ├── button/         # 按钮组件
│   │   │   ├── Button.vue  # 组件实现
│   │   │   ├── index.js    # 组件导出
│   │   │   ├── docs.md     # 组件文档
│   │   │   └── mock.js     # 模拟数据
│   │   ├── table/          # 表格组件
│   │   └── index.js        # 组件统一导出
│   ├── styles/             # 样式文件
│   │   ├── base.css        # 基础样式
│   │   ├── index.css       # 主样式文件
│   │   └── index.js        # 样式导出
│   ├── utils/              # 工具函数
│   ├── hooks/              # 组合式函数
│   ├── directives/         # 自定义指令
│   └── index.js            # 主入口文件
├── example/                 # 演示项目
│   ├── src/
│   │   ├── views/          # 演示页面
│   │   ├── router/         # 路由配置
│   │   └── main.js         # 入口文件
│   └── package.json        # 演示项目依赖
├── docs/                    # 文档站点
│   ├── .vitepress/         # VitePress 配置
│   ├── guide/              # 指南文档
│   ├── components/         # 组件文档
│   └── index.md            # 首页
├── lib/                     # CommonJS 构建产物
├── es/                      # ES Module 构建产物
├── vite.config.js          # 开发配置
├── vite.lib.config.js      # 构建配置
└── package.json            # 项目依赖

开发环境搭建 ​

环境要求 ​

  • Node.js >= 16
  • npm >= 7 或 yarn >= 1.22

克隆项目 ​

bash
git clone https://github.com/imtes/ui.git
cd imtes-ui

安装依赖 ​

bash
# 安装根目录依赖
npm install

# 安装演示项目依赖
cd example
npm install

启动开发服务器 ​

bash
# 启动演示项目
cd example
npm run dev

# 启动文档站点
npm run docs:dev

组件开发 ​

创建新组件 ​

  1. 创建组件目录
查看代码
bash
mkdir packages/components/your-component
  1. 创建组件文件
查看代码
vue
<!-- packages/components/your-component/YourComponent.vue -->
<template>
  <div class="im-your-component">
    <slot />
  </div>
</template>

<script setup>
defineOptions({
  name: 'ImYourComponent',
  inheritAttrs: false
})

// 组件逻辑
</script>

<style scoped>
.im-your-component {
  /* 组件样式 */
}
</style>
  1. 创建导出文件
查看代码
javascript
// packages/components/your-component/index.js
import YourComponent from './YourComponent.vue'

YourComponent.install = (app) => {
  app.component(YourComponent.name, YourComponent)
}

export default YourComponent
  1. 添加到组件列表
查看代码
javascript
// packages/components/index.js
import YourComponent from './your-component'

export {
  YourComponent
}
  1. 更新主入口
查看代码
javascript
// packages/index.js
import { YourComponent } from './components'

const components = [
  YourComponent
]

const install = (app) => {
  components.forEach(component => {
    app.component(component.name, component)
  })
}

export {
  YourComponent
}

export default {
  install
}

组件开发规范 ​

命名规范 ​

  • 组件名: 使用 PascalCase，以 Im 开头，如 ImButton
  • 文件名: 使用 PascalCase，如 Button.vue
  • CSS 类名: 使用 BEM 规范，以 im- 开头

代码规范 ​

查看代码
vue
<template>
  <!-- 使用 kebab-case 属性名 -->
  <div 
    class="im-component"
    :class="componentClass"
    v-bind="$attrs"
  >
    <slot />
  </div>
</template>

<script setup>
import { computed } from 'vue'

// 组件选项
defineOptions({
  name: 'ImComponent',
  inheritAttrs: false
})

// Props 定义
const props = defineProps({
  size: {
    type: String,
    default: 'default',
    validator: (value) => ['large', 'default', 'small'].includes(value)
  }
})

// 事件定义
const emit = defineEmits(['change', 'click'])

// 计算属性
const componentClass = computed(() => ({
  [`im-component--${props.size}`]: true
}))

// 方法
const handleClick = (event) => {
  emit('click', event)
}

// 暴露方法
defineExpose({
  focus: () => {
    // 组件方法
  }
})
</script>

<style scoped>
.im-component {
  /* 基础样式 */
}

.im-component--large {
  /* 大尺寸样式 */
}

.im-component--small {
  /* 小尺寸样式 */
}
</style>

继承原则 ​

组件应该继承基础组件的所有功能：

查看代码
vue
<template>
  <!-- 直接透传所有属性和事件 -->
  <el-button v-bind="$attrs">
    <slot />
  </el-button>
</template>

<script setup>
defineOptions({
  name: 'ImButton',
  inheritAttrs: false
})

// 只定义扩展功能，不重复定义基础属性
</script>

组件文档 ​

每个组件都应该包含完整的文档：

markdown
<!-- packages/components/your-component/docs.md -->
# YourComponent 组件

组件描述和用途。

## 基础用法

基础使用示例。

## API

### 属性

| 属性名 | 说明 | 类型 | 默认值 |
|--------|------|------|--------|
| size   | 尺寸 | string | default |

### 事件

| 事件名 | 说明 | 参数 |
|--------|------|------|
| change | 值改变时触发 | (value) |

### 插槽

| 插槽名 | 说明 |
|--------|------|
| default | 默认内容 |

演示页面 ​

为组件创建演示页面：

vue
<!-- example/src/views/your-component.vue -->
<template>
  <div class="p-6 bg-gray-50 min-h-screen">
    <div class="max-w-6xl mx-auto">
      <h1 class="text-3xl font-bold mb-8">YourComponent 组件</h1>
      
      <!-- 基础用法 -->
      <section class="mb-12">
        <div class="bg-white rounded-lg p-6 shadow-sm">
          <h2 class="text-xl font-semibold mb-4">基础用法</h2>
          <ImYourComponent>示例内容</ImYourComponent>
        </div>
      </section>
    </div>
  </div>
</template>

构建和发布 ​

本地构建 ​

bash
# 构建组件库
npm run build

# 构建文档
npm run docs:build

代码检查 ​

bash
# ESLint 检查
npm run lint

# 类型检查（如果使用 TypeScript）
npm run type-check

发布流程 ​

  1. 更新版本号
bash
npm version patch  # 修复版本
npm version minor  # 功能版本
npm version major  # 主要版本
  1. 更新 CHANGELOG

在 CHANGELOG.md 中记录本次更新内容。

  1. 构建和发布
bash
npm run build
npm publish

贡献指南 ​

提交规范 ​

使用 Conventional Commits 规范：

feat: 新增功能
fix: 修复问题
docs: 文档更新
style: 代码格式
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动

示例：

feat(button): 新增 loading 状态
fix(table): 修复分页显示问题
docs: 更新安装指南

Pull Request ​

  1. Fork 项目到你的 GitHub 账号
  2. 创建功能分支：git checkout -b feature/your-feature
  3. 提交更改：git commit -m 'feat: add some feature'
  4. 推送分支：git push origin feature/your-feature
  5. 创建 Pull Request

代码审查 ​

所有代码都需要经过审查才能合并：

  • 确保代码符合项目规范
  • 添加必要的测试
  • 更新相关文档
  • 确保构建通过

常见问题 ​

如何调试组件？ ​

  1. 在本地演示项目中测试组件，或访问 在线演示 查看效果
  2. 使用 Vue DevTools 检查组件状态
  3. 在浏览器开发者工具中调试样式

如何处理样式冲突？ ​

  1. 使用 scoped 样式
  2. 遵循 BEM 命名规范
  3. 使用 CSS 变量进行主题定制

如何优化组件性能？ ​

  1. 使用 v-memo 缓存昂贵的渲染
  2. 合理使用 computed 和 watch
  3. 避免不必要的响应式数据

参考资源 ​

基于 MIT 许可发布

Copyright © 2025 Imtes