nhanh-pure-function

JavaScript/TypeScript 纯函数工具库，提供动画、画布、格式化、校验等常用能力，适用于前端项目的数据处理与可视化场景。

特点：

• 🎯 纯函数设计 - 无副作用，易于测试和复用
• 📦 模块化 - 灵活组织，按需导入
• 🔤 完整类型定义 - 全 TypeScript 编写，类型支持完善
• 🎨 丰富工具 - 涵盖动画、图形、DOM、文件、格式化等11个模块

安装

npm install nhanh-pure-function

快速开始

import {
  _Format_Percentage,
  _Animate_Schedule,
  _File_Download,
  _Valid_IsPointInPolygon
} from 'nhanh-pure-function';

// 格式化百分比
_Format_Percentage(0.85); // '85%'

// 进度动画
_Animate_Schedule(500, (progress) => {
  console.log(progress); // 0 -> 1
});

// 验证点在多边形内
_Valid_IsPointInPolygon(
  { x: 50, y: 50 },
  [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 100, y: 100 }, { x: 0, y: 100 }]
); // true

模块详解

1. 🎬 Animate - 动画工具

数值动画和进度调度工具。

| 函数 | 说明 | |------|------| | _Animate_Schedule | 使用 requestAnimationFrame 实现进度动画（0→1），支持停止 | | _Animate_CreateOscillator | 创建数值振荡器，在 min/max 之间循环变化 | | _Animate_NumericTransition | 数值过渡动画，逐步改变值到目标值 | | _Animate_CubicBezier | 三次贝塞尔缓动函数（与 CSS cubic-bezier 一致） |

示例：

import { _Animate_Schedule } from 'nhanh-pure-function';

const stop = _Animate_Schedule(1000, (progress) => {
  element.style.opacity = progress;
});

// 停止动画
stop();

2. 🖼️ Blob - 数据与图像转换

二进制数据和图像处理。

| 函数 | 说明 | |------|------| | _Blob_ConvertDataToImageUrl | 将多种数据格式转换为图像 URL（支持 Base64、ArrayBuffer、Uint8Array、File） |

支持格式：

• 输入：Base64 字符串、Data URL、ArrayBuffer、Uint8Array、File
• 输出：任意 MIME 类型的图像 URL（Data URL 或 Blob URL）

3. 🌐 Browser - 浏览器 API

浏览器相关的 API 封装和工具。

| 函数 | 说明 | |------|------| | _Browser_GetFrameRate | 测量当前 FPS 和帧时间 | | _Browser_CopyToClipboard | 复制文本到剪贴板（支持 Clipboard API + 降级方案） | | _Browser_CalculatePrintableArea | 计算打印纸张的可用区域（考虑 DPI） | | _Browser_SameOriginTabManager | 同源标签页通信管理器（基于 BroadcastChannel） | | _Browser_OpenWindow | 窗口打开工具 |

子模块：

• soundEffects - 声音效果处理
• webSocketClient - WebSocket 客户端工具

4. 🎨 Canvas - 画布与可视化

4.1 Canvas.Axis - 数学坐标轴画布

完整的画布绘制引擎，支持坐标轴、图层、覆盖物等。

| 类/工具 | 说明 | |--------|------| | _Canvas_Axis | 主要画布管理类，提供图层、覆盖物、坐标轴管理 | | Layer | 图层管理 | | OverlayGroup | 覆盖物群组 | | Point | 点位 | | Line | 线段 | | Polygon | 多边形 | | Text | 文字 | | Arc | 圆弧 | | ArcTo | 圆角 | | Billboard | 图片覆盖物 | | Custom | 自定义绘制 | | OverlayCreator | 坐标轴交互创建工具 | | ViewFit | 视图适配（缩放、居中） |

功能：

• 坐标系统转换和渲染
• 多层次图层管理
• 丰富的几何图形绘制
• 交互式覆盖物创建
• 动态视图适配

4.2 Canvas.TimeAxis - 时间轴画布

