@yqg/simple 1.0.1 → 1.0.2

package/README.md

@@ -63,8 +63,35 @@ Vue.component('yqg-simple-form', YqgSimpleForm)
 
 ## 混入 (Mixins)
 
+### 引入方式
+
+```javascript
+import { table, modal, watermark } from '@yqg/simple/mixin'
+
+export default {
+  mixins: [table, modal, watermark],
+  // ...
+}
+```
+
+### 可用的混入
+
+- `table` - 表格混入，提供表格相关的通用方法
+- `tableSelection` - 表格选择混入
+- `modal` - 模态框混入，提供模态框相关的通用方法
+- `watermark` - 水印混入，提供水印功能
+- `commonTable` - 通用表格混入
+- `clientTable` - 客户端表格混入
+- `enumType` - 枚举类型混入
+- `cardList` - 卡片列表混入
+
+### 按需引入
+
 ```javascript
-import { table, modal, watermark } from '@yqg/simple'
+// 引入单个混入
+import table from '@yqg/simple/src/mixin/table'
+import modal from '@yqg/simple/src/mixin/modal'
+import watermark from '@yqg/simple/src/mixin/watermark'
 
 export default {
   mixins: [table, modal, watermark],
@@ -87,9 +114,397 @@ export default {
 
 ## 工具函数
 
+### 完整引入（从主入口）
+
 ```javascript
-import { formatMap, object } from '@yqg/simple'
+import { util, formatMap, object, constant } from '@yqg/simple'
+
+// 使用字符串工具
+const snakeCase = util.camelCaseToUnderscore('userName') // 'user_name'
+
+// 使用对象工具
+const value = object.pickValue(data, 'user.name')
+const merged = object.merge(obj1, obj2)
 
-// 使用工具函数
+// 使用格式化工具
 const formatted = formatMap.formatValue(value, options)
