🚀 不仅是工具库，更是国内前端开发的“瑞士军刀” —— @qnvip/core

前言

在前端开发领域，Lodash 确实是业界的标杆，但在国内的实际业务场景中，我们往往会遇到这样的尴尬：

为了一个 deepClone 引入了整个 Lodash（或者还要折腾 babel-plugin-lodash）。
处理 URL 参数时，还要额外引入 qs 或 query-string。
遇到"手机号脱敏"、"身份证校验"、"小程序 Scheme 跳转"这些中国特色的业务需求时，Lodash 就爱莫能助了，只能自己手写正则表达式。

我们需要一个更懂国内业务、更轻量、更聚合的工具库。

这就是 @qnvip/core 诞生的初衷。它源自一线大厂的业务沉淀，All in One 地解决了 90% 的日常痛点。

⚔️ 核心竞争力：为什么选择 @qnvip/core？

1. 🇨🇳 China-First：专为国内生态打造

不同于国外的通用库，我们内置了大量针对国内业务的解决方案：

小程序生态：一键生成支付宝/微信/字节/京东小程序的跳转 Scheme。
合规与安全：内置中国大陆手机号、身份证（15/18位）、中文姓名的精准校验与脱敏逻辑。
中后台适配：针对 ElementUI/AntD 等组件库的数据结构进行了专门的工具封装。

2. 📦 All-in-One：一个库顶五个

安装了 @qnvip/core，你可能不再需要以下依赖：

❌ lodash (已内置 debounce, throttle, deepClone, isEmpty...)
❌ qs / query-string (已内置 parseParams, paramsToQuery)
❌ copy-to-clipboard (已内置 copyText)
❌ file-saver (已内置 downloadFile)
❌ uuid (已内置 generateUID)

3. 🛡️ 企业级代码质量

TypeScript：全量 TS 编写，类型提示精准到每一个参数。
Tree-shaking：支持 ESM，按需加载，未使用的代码在构建时会自动剔除，零负担引入。
零依赖：自身不依赖任何第三方运行时包，底座干净纯粹。

💡 深度场景解析：它如何解决实际问题？

场景一：终结"跨端跳转"的噩梦 🤯

在混合开发（Hybrid）中，从 H5 唤起各个平台的小程序是一件极其繁琐的事。不同平台的 Scheme 协议不同，参数编码规则也不同。

@qnvip/core 的 generatePlatformLink 帮你抹平了这一切：

typescript 复制代码

import { generatePlatformLink, schemeToParams } from '@qnvip/core'

// 1. 生成支付宝跳转链接
// 痛点：手动拼接容易错，参数还需要多重 encode
const alipayLink = generatePlatformLink({
  platform: 'ALIPAY',
  appId: '202100xxxx',
  page: 'pages/home/index',
  query: { id: '123', from: 'sms' } // 自动处理对象转字符串 + encodeURIComponent
})
// Output: alipays://platformapi/startapp?appId=202100xxxx&page=...

// 2. 调试神器：反向解析 Scheme
// 痛点：拿到一个长长的 Scheme，想知道里面到底传了什么参数
const scheme = 'alipays://platformapi/startapp?appId=2021&page=pages%2Findex&query=a%3D1'
const params = schemeToParams(scheme)
console.log(params)
// Output: {
//   params: {
//     appId: '2021',
//     path: 'pages/index',
//     query: { a: '1' }
//   }
// }

场景二：合规是底线，脱敏要灵活 🔒

在《个人信息保护法》日益严格的今天，数据脱敏是前端的必修课。

typescript 复制代码

import { desensitize, isTrueName } from '@qnvip/core'

// 场景：列表页展示用户摘要信息
const user = {
  phone: '13812345678',
  idCard: '110101199001011234',
  name: '张三丰'
}

// ❌ 以前的做法：手写正则，容易出错
// user.phone.replace(/^(\d{3})\d{4}(\d{4})$/, '$1****$2')

// ✅ 现在的做法：语义化调用
console.log(desensitize(user.phone, { type: 'phone' })) // "138****5678"
console.log(desensitize(user.idCard, { type: 'idcard' })) // "110***********1234"
console.log(desensitize(user.name, { type: 'name' })) // "张*丰"