时间轴 Canvas 管理器，用于时间序列数据可视化。

| 类 | 说明 | |----|------| | TimeAxisCanvasManager | 时间轴画布管理器 |

功能：

• 时间轴初始化和像素同步
• 水平拖拽操作
• 鼠标时间提示
• 动画曲线支持
• 线性渐变填充

相关类型：

• TimeAxisMouseTimeInfo - 鼠标时间提示信息
• TimeAxisRect - 矩形区域定义
• TimeAxisFillStyle - 填充样式（纯色或渐变）
• TimeAxisAnimationCurve - 动画曲线函数

5. 🎛️ Element - DOM 交互

DOM 元素交互和事件处理。

| 函数 | 说明 | |------|------| | _Element_ScrollEndListener | 滚动结束监听器（支持垂直/水平） | | _Element_CloseOnOutsideClick | 外部点击关闭逻辑（支持选择器白名单和 UI 库白名单） |

子模块：

• drop - 拖放功能
• fullscreen - 全屏显示

6. 📁 File - 文件操作

文件读取、选择、下载等工具。

| 函数 | 说明 | |------|------| | _File_Read | 读取文件内容（基于 fetch） | | _File_Select | 文件选择对话框（支持 accept 过滤和多选） | | _File_Download | 下载文件管理器（支持进度监控、超时、中止） |

特性：

• 文件类型过滤
• 单选/多选模式
• 下载进度跟踪
• 自动/手动下载模式

7. 📝 Format - 格式化工具

数据格式化和字符串处理。

| 函数 | 说明 | |------|------| | _Format_CapitalizeFirstLetter | 首字母大写 | | _Format_Percentage | 数字转百分比字符串（如 0.85 → '85%'） | | _Format_NumberWithCommas | 数字加千位分隔符（如 1000 → '1,000'） | | _Format_NumberWithUnit | 数字带单位格式化（如 12340 → '1.23万'） | | _Format_HrefName | URL 文件名提取 | | _Format_Timestamp | 时间戳格式化 |

8. 🧮 Math - 数学计算

几何和地理计算工具（主要用于 GIS 和可视化）。

| 函数 | 说明 | |------|------| | _Math_LngLatToPlane | 经纬度转平面坐标（Web Mercator 投影） | | _Math_PlaneToLngLat | 平面坐标转经纬度 | | _Math_PointToLineDistance | 点到线段的距离 | | _Math_GetArcPoints | 计算圆弧的起点和终点坐标 |

9. 🏷️ Types - TypeScript 工具类型

通用的 TypeScript 类型工具。

| 类型 | 说明 | |------|------| | _Type_RequiredBy<T, K> | 将指定属性改为必填 | | _Type_PartialBy<T, K> | 将指定属性改为可选 | | _Type_DeepPartial<T> | 递归将所有属性改为可选 | | _Type_Mutable<T> | 移除只读修饰符，使属性可变 |

示例：

import { _Type_PartialBy, _Type_DeepPartial } from 'nhanh-pure-function';

interface User {
  id: number;
  name: string;
  email: string;
}

// 部分属性可选
type PartialUser = _Type_PartialBy<User, 'email'>; // id 和 name 必填

// 深度可选
type DeepPartialUser = _Type_DeepPartial<User>;

10. 🔧 Utility - 工具函数

通用工具函数集合。

| 函数 | 说明 | |------|------| | _Utility_ExecuteWhenIdle | 在浏览器空闲时执行回调（RequestIdleCallback） | | _Utility_WaitForCondition | 等待条件满足 | | _Utility_MergeObjects | 深度合并对象 | | _Utility_GenerateUUID | UUID 生成 | | _Utility_Debounce | 防抖函数 |

子模块：

• colorConverter - 颜色转换工具
• shortcutKey - 快捷键处理
• undoRedoHistory - 撤销/重做历史管理

11. ✅ Valid - 数据验证

数据验证和类型检查工具。

