@boom_pk/lowcode-barcode-component/README.md

阿里低代码引擎条形码组件

# 阿里低代码引擎条形码组件

一个专为阿里低代码引擎开发的条形码生成组件，支持多种条形码格式，配置灵活，使用简单。

## ✨ 特性

- 🎯 **多格式支持** - 支持 CODE128、CODE39、EAN13、EAN8、UPC 等主流条形码格式
- 🎨 **高度可配置** - 支持宽度、高度、颜色、字体等多种样式配置
- 📱 **响应式设计** - 适配各种设备尺寸
- 🔧 **低代码友好** - 完全适配阿里低代码引擎的组件规范
- ⚡ **高性能** - 基于 Canvas 渲染，性能优异
- 🛡️ **类型安全** - 完整的 TypeScript 支持

## 📦 安装

```bash
npm install @your-org/barcode-component jsbarcode
```

## 🚀 快速开始

### 在低代码引擎中使用

```javascript
import { BarcodeComponent, BarcodeComponentMeta } from '@your-org/barcode-component';

// 注册组件到设计器
designer.registerComponent(BarcodeComponent, BarcodeComponentMeta);
```

### 在 React 项目中直接使用

```jsx
import BarcodeComponent from '@your-org/barcode-component';

function App() {
  return (
    <BarcodeComponent
      value="HELLO123456"
      format="CODE128"
      width={2}
      height={100}
      displayValue={true}
      fontSize={20}
      background="#ffffff"
      lineColor="#000000"
    />
  );
}
```

## 📋 API 参考

### 基础属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `value` | `string` | `'SAMPLE123'` | 条形码内容 |
| `format` | `string` | `'CODE128'` | 条形码格式 |
| `width` | `number` | `2` | 条形码宽度系数 |
| `height` | `number` | `100` | 条形码高度 |

### 文本属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `displayValue` | `boolean` | `true` | 是否显示文本 |
| `fontSize` | `number` | `20` | 字体大小 |
| `textAlign` | `'left' \| 'center' \| 'right'` | `'center'` | 文本对齐方式 |
| `textPosition` | `'top' \| 'bottom'` | `'bottom'` | 文本位置 |

### 样式属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `background` | `string` | `'#ffffff'` | 背景颜色 |
| `lineColor` | `string` | `'#000000'` | 条形码颜色 |
| `margin` | `number` | `10` | 整体边距 |
| `marginTop` | `number` | `10` | 上边距 |
| `marginBottom` | `number` | `10` | 下边距 |
| `marginLeft` | `number` | `10` | 左边距 |
| `marginRight` | `number` | `10` | 右边距 |

## 🔧 支持的条形码格式

| 格式 | 说明 | 适用场景 |
|------|------|----------|
| `CODE128` | 通用编码，支持完整 ASCII 字符集 | 物流、库存管理 |
| `CODE39` | 工业标准，支持数字、字母和部分符号 | 工业、军用标识 |
| `EAN13` | 欧洲商品条码标准（13位） | 商品零售 |
| `EAN8` | 欧洲商品条码标准（8位） | 小商品 |
| `UPC` | 美国商品条码标准 | 北美零售 |
| `CODE128A` | CODE128 子集 A | 控制字符 |
| `CODE128B` | CODE128 子集 B | 大小写字母和数字 |
| `CODE128C` | CODE128 子集 C | 纯数字，压缩编码 |

## 🎨 使用示例

### 基础用法

```jsx
// 简单的商品条码
<BarcodeComponent
  value="1234567890123"
  format="EAN13"
/>

// 自定义样式的条码
<BarcodeComponent
  value="HELLO-WORLD"
  format="CODE128"
  width={3}
  height={120}
  background="#f0f0f0"
  lineColor="#333333"
  fontSize={24}
/>
```

### 高级配置

```jsx
// 完整配置的条码
<BarcodeComponent
  value="PRODUCT-001"
  format="CODE39"
  width={2.5}
  height={80}
  displayValue={true}
  fontSize={16}
  textAlign="center"
  textPosition="bottom"
  background="#ffffff"
  lineColor="#000000"
  margin={15}
  marginTop={10}
  marginBottom={20}
  marginLeft={10}
  marginRight={10}
/>
```

### 动态条码

```jsx
function DynamicBarcode() {
  const [barcodeValue, setBarcodeValue] = useState('SAMPLE123');
  const [format, setFormat] = useState('CODE128');
  
  return (
    <div>
      <input
        type="text"
        value={barcodeValue}
        onChange={(e) => setBarcodeValue(e.target.value)}
        placeholder="输入条码内容"
      />
      <select value={format} onChange={(e) => setFormat(e.target.value)}>
        <option value="CODE128">CODE128</option>
        <option value="CODE39">CODE39</option>
        <option value="EAN13">EAN13</option>
      </select>
      <BarcodeComponent
        value={barcodeValue}
        format={format}
        width={2}
        height={100}
      />
    </div>
  );
}
```

## 🏗️ 开发指南

### 本地开发

```bash
# 克隆项目
git clone <your-repo-url>
cd barcode-component

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 构建打包

```bash
# 构建所有版本
npm run build

# 构建 CommonJS 版本
npm run build:lib

# 构建 ES Module 版本
npm run build:es

# 构建 UMD 版本
npm run build:umd
```

### 目录结构

```
barcode-component/
├── src/
│   ├── BarcodeComponent.jsx     # 主组件
│   ├── barcode-meta.js          # 组件元数据
│   └── index.js                 # 入口文件
├── public/
│   └── index.html               # 演示页面
├── lib/                         # CommonJS 构建输出
├── es/                          # ES Module 构建输出
├── dist/                        # UMD 构建输出
├── package.json
├── webpack.config.js
└── README.md
```

## 🔍 注意事项

### 条形码内容要求

- **EAN13**: 必须是 12 或 13 位数字
- **EAN8**: 必须是 7 或 8 位数字
- **UPC**: 必须是 11 或 12 位数字
- **CODE39**: 支持数字、大写字母和 `-.$+%/` 符号
- **CODE128**: 支持完整 ASCII 字符集

### 错误处理

组件内置错误处理机制，当条形码生成失败时会在 Canvas 上显示错误信息。

### 性能优化

- 使用 `React.memo` 避免不必要的重渲染
- 仅在必要属性变化时重新生成条形码
- Canvas 复用避免频繁创建销毁

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🆘 常见问题

### Q: 如何在低代码引擎中使用？

A: 参考上面的快速开始部分，需要先注册组件到设计器中。

### Q: 支持二维码吗？

A: 当前版本只支持条形码，二维码支持计划在下个版本中添加。

### Q: 如何自定义更多样式？

A: 可以通过 CSS 类名或内联样式对组件容器进行样式定制。

### Q: 条形码模糊怎么办？

A: 尝试调整 `width` 和 `height` 参数，或者在高 DPI 屏幕上使用更大的尺寸。

---

如有问题或建议，请提交 [Issue](https://github.com/your-org/barcode-component/issues) 或联系维护者。