halara-ui

Halara 组件库

Halara 是一个基于 React 的 UI 组件库，提供了一系列可重用的组件，包括 Address、Button、Image、Input 等。该组件库支持多种模块格式，可以在不同的项目环境中使用。

目录

• 安装
• 使用方式
• 组件列表
• 项目结构
• 开发指南
• 构建产物
• 代码规范
• 依赖项
• 许可证

安装

使用 npm:

npm install halara-ui

使用 yarn:

yarn add halara-ui

使用方式

ES 模块导入 (推荐)

// 导入组件
import { Button, Input, Address } from 'halara-ui';
// 导入样式
import 'halara-ui/style';

// 使用组件
function App() {
  return (
    <div>
      <Button>点击我</Button>
      <Input placeholder="请输入" />
    </div>
  );
}

按需导入

// 只导入所需组件
import Button from 'halara-ui/Button';
// 只导入该组件样式
import 'halara-ui/Button/style';

CommonJS 导入

const { Button, Input } = require('halara-ui');

UMD 格式 (浏览器直接使用)

<!-- 在 HTML 中引入 -->
<link rel="stylesheet" href="https://unpkg.com/halara-ui/style">
<script src="https://unpkg.com/halara-ui"></script>

<script>
  // 使用全局变量 Halara 访问组件
  const { Button, Input } = Halara;
  
  // 使用组件...
</script>

组件列表

组件库目前包含以下组件：

• Address: 地址组件，支持地址输入和选择
• Button: 按钮组件，支持不同样式和状态
• Image: 图片组件，支持懒加载和错误处理
• Input: 输入框组件，支持各种表单输入场景

每个组件都有自己的属性和方法，详细文档请参考各组件的使用说明。

项目结构

halara-ui/
├── dist/                 # 构建产物目录
│   ├── es/               # ES模块格式
│   ├── cjs/              # CommonJS格式
│   └── umd/              # UMD格式
├── src/                  # 源代码目录
│   ├── components/       # 组件源码
│   │   ├── Address/      # 地址组件
│   │   ├── Button/       # 按钮组件
│   │   ├── Image/        # 图片组件
│   │   ├── Input/        # 输入框组件
│   │   └── index.ts      # 组件导出
│   ├── BaseComponents/   # 基础组件
│   ├── less/             # 样式文件
│   ├── store/            # 状态管理
│   └── index.ts          # 主入口文件
├── .storybook/           # Storybook配置
├── eslint.config.js      # ESLint配置
├── .stylelintrc.js       # Stylelint配置
├── .prettierrc.js        # Prettier配置
├── vite.config.ts        # Vite构建配置
└── package.json          # 项目配置

开发指南

环境准备

确保你的环境中安装了 Node.js 22+ 和 yarn。

# 克隆项目
git clone <repository-url>

# 安装依赖
yarn install

# 启动开发服务器
yarn dev

可用脚本

# 开发模式
yarn dev               # 启动开发服务器
yarn storybook         # 启动Storybook组件预览

# 构建
yarn build             # 构建所有格式的组件库
yarn clean             # 清理构建目录

# 代码质量
yarn lint              # 运行所有lint检查
yarn lint:js           # 只检查JS/TS文件
yarn lint:style        # 只检查样式文件
yarn format            # 格式化代码
yarn fix:all           # 自动修复所有可修复的问题

# 发布
yarn publish           # 发布到公共npm仓库

添加新组件

1. 在 src/components 目录下创建新的组件目录
2. 创建组件文件、样式文件和索引文件
3. 在 src/components/index.ts 中导出新组件
4. 编写组件文档和测试用例
5. 运行 yarn build 构建组件库

构建产物

构建后的产物位于 dist 目录，包含三种模块格式：

ES 模块 (dist/es/)

• 现代化的 ES 模块格式
• 支持 tree-shaking
• 包含每个组件的单独目录、JS 文件和 CSS 文件
• 包含 TypeScript 类型定义

CommonJS (dist/cjs/)

• 传统的 CommonJS 格式
• 适用于 Node.js 和旧版打包工具
• 结构与 ES 模块格式相同

UMD (dist/umd/)

• 通用模块定义格式
• 适用于浏览器直接引用
• 包含单一的 JS 文件 (index.js) 和 CSS 文件 (style.css)
• 压缩和优化过的代码

代码规范

项目使用以下工具确保代码质量：

1. ESLint - 代码质量检查

   • 支持 React 和 TypeScript
   • 配置文件: eslint.config.js

2. Stylelint - 样式代码检查

   • 支持 SCSS
   • 配置文件: .stylelintrc.js

3. Prettier - 代码格式化

   • 统一的代码风格
   • 配置文件: .prettierrc.js

代码规范的主要原则：

• 使用单引号
• 使用2个空格缩进
• 行宽限制为100个字符
• 使用尾随逗号
• 避免使用 any 类型
• 遵循组件最佳实践

依赖项

核心依赖

• React: ^17.0.0 || ^18.0.0
• React DOM: ^17.0.0 || ^18.0.0
• classnames: ^2.5.1

开发依赖

• 构建工具: Vite, TypeScript
• 代码质量: ESLint, Stylelint, Prettier
• 组件预览: Storybook
• 其他工具: MobX (状态管理)

详细的依赖列表可以在 package.json 文件中查看。

许可证

MIT © Edwin

---

贡献指南

欢迎提交问题报告和拉取请求。在提交代码前，请确保：

1. 代码通过所有测试和lint检查
2. 保持代码风格一致
3. 更新相关文档
4. 添加必要的测试用例

如有任何问题，请联系项目维护者。