@bigworm/bigworm-tools

前端工具库，包含三个模块：SnakeUtil（驼峰/下划线命名互转）、ElementUtil（Element Plus 表单/表格专用辅助）、以及从 @bigworm/bigworm-envelope 透传的 EnvelopeUtil。支持具名函数和命名空间两种调用方式。

安装

npm install @bigworm/bigworm-tools

对等依赖（已自动安装）：

• @bigworm/bigworm-envelope

SnakeUtil — 驼峰/下划线命名互转

适用于后端使用下划线命名（数据库字段）、前端使用驼峰命名的场景。

基础转换

import { camelToSnake, snakeToCamel, SnakeUtil } from '@bigworm/bigworm-tools'

camelToSnake('userName')      // 'user_name'
camelToSnake('getUserName')   // 'get_user_name'
camelToSnake('UserName')      // 'user_name'（开头大写自动处理）

snakeToCamel('user_name')     // 'userName'
snakeToCamel('_user_name')    // 'userName'（前导下划线自动去除）

// 命名空间方式等价
SnakeUtil.camelToSnake('userName')

批量转换对象键名

import { convertObjectKeysToSnake, convertObjectKeysToCamel } from '@bigworm/bigworm-tools'

// 驼峰 → 下划线
convertObjectKeysToSnake({ userName: '张三', userId: '001' })
// { user_name: '张三', user_id: '001' }

// 下划线 → 驼峰
convertObjectKeysToCamel({ user_name: '张三', user_id: '001' })
// { userName: '张三', userId: '001' }

Entity ↔ 对象（含命名转换）

import { getBeanWithSnake, putBeanWithSnake, getListWithSnake, putListWithSnake } from '@bigworm/bigworm-tools'

// Entity → 对象（下划线 → 驼峰）
// entity.data() 中有 user_name、user_id
const formData = { userName: '', userId: '' }
getBeanWithSnake(entity, formData)
// formData = { userName: '张三', userId: '001' }

// 对象 → Entity（驼峰 → 下划线）
putBeanWithSnake({ userName: '张三', userId: '001' }, entity)
// entity.data() 写入 user_name、user_id

// Entity DataSet → 数组（下划线 → 驼峰）
const users = getListWithSnake<{ userId: string; userName: string }>(entity, 'userList')
// [{ userId: '001', userName: '张三' }]

// 数组 → Entity DataSet（驼峰 → 下划线）
putListWithSnake([{ userId: '001', userName: '张三' }], entity, 'userList')
// entity 的 userList 子表中写入 user_id、user_name

注意： snakeMapToCamelBean 也已导出，用于将 snake_case Map 填充到目标对象（与 getBeanWithSnake 底层相同，但接受普通 Map 而非 Entity）。

方法一览

| 方法 | 方向 | 说明 | |------|------|------| | camelToSnake(str) | camel → snake | 字符串转换 | | snakeToCamel(str) | snake → camel | 字符串转换 | | convertObjectKeysToSnake(obj) | camel → snake | 对象键名批量转换，返回新对象 | | convertObjectKeysToCamel(obj) | snake → camel | 对象键名批量转换，返回新对象 | | snakeMapToCamelBean(body, target) | snake → camel | Map 填充到目标对象 | | getBeanWithSnake(entity, target) | snake → camel | Entity 属性填充到对象 | | putBeanWithSnake(source, entity) | camel → snake | 对象属性写入 Entity（跳过 null/undefined） | | getListWithSnake<T>(entity, name) | snake → camel | Entity 子表转 T[] | | putListWithSnake(source, entity, name) | camel → snake | T[] 写入 Entity 子表 |

ElementUtil — Element Plus 表单/表格辅助

封装了 EnvelopeUtil 和 SnakeUtil 的高频操作，统一处理表单填充/收集、表格数据绑定和分页。支持 Vue3 reactive / ref 响应式对象。

表单操作

import { fillForm, collectForm } from '@bigworm/bigworm-tools'

// ---- 填充表单 ----
const formData = reactive({ userName: '', age: 0 })

// 场景1：前后端都用驼峰（默认）
fillForm(entity, formData)

// 场景2：后端下划线 → 前端驼峰
fillForm(entity, formData, { convertKeys: true })

