🚀 不仅是工具库，更是国内前端开发的“瑞士军刀” —— @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 帮你抹平了这一切：

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' }
//   }
// }

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

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

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 表格，我们封装了专门的数据转换工具。

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: '手机' }

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

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	生成唯一标识符

---

📦 快速开始

# npm
npm install @qnvip/core

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

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

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

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

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