-const merged = object.deepMerge(obj1, obj2)
+```
+
+### 按需引入（推荐）
+
+支持通过子路径按需引入工具函数，减少打包体积：
+
+```javascript
+// 字符串工具
+import { camelCaseToUnderscore } from '@yqg/simple/util/tool'
+
+const snakeCase = camelCaseToUnderscore('userName') // 'user_name'
+
+// 对象操作工具
+import { pickValue, setValue, merge } from '@yqg/simple/util/object'
+
+const data = { user: { name: 'John', age: 30 } }
+const name = pickValue(data, 'user.name') // 'John'
+const updated = setValue(data, 'user.email', 'john@example.com')
+const merged = merge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
+
+// 格式化工具
+import getFormatter from '@yqg/simple/util/format-map'
+
+const listFormatter = getFormatter('list')
+const formatted = listFormatter.format(['a', 'b', 'c']) // 'a\nb\nc'
+
+// 枚举工具
+import { boolOf, valueOf } from '@yqg/simple/util/enum'
+
+const bool = boolOf('TRUE') // true
+const str = valueOf(true) // 'TRUE'
+
+// JSON 工具
+import { pureJSONString, reformatJson } from '@yqg/simple/util/json'
+
+const jsonStr = pureJSONString({ name: 'John' })
+
+// 本地存储工具
+import { setStorage, getStorage, removeItem } from '@yqg/simple/util/local-storage'
+
+setStorage('user', JSON.stringify({ name: 'John' }))
+const user = getStorage('user')
+
+// 键码映射
+import keyCodeMap from '@yqg/simple/util/keyCodeMap'
+
+if (event.keyCode === keyCodeMap.enter) {
+  // 处理回车键
+}
+
+// Storage 类
+import Storage from '@yqg/simple/util/storage'
+
+const myStorage = new Storage('my-key', true) // 使用 sessionStorage
+myStorage.set({ data: 'value' })
+const data = myStorage.get()
+```
+
+### TypeScript 支持
+
+所有工具函数都提供完整的 TypeScript 类型声明，开发时会有智能提示：
+
+```typescript
+import { camelCaseToUnderscore, pickValue, merge } from '@yqg/simple/util'
+
+// ✅ 编辑器自动提示：camelCaseToUnderscore(camelStr: string): string
+const snakeCase = camelCaseToUnderscore('userName')
+
+// ✅ 编辑器自动提示：pickValue<T = any>(obj: any, keyString: string): T | undefined
+const value = pickValue<number>({ a: { b: 1 } }, 'a.b')
+
+// ✅ 编辑器自动提示：merge<T, S>(target?: T, source?: S): T & S
+const merged = merge({ a: 1 }, { b: 2 })
+```
+
+### 工具函数 API
+
+#### 字符串工具 (`util/tool`)
+
+- `camelCaseToUnderscore(camelStr: string): string` - 驼峰转下划线
+
+#### 对象工具 (`util/object`)
+
+- `evalProp<T, V>(value: T | ((values: V) => T), values?: V): T` - 评估属性（函数或值）
+- `pickValue<T>(obj: any, keyString: string): T | undefined` - 提取嵌套值（支持 'a.b.c' 或 'a[0].b'）
+- `setValue<T>(obj: T, keyString: string, value: any): T` - 设置嵌套值
+- `spreadObjectKeys<T>(origin: T): T` - 展开对象键
+- `numbersToStr<T>(val: T | T[]): ...` - 数字转字符串
+- `spreadProps(props): ...` - 展开 Vue 组件属性
+- `appendClass(className, appendix): ...` - 追加类名
+- `merge<T, S>(target?: T, source?: S): T & S` - 深度合并对象
+- `isMobile: boolean` - 是否为移动设备
+
+#### 格式化工具 (`util/format-map`)
+
+- `getFormatter(format: string | Formatter): Formatter` - 获取格式化器
+- 内置格式化器：`boolean`、`bool`、`list`、`comma`、`listJson`、`json`、`listComma`、`commaToList`、`date`、`dateTime`、`percent`
+
+```javascript
+const listFormatter = getFormatter('list')
+const formatted = listFormatter.format(['a', 'b', 'c']) // 'a\nb\nc'
+const unformatted = listFormatter.unformat('a\nb\nc') // ['a', 'b', 'c']
+```
+
+#### 枚举工具 (`util/enum`)
+
+- `boolOf(str: string): boolean` - 字符串转布尔值（'TRUE' -> true）
+- `valueOf(bool: boolean): 'TRUE' | 'FALSE' | undefined` - 布尔值转字符串（true -> 'TRUE'）
+
+#### JSON 工具 (`util/json`)
+
+- `pureJSONString(value: any): string` - 转换为格式化的 JSON 字符串
+- `reformatJson(value: string, context?: any): string` - 重新格式化 JSON 字符串
+
+#### 本地存储工具 (`util/local-storage`)
+
+- `setStorage(itemName: string, item: string): void` - 设置 localStorage
+- `getStorage(itemName: string): string | null` - 获取 localStorage
+- `removeItem(itemName: string): void` - 删除 localStorage 项
+
+#### 键码映射 (`util/keyCodeMap`)
+
+```javascript
+const keyCodeMap = {
+  esc: 27,
+  tab: 9,
+  enter: 13,
+  up: 38,
+  down: 40,
+  backSpace: 8
+}
+```
+
+#### Storage 类 (`util/storage`)
+
+封装了 localStorage 或 sessionStorage 的存储类：
+
+```typescript
+class Storage {
+  constructor(key: string, useSessionStorage?: boolean)
+  set(cache: any): void              // 设置存储
+  get<T = any>(): T | null          // 获取存储
+  remove(): void                     // 删除存储
+  on(fn: (event: StorageEvent) => void): void  // 监听变化
+  off(needsRemove?: boolean): void  // 取消监听
+}
+```
+
+## 常量
+
+组件库提供了丰富的常量定义，包括表单字段定义、表格配置等。
+
+### 引入方式
+
+#### 从主入口引入
+
+```javascript
+import { constant } from '@yqg/simple'
+
+// 使用
+const dateDef = constant.dateTimeDef
+const requiredField = constant.required({ field: 'name', label: '姓名' })
+```
+
+#### 按需引入（推荐）
+
+```javascript
+// 引入 fields.ts（包含 common-fields 的所有导出）
+import { 
+  extendsDefValue,
+  dateTimeDayStartDef,
+  dateTimeDayEndDef,
+  // 以下来自 common-fields
+  dateTimeDef,
+  required,
+  merge,
+  id,
+  timeCreate,
+  timeUpdate,
+  remark
+} from '@yqg/simple/constant/fields'
+
+// 引入 common-fields
+import { 
+  dateTimeDef,
+  required,
+  merge,
+  primaryStaticProps,
+  successStaticProps,
+  warningStaticProps,
+  fixedLeft,
+  fixedRight,
+  staticComp,
+  blockItem,
+  hiddenItem,
+  id,
+  time,
+  timeCreate,
+  timeUpdate,
+  remark
+} from '@yqg/simple/constant/common-fields'
+
+// 引入表格常量
+import { defaultPagination } from '@yqg/simple/constant/table'
+```
+
+### 常用常量 API
+
+#### fields 相关 (`constant/fields`)
+
+**字段定义辅助函数：**
+
+- `extendsDefValue(options)` - 扩展 DefValue 组件
+  ```javascript
+  const customDef = extendsDefValue({
+    props: { showTime: true },
+    filter: 'dateTime'
+  })
+  ```
+
+- `dateTimeDayStartDef` - 日期时间定义（默认 00:00:00）
+  ```javascript
+  // 用于搜索开始时间
+  const startTimeDef = {
+    ...dateTimeDayStartDef,
+    field: 'startTime',
+    label: '开始时间'
+  }
+  ```
+
+- `dateTimeDayEndDef` - 日期时间定义（默认 23:59:59）
+  ```javascript
+  // 用于搜索结束时间
+  const endTimeDef = {
+    ...dateTimeDayEndDef,
+    field: 'endTime',
+    label: '结束时间'
+  }
+  ```
+
+#### common-fields 相关 (`constant/common-fields`)
+
+**辅助函数：**
+
+- `merge<T>(...args)` - 合并字段定义
+  ```javascript
+  const customField = merge(dateTimeDef, { required: true, label: '创建时间' })
+  ```
+
+- `required(def)` - 标记字段为必填
+  ```javascript
+  const nameField = required({ field: 'name', label: '姓名' })
+  ```
+
+- `fixedLeft(def, width?)` - 固定列到左侧
+  ```javascript
+  const idColumn = fixedLeft(id, 100)
+  ```
+
+- `fixedRight(def, width?)` - 固定列到右侧
+  ```javascript
+  const opColumn = fixedRight(op, 150)
+  ```
+
+- `staticComp(def)` - 将字段转为静态组件（只读）
+  ```javascript
+  const readOnlyName = staticComp({ field: 'name', label: '姓名' })
+  ```
+
+**样式定义：**
+
+- `primaryStaticProps` - 主色文本样式
+- `successStaticProps` - 成功色文本样式
+- `warningStaticProps` - 警告色文本样式
+- `sizeLongProps` - 长宽度输入框样式
+
+**布局定义：**
+
+- `blockItem` - 块级表单项
+- `hiddenItem` - 隐藏表单项
+- `rangeItem` - 范围表单项
+
+**常用字段定义：**
+
+- `dateTimeDef` - 日期时间字段
+  ```javascript
+  { type: 'date', props: { showTime: true }, filter: 'dateTime' }
+  ```
+
+- `id` - ID 字段
+  ```javascript
+  { field: 'id', label: 'ID' }
+  ```
+
+- `time` - 时间字段
+- `timeCreate` - 创建时间字段
+- `timeUpdate` - 更新时间字段
+- `timeCreated` - 创建时间字段（别名）
+- `timeUpdated` - 更新时间字段（别名）
+- `remark` - 备注字段（文本域）
+- `op` - 操作列字段
+
+**七牛上传字段：**
+
+- `qiniuFileDef` - 七牛文件上传字段
+- `qiniuImageDef` - 七牛图片上传字段
+
+### 使用示例
+
+```javascript
+import { 
+  merge, 
+  required, 
+  dateTimeDayStartDef, 
+  dateTimeDayEndDef,
+  id,
+  timeCreate,
+  timeUpdate,
+  remark,
+  fixedLeft,
+  fixedRight
+} from '@yqg/simple/constant/fields'
+
+export default {
+  data() {
+    return {
+      // 表单字段定义
+      formFields: [
+        required(merge(id, { label: '用户ID' })),
+        required({ field: 'name', label: '姓名' }),
+        { 
+          ...dateTimeDayStartDef, 
+          field: 'startTime', 
+          label: '开始时间' 
+        },
+        {
+          ...dateTimeDayEndDef,
+          field: 'endTime',
+          label: '结束时间'
+        },
+        remark
+      ],
+      
+      // 表格列定义
+      tableColumns: [
+        fixedLeft(id, 80),
+        { field: 'name', label: '姓名' },
+        timeCreate,
+        timeUpdate,
+        fixedRight({ field: 'op', label: '操作' }, 120)
+      ]
+    }
+  }
+}
+```
+
+## 文档
+
+- [详细使用示例](./USAGE_EXAMPLE.md)
+- [更新日志](./CHANGELOG.md)
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 构建
+npm run build
+
+# 代码检查
+npm run lint
+```
+
+## License
+
+MIT