// 场景3：先清空再填充
fillForm(entity, formData, { clearFirst: true, convertKeys: true })

// ---- 收集表单 ----
const entity = new Entity()

// 场景1：前后端都用驼峰（默认）
collectForm(formData, entity)

// 场景2：前端驼峰 → 后端下划线
collectForm(formData, entity, { convertKeys: true })

FormOptions：

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | convertKeys | boolean | false | 是否进行命名转换（驼峰 ↔ 下划线） | | clearFirst | boolean | false | 填充前先清空表单 | | nodeName | string | 'default' | Entity 节点名 |

表格操作（支持分页）

import { fillTable, collectTable } from '@bigworm/bigworm-tools'

// ---- 填充表格 ----
const tableData = ref<User[]>([])
const pagination = reactive({ page: 1, size: 10, total: 0 })

// 场景1：简单表格（无分页）
fillTable(entity, tableData.value, { datasetName: 'userList' })

// 场景2：带分页，后端下划线 → 前端驼峰
fillTable(entity, tableData.value, {
  datasetName: 'userList',
  convertKeys: true,
  pagination: pagination   // 自动从 entity.data() 读取 page/size/total 并更新
})

// ---- 收集表格（含分页，用于传参给后端） ----
const entity = new Entity()
collectTable(tableData.value, entity, {
  datasetName: 'userList',
  pagination: { page: 1, size: 10, total: 0 }
})

TableOptions：

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | datasetName | string | 'dataset' | 子表名 | | convertKeys | boolean | false | 是否进行命名转换 | | pagination | Pagination | — | 分页对象，自动读写 page/size/total | | paginationKeys | PaginationKeys | — | 自定义分页字段名映射 | | nodeName | string | 'default' | Entity 节点名 |

fillTable 返回值 FillTableResult<T>：

{
  data: T[],           // 填充后的表格数组（与传入 tableData 同一引用）
  pagination?: {       // 提取到的分页信息（仅传入 pagination 时有值）
    page: number,
    size: number,
    total: number
  }
}

自定义分页字段映射（paginationKeys）：

// 后端返回字段名为 pageNo/pageSize/totalCount
fillTable(entity, tableData.value, {
  datasetName: 'list',
  pagination: pagination,
  paginationKeys: { page: 'pageNo', size: 'pageSize', total: 'totalCount' }
})

方法一览

| 方法 | 说明 | |------|------| | fillForm(entity, formData, options?) | Entity → 表单对象 | | collectForm(formData, entity, options?) | 表单对象 → Entity | | fillTable<T>(entity, tableData, options?) | Entity → 表格数组（含分页） | | collectTable(tableData, entity, options?) | 表格数组 → Entity（含分页） |

EnvelopeUtil — 透传自 bigworm-envelope

直接从 @bigworm/bigworm-envelope 透传，无命名转换，适合前后端均使用驼峰命名的场景。

import { get, put, getBean, putBean, getList, putList, EnvelopeUtil } from '@bigworm/bigworm-tools'

put(entity, 'userId', '10001')
const userId = get(entity, 'userId')          // string（不存在返回 ""）

putBean(formData, entity)                     // formData 属性写入 entity
const form = getBean<UserVO>(entity)          // entity 属性读到 UserVO

putList(orderList, entity, 'orders')          // List 写入 orders 子表
const orders = getList<OrderVO>(entity, 'orders')

// 命名空间等价
EnvelopeUtil.put(entity, 'userId', '10001')

默认导出

import BigWormTools from '@bigworm/bigworm-tools'

BigWormTools.EnvelopeUtil.get(entity, 'userId')
BigWormTools.SnakeUtil.camelToSnake('userName')
BigWormTools.ElementUtil.fillForm(entity, formData)

构建 & 测试

npm run build        # ESM + CJS + UMD
npm run build:all    # 构建并压缩（发布前使用）

npm test             # 运行所有测试
npm run test:watch   # 监听模式
npm run test:coverage # 覆盖率报告

构建格式：

• dist/esm/（含 .d.ts）— Vite / Webpack，支持 Tree-shaking
• dist/cjs/ — Node.js / Jest
• dist/umd/ — 浏览器 <script> 标签