// 甚至支持少数民族姓名的精准校验（支持中间的点）
isTrueName('迪丽热巴·迪力木拉提') // true

场景三：中后台开发的"提效利器" 🚀

针对管理后台中大量的 Select 下拉框和 Table 表格，我们封装了专门的数据转换工具。

typescript 复制代码

import { generateSelectOption, findValueToLabel, filterInvalidValues } from '@qnvip/core'

// 场景：后端返回 key-value 结构不统一，组件库需要 label-value
const serverData = [
  { region_id: 101, region_name: '北京' },
  { region_id: 102, region_name: '上海' }
]

// 一行代码转换，无需手写 .map
const options = generateSelectOption(serverData, 'region_name', 'region_id')
// Output: [{ label: '北京', value: 101 }, { label: '上海', value: 102 }]

// 场景：Table 列表中把 status: 1 展示为 "已上架"
// 即使 value 是字符串 '1' 也能容错匹配
const statusLabel = findValueToLabel([{ label: '已上架', value: 1 }], '1', { defaultValue: '-' }) // Output: "已上架"

// 场景：搜索表单提交前，清洗空值（null/undefined/空字符串）
const query = filterInvalidValues({
  keyword: '手机',
  type: '', // 被清洗
  date: null // 被清洗
})
// Output: { keyword: '手机' }

场景四：页面安全与文件交互 🖼️

typescript 复制代码

import { setWaterMark, downloadFile, getImageDimensions } from '@qnvip/core'

// 1. 页面水印：防截图、防泄露
// 创建一个覆盖全屏、点击穿透（pointer-events: none）的水印层
setWaterMark('绝密资料 - 严禁外传')

// 2. 鲁棒的文件下载
// 兼容 IE 的 msSaveBlob 和现代浏览器的 a 标签下载
downloadFile(blobData, '报表.xlsx')

// 3. 上传前预检
// 读取文件宽高，拦截不符合尺寸的图片
const { width, height } = await getImageDimensions(file)

🛠️ 源码级的高级特性

我们不仅关注功能，更关注代码的健壮性。

debounce (防抖) : 返回对象包含 cancel 方法。在 React useEffect 或 Vue onUnmounted 中调用，可避免组件卸载后的内存泄漏。
deepClone (深拷贝) : 采用 WeakMap 解决循环引用问题，并完美支持 Date 对象、RegExp 等特殊类型的拷贝。
isEmpty (判空) : 极其严谨的判空逻辑。0 和 false 不会被误判为空，而 []、{}、null、undefined 会被正确识别。

📚 全景能力清单

模块	核心函数	解决痛点
URL	`parseParams` / `paramsToQuery`	替代 qs，处理 URL 参数编解码
	`schemeToParams`	解析复杂的 App Scheme 结构
验证	`isIdCard` / `isPhone`	国内手机号、身份证合法性校验
	`isTrueName`	支持生僻字、少数民族姓名的校验
数据	`deepClone`	解决 JSON.parse(JSON.stringify) 的缺陷
	`filterInvalidValues`	表单提交前的参数清洗
	`generateSelectOption`	后端数据快速适配 UI 组件
业务	`generatePlatformLink`	统一生成各平台小程序跳转链接
	`desensitize`	灵活的数据脱敏配置
DOM	`setWaterMark`	快速添加页面安全水印
	`copyText`	兼容性更好的剪贴板复制
文件	`downloadFile`	统一文件下载行为
	`getImageDimensions`	图片上传前的尺寸预检
工具	`debounce` / `throttle`	高性能防抖节流
	`generateUID`	生成唯一标识符

📦 快速开始

bash 复制代码

# npm
npm install @qnvip/core

# pnpm (推荐)
pnpm add @qnvip/core

我们相信，最好的工具库是"由于它存在，你甚至感觉不到它的存在"。 @qnvip/core 致力于成为这样润物细无声的基础设施。

🔗 GitHub : github.com/qnvip-front...

📚 API 文档 : tech.qnvip.com/core/

既然看到了这里，不妨去 GitHub 点个 Star ⭐️ 支持一下国产开源力量！