l-mini-fn

l-mini-fn

uniapp 跨平台小程序工具库，提供扫码、摄像头、手势检测等常用功能

✨ 特性

• 🎯 跨平台支持：微信、支付宝、抖音、百度、京东、QQ、快手小程序
• 🔍 扫码功能：获取启动参数、解析扫码参数、URL参数解析
• 📷 摄像头权限：检测和请求摄像头权限
• 👆 手势检测：滑动方向检测，带防抖处理
• 📁 文件存储：跨平台文件读写、JSON 存储缓存
• 🔧 通用工具：平台判断、弹窗、路由、系统信息、图片处理等
• 📦 双模块格式：同时生成 ESM 和 CJS，兼容所有环境
• 🌳 Tree-shaking：支持按需导入，减小打包体积
• 📝 TypeScript：完整的类型定义，提升开发体验
• 🚀 零依赖：无运行时依赖，轻量高效
• ✅ 测试完善：单元测试覆盖核心功能

📦 安装

npm install l-mini-fn
# 或
yarn add l-mini-fn
# 或
pnpm add l-mini-fn

🚀 快速开始

扫码功能

import { getLaunchOptions, getScanParams, getQueryParams } from 'l-mini-fn';

// 在小程序页面的 onLoad 中使用
onLoad(options) {
  // 获取扫码参数
  getScanParams(options, (url, params) => {
    console.log('扫码URL:', url);
    console.log('解析参数:', params);
    // url: "https://example.com?id=123&name=test"
    // params: { id: "123", name: "test" }
  });
}

// 解析 URL 参数
const params = getQueryParams('https://example.com?id=123&name=test');
console.log(params); // { id: '123', name: 'test' }

摄像头权限

import { hasCameraAccess, requestCameraPermission } from 'l-mini-fn';

// 检测摄像头权限
const hasPermission = await hasCameraAccess();
if (!hasPermission) {
  // 请求权限
  const granted = await requestCameraPermission();
  if (granted) {
    console.log('用户已授权');
  } else {
    console.log('用户拒绝授权');
  }
}

手势检测

import { detectDirectionDebounce, resetSwipeDetect } from 'l-mini-fn';

// 在 Vue 组件中使用
onTouchMove(e) {
  detectDirectionDebounce(e, (direction) => {
    console.log('滑动方向:', direction); // 'up' | 'down' | 'left' | 'right'
  }, { threshold: 10, delay: 50 });
}

onTouchEnd() {
  resetSwipeDetect();
}

平台判断

import {
  getPlatform,
  isWeixin,
  isAlipay,
  isOneOf
} from 'l-mini-fn';

// 获取当前平台
const platform = getPlatform();
console.log(platform); // 'wechat' | 'alipay' | 'douyin' | ...

// 判断具体平台
if (isWeixin()) {
  console.log('当前运行在微信小程序');
  // 微信特有逻辑
} else if (isAlipay()) {
  console.log('当前运行在支付宝小程序');
  // 支付宝特有逻辑
}

// 批量判断
if (isOneOf(['wechat', 'alipay'])) {
  console.log('当前运行在微信或支付宝');
}

弹窗提示

import { showCustomModal } from 'l-mini-fn';

// Promise 方式（推荐）
const confirmed = await showCustomModal({
  title: '提示',
  msg: '确定删除吗？'
});
if (confirmed) {
  console.log('用户点击了确认');
}

// 回调方式（兼容旧代码）
showCustomModal(
  { title: '提示', msg: '确定删除吗？' },
  () => { console.log('确认'); },
  () => { console.log('取消'); }
);

其他工具

import {
  router,
  getSystemInfo,
  copyText,
  showGlobalLoading,
  hideGlobalLoading
} from 'l-mini-fn';

// 路由跳转
router('/pages/detail/index', 'navigateTo');

// 获取系统信息
const systemInfo = await getSystemInfo();
console.log(systemInfo.model); // 设备型号

// 复制文本
copyText('Hello World', '复制成功');

// 加载提示
await showGlobalLoading('加载中...');
// ... 执行操作
await hideGlobalLoading();

文件存储

import { storage, writeJSON, readJSON, exists, deleteFile } from 'l-mini-fn';

// 方式一：使用默认实例（推荐）
// 写入 JSON
await storage.writeJSON('user.json', { name: '张三', age: 25 });

// 读取 JSON
const user = await storage.readJSON('user.json');
console.log(user.name); // '张三'

// 检查文件是否存在
const hasUser = await storage.exists('user.json');

// 删除文件
await storage.delete('user.json');

// 方式二：使用便捷函数
await writeJSON('config.json', { theme: 'dark' });
const config = await readJSON('config.json');

📁 功能模块

扫码模块（miniprogram/scan）

函数	说明
getLaunchOptions()	获取小程序启动参数
getScanParams(options, callback)	解析扫码参数
getQueryParams(url)	解析 URL 查询参数

