# Data-Package-Model

**Repository Path**: firexmoon/data-package-model

## Basic Information

- **Project Name**: Data-Package-Model
- **Description**: 基于Html的二进制数据格式可视化建模和数据结构解析器，特别适合TLV、APDU、文件头等场景下的数据结构设计、验证和调试。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DPM2 - 数据包模型编辑器

基于Html的二进制数据格式可视化建模和数据结构解析器，特别适合TLV、APDU、文件头等场景下的数据结构设计、验证和调试。

## 功能特性

### 数据结构定义
- **模板系统**：通过树形界面定义复杂的数据结构
- **容器支持**：支持嵌套容器结构，实现层级化的数据组织
- **三种容器长度模式**：
  - `auto`：自动计算子元素总长度
  - `fixed`：固定长度，可定义精确字节数
  - `ref`：引用其他字段的值作为容器长度

### 数据类型支持
- **整数类型**：UINT8/16/32/64、INT8/16/32/64
- **浮点类型**：FLOAT（32位）、DOUBLE（64位）
- **字节类型**：STRING、BYTES
- **字节序控制**：BIG_ENDIAN、LITTLE_ENDIAN
- **字符串编码**：UTF-8、GB18030、ASCII、UTF-16LE、UTF-16BE
- **长度引用**：可变长类型可引用其他字段作为长度值

### 可视化编辑
- **树形结构面板**：直观的可视化编辑界面
- **类型库**：拖拽式添加字段到结构中
- **属性编辑器**：编辑字段名称、描述、长度、编码等属性
- **实时解析**：与结构定义同步的十六进制视图

### 预设模板
内置常用文件格式模板：
- BMP 文件头（14字节）和 DIB 头（40字节）
- PNG 签名和 IHDR 块
- ZIP 本地文件头
- WAV 音频格式头
- TCP/UDP/IP 网络协议头

### 数据导入导出
- **DPM 格式**：以 JSON 格式保存和加载模板
- **二进制数据**：支持文件上传或粘贴十六进制数据
- **长度限制**：可配置最大加载字节数（默认 256 字节）

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React | 19.2.6 | UI 框架 |
| TypeScript | ~6.0.2 | 类型安全 |
| Vite | 8.0.12 | 构建工具 |
| Zustand | 5.0.13 | 状态管理 |
| Tailwind CSS | 4.3.0 | 样式框架 |
| dnd-kit | 10.0.0 | 拖拽功能 |

## 快速开始

### 环境要求
- Node.js 18+ 
- npm 9+

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问地址：
- 本地：http://localhost:5173
- 局域网：http://<你的IP地址>:5173

支持热模块替换（HMR）。

### 构建生产版本

```bash
npm run build
```

构建完成后，输出文件在 `dist` 目录。

### 预览生产版本

```bash
npm run preview
```

预览地址：http://localhost:4173

### 代码检查

```bash
npm run lint
```

## 数据类型详解

### 固定大小类型

| 类型 | 字节数 | 说明 |
|------|--------|------|
| UINT8 / INT8 | 1 | 8位无符号/有符号整数 |
| UINT16 / INT16 | 2 | 16位无符号/有符号整数 |
| UINT32 / INT32 | 4 | 32位无符号/有符号整数 |
| UINT64 / INT64 | 8 | 64位无符号/有符号整数 |
| FLOAT | 4 | 32位浮点数 |
| DOUBLE | 8 | 64位双精度浮点数 |

### 可变大小类型

| 类型 | 说明 |
|------|------|
| STRING | 字符串，需要指定长度或引用 |
| BYTES | 原始字节，需要指定长度或引用 |
| CONTAINER | 容器，嵌套其他字段 |

### 字节序

- **BIG**：大端序（网络字节序）
- **LITTLE**：小端序（Intel 格式）

### 字符串编码

支持多种字符编码：UTF-8、GB18030、ASCII、UTF-16LE、UTF-16BE

## DPM 格式说明

DPM（Data Package Model）是一种 JSON 格式的模板描述格式：

```json
{
  "version": "1.0",
  "name": "Template Name",
  "description": "Template description",
  "root": {
    "type": "container",
    "name": "Root",
    "children": [...]
  }
}
```

### 导出模板

点击导出按钮，将当前模板保存为 `.dpm` 文件。

### 导入模板

点击导入按钮，加载 `.dpm` 文件。

## 使用流程

1. **选择预设模板**（可选）
   - 从下拉菜单选择一个预设格式
   - 系统自动填充示例数据

2. **定义数据结构**
   - 从类型库拖拽字段到结构树
   - 配置每个字段的类型、长度、编码等属性
   - 使用容器组织复杂结构

3. **加载二进制数据**
   - 上传二进制文件
   - 或粘贴十六进制字符串

4. **查看解析结果**
   - 十六进制视图中高亮对应区域
   - 结构树显示字段名称和解析值
   - 悬停查看详细信息

## 命令行参考

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm run preview` | 预览生产版本 |
| `npm run lint` | 运行代码检查 |

## 常见问题

**Q: 如何解析自定义二进制格式？**
A: 从类型库拖拽字段到结构树，根据数据格式调整类型、长度和字节序。

**Q: 支持嵌套结构吗？**
A: 支持，可以在容器内添加子容器，实现多层嵌套。

**Q: 如何处理长度不确定的字段？**
A: 使用长度引用功能，将长度字段指向另一个整数字段。

**Q: 端口被占用怎么办？**
A: 修改 `vite.config.ts` 配置文件中的端口号。

**Q: 支持哪些文件格式？**
A: 内置 BMP、PNG、ZIP、WAV、TCP/UDP/IP 等预设模板，也支持任意自定义二进制格式。