YQG Simple Component Library

基于 Vue 2 + Ant Design Vue 的轻量级组件库，提供常用的业务组件和工具函数。

安装

npm install @yqg/simple
# 或
yarn add @yqg/simple

使用

完整引入

import Vue from 'vue'
import YqgSimple from '@yqg/simple'
import '@yqg/simple/dist/style.css'

Vue.use(YqgSimple)

按需引入

import Vue from 'vue'
import { YqgSimpleTable, YqgSimpleForm } from '@yqg/simple'

Vue.component('yqg-simple-table', YqgSimpleTable)
Vue.component('yqg-simple-form', YqgSimpleForm)

组件列表

表单组件

• yqg-simple-form - 简单表单组件
• yqg-static-form - 静态表单组件
• field-input - 输入框字段
• field-select - 选择器字段
• field-checkbox - 复选框字段
• field-radio - 单选框字段
• field-textarea - 文本域字段
• field-md-editor - Markdown 编辑器字段

表格组件

• yqg-simple-table - 简单表格组件
• yqg-info-table - 信息表格组件
• yqg-infinite-pagination - 无限分页组件

弹窗组件

• yqg-simple-modal - 简单模态框
• yqg-simple-drawer - 简单抽屉组件

其他组件

• yqg-card-list - 卡片列表组件
• yqg-env-switch - 环境切换组件
• yqg-suggestion-shortcuts - 建议快捷键组件
• yqg-swim-lane-input - 泳道输入组件
• yqg-transfer - 穿梭框组件

混入 (Mixins)

引入方式

import { table, modal, watermark } from '@yqg/simple/mixin'

export default {
  mixins: [table, modal, watermark],
  // ...
}

可用的混入

• table - 表格混入，提供表格相关的通用方法
• tableSelection - 表格选择混入
• modal - 模态框混入，提供模态框相关的通用方法
• watermark - 水印混入，提供水印功能
• commonTable - 通用表格混入
• clientTable - 客户端表格混入
• enumType - 枚举类型混入
• cardList - 卡片列表混入

按需引入

// 引入单个混入
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],
  // ...
}

过滤器 (Filters)

组件库内置了以下过滤器：

• date - 日期格式化
• dateTime - 日期时间格式化
• time - 时间格式化
• numberWithCommas - 数字千分位分隔
• percent - 百分比格式化
• phoneMask - 手机号脱敏
• countToTime - 倒计时格式化
• markdown - Markdown 转 HTML

工具函数

完整引入（从主入口）

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)

按需引入（推荐）

支持通过子路径按需引入工具函数，减少打包体积：

// 字符串工具
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', '[email protected]')
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 类型声明，开发时会有智能提示：

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

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)

const keyCodeMap = {
  esc: 27,
  tab: 9,
  enter: 13,
  up: 38,
  down: 40,
  backSpace: 8
}

Storage 类 (util/storage)

封装了 localStorage 或 sessionStorage 的存储类：

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  // 取消监听
}

常量

组件库提供了丰富的常量定义，包括表单字段定义、表格配置等。

引入方式

从主入口引入

import { constant } from '@yqg/simple'

// 使用
const dateDef = constant.dateTimeDef
const requiredField = constant.required({ field: 'name', label: '姓名' })

按需引入（推荐）

// 引入 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 组件

  const customDef = extendsDefValue({
    props: { showTime: true },
    filter: 'dateTime'
  })

• dateTimeDayStartDef - 日期时间定义（默认 00:00:00）

  // 用于搜索开始时间
  const startTimeDef = {
    ...dateTimeDayStartDef,
    field: 'startTime',
    label: '开始时间'
  }

• dateTimeDayEndDef - 日期时间定义（默认 23:59:59）

  // 用于搜索结束时间
  const endTimeDef = {
    ...dateTimeDayEndDef,
    field: 'endTime',
    label: '结束时间'
  }

common-fields 相关 (constant/common-fields)

辅助函数：

• merge<T>(...args) - 合并字段定义

  const customField = merge(dateTimeDef, { required: true, label: '创建时间' })

• required(def) - 标记字段为必填

  const nameField = required({ field: 'name', label: '姓名' })

• fixedLeft(def, width?) - 固定列到左侧

  const idColumn = fixedLeft(id, 100)

• fixedRight(def, width?) - 固定列到右侧

  const opColumn = fixedRight(op, 150)

• staticComp(def) - 将字段转为静态组件（只读）

  const readOnlyName = staticComp({ field: 'name', label: '姓名' })

样式定义：

• primaryStaticProps - 主色文本样式
• successStaticProps - 成功色文本样式
• warningStaticProps - 警告色文本样式
• sizeLongProps - 长宽度输入框样式

布局定义：

• blockItem - 块级表单项
• hiddenItem - 隐藏表单项
• rangeItem - 范围表单项

常用字段定义：

• dateTimeDef - 日期时间字段

  { type: 'date', props: { showTime: true }, filter: 'dateTime' }

• id - ID 字段

  { field: 'id', label: 'ID' }

• time - 时间字段

• timeCreate - 创建时间字段

• timeUpdate - 更新时间字段

• timeCreated - 创建时间字段（别名）

• timeUpdated - 更新时间字段（别名）

• remark - 备注字段（文本域）

• op - 操作列字段

七牛上传字段：

• qiniuFileDef - 七牛文件上传字段
• qiniuImageDef - 七牛图片上传字段

使用示例

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)
      ]
    }
  }
}

文档

• 详细使用示例
• 更新日志

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 代码检查
npm run lint

License

MIT