摄像头模块（miniprogram/camera）

函数	说明
hasCameraAccess()	检测摄像头权限
requestCameraPermission()	请求摄像头权限

手势检测模块（utils/gesture）

函数	说明
detectDirectionDebounce(e, callback, options)	检测滑动方向
resetSwipeDetect()	重置检测状态

通用工具模块（miniprogram/common）

平台相关

• getPlatform() - 获取当前平台类型
• isWeixin() - 判断是否为微信小程序
• isAlipay() - 判断是否为支付宝小程序
• isDouyin() - 判断是否为抖音小程序
• isBaidu() - 判断是否为百度小程序
• isJD() - 判断是否为京东小程序
• isQQ() - 判断是否为QQ小程序
• isKuaishou() - 判断是否为快手小程序
• isH5() - 判断是否为H5
• isApp() - 判断是否为App
• isOneOf(platforms) - 判断是否在指定平台之一

弹窗相关

• showCustomModal(options, confirmCallBack, cancelCallback) - 自定义模态框

路由相关

• router(url, type) - 路由跳转（navigateTo/reLaunch/switchTab/redirectTo）

系统信息

• getEnvVersion() - 获取平台版本（正式版/体验版/开发版）
• getSystemInfo() - 获取系统信息
• getMiniVersion() - 获取小程序版本号
• getMenuButtonInfo() - 获取胶囊按钮信息

图片相关

• selectSystemPhoto(callback, params) - 选择系统相册图片
• getWxImage(filePath) - 转换微信协议图片为可回显路径
• getCachedImage(url, cache, options) - 图片缓存

加载提示

• showGlobalLoading(msg) - 显示全局加载（支持引用计数）
• hideGlobalLoading() - 隐藏全局加载

计算工具

• calcSquareItemHeight(columns, margin, containerWidth) - 计算正方形元素高度

键盘相关

• getKeyBoardHeight(changeCallBack) - 获取键盘高度（含安全区）

剪贴板

• copyText(text, successToast) - 复制文本到剪贴板

文件存储模块（miniprogram/file-storage）

FileStorage 类

• writeFile(fileName, content, options) - 写入文本文件
• writeJSON(fileName, data, options) - 写入 JSON 文件
• readFile(fileName, options) - 读取文本文件
• readJSON(fileName, options) - 读取 JSON 文件
• exists(fileName) - 检查文件是否存在
• delete(fileName) - 删除文件
• clear() - 清空目录
• getFileInfo(fileName) - 获取文件信息

便捷函数

• writeFile() - 写入文件（使用默认实例）
• writeJSON() - 写入 JSON（使用默认实例）
• readFile() - 读取文件（使用默认实例）
• readJSON() - 读取 JSON（使用默认实例）
• exists() - 检查文件是否存在（使用默认实例）
• deleteFile() - 删除文件（使用默认实例）
• storage - 默认 FileStorage 实例

📦 项目结构

l-mini-fn/
├── src/
│   ├── index.ts              # 统一导出入口
│   ├── miniprogram/          # 小程序专用模块
│   │   ├── scan.ts           # 扫码相关
│   │   ├── camera.ts         # 摄像头相关
│   │   ├── common.ts         # 通用工具
│   │   └── file-storage.ts   # 文件存储
│   ├── utils/                # 通用工具模块
│   │   ├── gesture.ts        # 手势检测
│   │   └── internal.ts       # 内部工具（不对外导出）
│   └── types/                # 类型定义
├── __tests__/                # 单元测试
├── dist/                     # 构建输出（自动生成）
├── tsup.config.ts            # 构建配置
├── tsconfig.json             # TypeScript 配置
└── package.json

🛠️ 开发命令

# 监听模式开发（热重载）
npm run dev

# 清理并构建生产版本
npm run build

# 清理 dist 目录
npm run clean

# 重装依赖
npm run reload

# 运行测试
npm test

# 生成 API 文档
npm run docs

# 本地预览文档
npm run docs:serve

# 发布到 npm
npm run publish:npm

🌐 平台支持

平台	支持情况
微信小程序	✅ 完全支持
支付宝小程序	✅ 完全支持
抖音小程序	✅ 平台检测支持
百度小程序	✅ 平台检测支持
京东小程序	✅ 平台检测支持
QQ小程序	✅ 平台检测支持
快手小程序	✅ 平台检测支持
H5	✅ 部分支持

📝 代码规范

遵循 Conventional Commits 规范：

git commit -m "feat: 添加新功能"
git commit -m "fix: 修复bug"
git commit -m "docs: 更新文档"

🧪 测试

# 运行测试
npm test

# 生成覆盖率报告
npm run test:coverage

# 监听模式运行测试
npm run test:watch

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

• Issues: GitHub Issues

享受编码！ 🎉