| 函数 | 说明 | |------|------| | _Valid_IsNumberArray | 检查是否为有效的一维数字数组 | | _Valid_Is2DNumberArray | 检查二维数字数组结构 | | _Valid_IsInMargin | 判断数值是否在误差范围内 | | _Valid_IsPointInPolygon | 点是否在多边形内（射线算法） | | _Valid_DoesInfiniteLineIntersectRectangle | 直线是否与矩形相交 | | _Valid_DataType | 获取数据类型字符串 |

示例：

import { _Valid_IsPointInPolygon, _Valid_DataType } from 'nhanh-pure-function';

// 点在多边形内
const polygon = [
  { x: 0, y: 0 },
  { x: 100, y: 0 },
  { x: 100, y: 100 },
  { x: 0, y: 100 }
];
_Valid_IsPointInPolygon({ x: 50, y: 50 }, polygon); // true

// 获取数据类型
_Valid_DataType([]); // 'Array'
_Valid_DataType(new Map()); // 'Map'

12. 💬 _Tip - 提示流

链式提示系统，支持成功/失败自动调用不同的回调。

| 方法 | 说明 | |------|------| | _Tip.register(type, handler) | 注册提示处理函数 | | _Tip.info(...args) | 成功提示链 | | _Tip.success(...args) | 成功提示链 | | _Tip.warning(...args) | 警告提示链 | | _Tip.error(...args) | 错误提示链 |

示例：

import { _Tip } from 'nhanh-pure-function';

// 注册提示处理函数（如与 UI 库集成）
_Tip.register('success', (msg) => message.success(msg));
_Tip.register('error', (msg) => message.error(msg));

// 链式调用
_Tip.info('加载中...')
  .warning('加载失败')
  .run(somePromise);

// 或
_Tip.success('加载成功')
  .error('请重试')
  .run(data);

13. 📦 Constant - 常量

扩展名与 MIME 映射、单位标签、纸张尺寸、窗口目标等常量。

开发和构建

安装依赖

npm install

开发模式（监听模式）

npm run watch

构建

npm run build

开发构建

npm run build:dev

测试

npm test

运行 Jest 测试套件并生成覆盖率报告。

项目配置

构建工具

• Vite - 快速构建和开发
• TypeScript - 完整的类型支持
• Jest - 单元测试框架
• Less - 样式预处理

输出格式

• dist/index.cjs.js - CommonJS 格式
• dist/index.es.js - ES Module 格式
• dist/index.d.ts - TypeScript 类型定义

使用示例

场景 1：表单数据格式化

import {
  _Format_Percentage,
  _Format_NumberWithCommas,
  _Format_CapitalizeFirstLetter
} from 'nhanh-pure-function';

const data = {
  discount: 0.15,
  amount: 50000,
  name: 'john doe'
};

console.log(_Format_Percentage(data.discount)); // '15%'
console.log(_Format_NumberWithCommas(data.amount)); // '50,000'
console.log(_Format_CapitalizeFirstLetter(data.name)); // 'John doe'

场景 2：动画和过渡

import { _Animate_Schedule, _Animate_NumericTransition } from 'nhanh-pure-function';

// 进度动画
_Animate_Schedule(500, (progress) => {
  element.style.width = (progress * 100) + '%';
});

// 数值过渡
_Animate_NumericTransition(0, 100, 1000, (value) => {
  counter.textContent = Math.floor(value);
});

场景 3：地理坐标转换（GIS 场景）

import {
  _Math_LngLatToPlane,
  _Math_PlaneToLngLat,
  _Valid_IsPointInPolygon
} from 'nhanh-pure-function';

// 经纬度转平面坐标
const planeCoord = _Math_LngLatToPlane([120.15, 30.28]);

// 判断点在区域内
const isInArea = _Valid_IsPointInPolygon(
  { x: planeCoord[0], y: planeCoord[1] },
  boundaryPolygon
);

许可证

MIT

Copyright (c) 2024-present nhanh