@d-matrix/utils

@d-matrix/utils 是一个面向前端开发的 TypeScript 工具函数集合，按命名空间导出浏览器、React、日期、数组、数值、文件与图表等常用能力。

文档同时保留了详细 API 说明、测试入口和发布命令，既适合作为包使用说明，也适合作为仓库维护入口。

特性

按命名空间导出，导入路径稳定，适合在业务项目中按模块组织调用。
覆盖前端常见场景，包括剪贴板、DOM、React Hook、文件处理、ECharts、数组与数值计算。
提供 Cypress 组件测试、类型测试和示例页面，便于验证行为与查看用法。

快速开始

安装

npm install @d-matrix/utils

如果你会使用 react 或 echarts 相关能力，请根据项目实际情况安装对应的 peer dependencies。

导入方式

包的公开入口与 src/index.ts 保持一致，推荐按命名空间导入：

import { array, date, number, react } from '@d-matrix/utils';

基本示例

import { date, number } from '@d-matrix/utils';

const years = date.getYears({ type: date.YearOptionKind.Numbers, recentYears: 3 });
const ratio = number.safeDivide('12', '4');

console.log(years); // [2026, 2025, 2024]
console.log(ratio); // 3

import React from 'react';
import { react } from '@d-matrix/utils';

export function ResponsivePanel() {
  const isDesktopViewport = react.useMediaQuery('(min-width: 1024px)');
  const isMobileViewport = react.useMediaQuery('(max-width: 767px)');

  return <div>{isDesktopViewport ? 'desktop' : isMobileViewport ? 'mobile' : 'tablet'}</div>;
}

API 导航

每个 API 默认收起，点击展开可查看说明、示例和测试入口。

clipboard：剪贴板读写。
react：React 渲染、Hook 与类型辅助。
dom：DOM 操作与 HTML 字符串处理。
date：年份与星期相关工具。
types：TypeScript 类型工具。
algorithm：树结构与二分相关算法。
file：图片、下载与文件辅助。
support：运行环境能力检测。
timer：异步等待工具。
operator：运行时类型判断。
decimal：十进制格式化。
object：对象清理与键名辅助。
array：数组移动、统计与排名。
number：安全数值运算。
echarts：ECharts 配置与数据处理。
color：颜色转换。
scene：业务场景选择态与排序工具。

API 详情

clipboard

提供剪贴板写入能力，支持文本和图片两类常见前端交互场景。

react

提供 React 渲染、常用 Hook、类组件增强能力与类型辅助工具。

搜索请求示例

当用户快速输入多个搜索关键字时，旧请求可能比新请求更晚返回。useVersionGuard() 可以避免旧请求覆盖新结果。

import React from 'react';
import { react } from '@d-matrix/utils';

export function SearchResult({ query }: { query: string }) {
  const [result, setResult] = React.useState('');
  const { captureVersion, isCurrentVersion } = react.useVersionGuard([query]);

  React.useEffect(() => {
    const version = captureVersion();

    fetch(`/api/search?q=${encodeURIComponent(query)}`)
      .then((response) => response.text())
      .then((text) => {
        if (isCurrentVersion(version)) {
          setResult(text);
        }
      });
  }, [captureVersion, isCurrentVersion, query]);

  return <div>{result}</div>;
}

路由资源示例

当详情页从 userId=1 切到 userId=2 时，userId=1 的请求结果如果晚返回，不应该覆盖 userId=2 的页面状态。

import React from 'react';
import { react } from '@d-matrix/utils';

interface UserProfileProps {
  userId: string;
}

export function UserProfile({ userId }: UserProfileProps) {
  const [name, setName] = React.useState('');
  const { captureVersion, isCurrentVersion } = react.useVersionGuard([userId]);

  React.useEffect(() => {
    const version = captureVersion();

    fetch(`/api/users/${userId}`)
      .then((response) => response.json())
      .then((user: { name: string }) => {
        if (isCurrentVersion(version)) {
          setName(user.name);
        }
      });
  }, [captureVersion, isCurrentVersion, userId]);

  return <div>{name}</div>;
}

注意事项

依赖数组应该包含能代表当前上下文的值，不需要在外部手动拼接字符串 key。
依赖值会使用深比较判断是否变化；复杂对象建议保持不可变更新，避免原地修改导致历史依赖快照同时被改写。
useVersionGuard() 只负责判断结果是否过期，不会取消已经发出的请求；如果需要真正取消网络请求，可以结合 AbortController 使用。
captureVersion() 和 isCurrentVersion() 引用稳定，可安全放入 useEffect 依赖数组。更多行为验证见测试。

dom

提供 DOM 滚动、纯文本提取、HTML 颜色值转换和文本尺寸测量等浏览器侧工具。

date

提供年份选项构造和星期展示等日期辅助能力。

types

提供常用的 TypeScript 类型变换工具，适合在业务类型声明中复用。

algorithm

收录树结构与二分相关的算法辅助能力。

相关测试：tree.cy.ts、binary.cy.ts

nodeCountAtDepth(root: Record<string, any>, depth: number, childrenKey: string = 'children'): number

计算指定层级的节点数量。

const root = {
  id: 1,
  children: [
    { id: 2, children: [{ id: 21 }, { id: 22 }, { id: 23 }] },
    { id: 3, children: [{ id: 31 }, { id: 32 }, { id: 33 }] },
  ],
};
expect(tree.nodeCountAtDepth(root, 0)).to.be.equal(1);
expect(tree.nodeCountAtDepth(root, 1)).to.be.equal(2);
expect(tree.nodeCountAtDepth(root, 2)).to.be.equal(6);

findNode<T extends Record<string, any>>(tree: T[], predicate: (node: T) => boolean, childrenKey = 'children'): T | null

找到符合条件的节点。

const root = {
  id: 1,
  children: [
    { id: 2, children: [{ id: 21 }, { id: 22 }, { id: 23 }] },
    { id: 3, children: [{ id: 31 }, { id: 32 }, { id: 33 }] },
  ],
};
const actual = tree.findNode([root], (node) => node.id === 3);
expect(actual).to.be.deep.equal(root.children[1]);

const actual2 = tree.findNode([root], (node) => node.id === 33);
expect(actual2).to.be.deep.equal(root.children[1].children[2]);

findParent(tree, child, indentityKey, childrenKey)

根据子节点查找父节点。

const treeData = {
  code: 1,
  subs: [
    { code: 2, subs: [{ code: 21 }, { code: 22 }, { code: 23 }] },
    { code: 3, subs: [{ code: 31 }, { code: 32 }, { code: 33 }] },
  ],
};

const actual = tree.findParent(treeData, treeData.subs[1].subs[2], 'code', 'subs');
expect(actual).to.be.deep.equal(treeData.subs[1]);

findPath<T extends Record<string, any>>(tree: T[], func: (node: T) => boolean, childrenKey = 'children'): T[] | null

查找节点路径，返回节点数组或 null。

const root = {
  id: 1,
  children: [
    { id: 2, children: [{ id: 21 }, { id: 22 }, { id: 23 }] },
    { id: 3, children: [{ id: 31 }, { id: 32 }, { id: 33 }] },
  ],
};

const actual = tree.findPath([root], (node) => node.id === 33);
expect(actual).to.be.deep.equal([root, root.children[1], root.children[1].children[2]]);

flatten(tree, childrenKey = 'children')

扁平化树结构，返回的每个节点都不包含 children 属性。

file

提供图片加载、尺寸校验、文件下载和响应头文件名解析等工具。

support

提供浏览器、WebSocket、SharedWorker 等运行环境能力检测函数。

timer

提供基于 Promise 的异步等待工具。

operator

提供运行时值类型判断工具。

decimal

提供基于 decimal.js-light 的数值格式化能力。

object

提供对象零值清理与类型安全键名访问辅助函数。

array

提供数组移动、序号计算、百分位排名和标准差等实用函数。

number

提供随机整数、字符串转数值与安全四则运算函数。

echarts

提供 ECharts 配置合并、时间序列补点和 Y 轴范围计算工具。

相关测试：mergeOption.cy.ts、fill.cy.ts、calcYAxisRange.cy.ts

mergeOption(defaults: EChartsOption, overrides: EChartsOption, option?: deepmerge.Options): EChartsOption

deep merge ECharts 配置。更多用法见测试用例。

fill<T extends Record<string, any>, XAxisField extends keyof T, YAxisField extends keyof T>(dataSource: T[], xAxisField: XAxisField, yAxisField: YAxisField): T[]

适用于后端接口只返回部分时间点数据时，按 5 分钟粒度补点。填充点的 Y 轴值沿用前一个点的值。

时间示例：[9:23, 9:27] => [9:23, 9:25, 9:27, 9:30]

更多用法见测试用例，效果图见折线图。

calcYAxisRange<T extends Record<string, any>, Key extends keyof T>(data: T[], key: Key, decimalPlaces = 2, splitNumber = 5): { max: number; min: number }

计算 ECharts YAxis 的 max 和 min，使折线图能够根据实际数据动态调整波动范围，并让第一个点始终位于 Y 轴中间位置。效果图见这里。

confinePosition: TooltipComponentPositionCallback（已弃用）

confinePosition 会根据鼠标位置与 tooltip 尺寸计算提示框左上角坐标，避免提示框超出图表视图右侧和底部。默认偏移量为右下方各 20px；空间不足时会尝试显示在鼠标左侧或上方。

在线示例：CodeSandbox。

推荐直接使用 ECharts 原生的 tooltip.confine: true 配置。它会将 tooltip 限制在图表容器中，无需维护自定义位置回调。

import type { EChartsOption } from 'echarts';

const option: EChartsOption = {
  tooltip: {
    trigger: 'axis',
    confine: true,
  },
};

在迁移完成前，仍可通过深路径导入已弃用的回调：

import type { EChartsOption } from 'echarts';
import { confinePosition } from '@d-matrix/utils/dist/echarts/tooltip';

const option: EChartsOption = {
  tooltip: {
    trigger: 'axis',
    position: confinePosition,
  },
};

自定义图标

自定义 ECharts symbol 定义位于 src/echarts/symbols/index.ts，可通过深路径导入单个图标或 symbols 集合。

import { ChevronLeftOutline, symbols } from '@d-matrix/utils/dist/echarts/symbols';

const option = {
  series: [
    {
      type: 'scatter',
      symbol: ChevronLeftOutline,
      symbolSize: 24,
      data: [[0, 0]],
    },
  ],
};

symbols.StarFilled;

中国地图 GeoJSON

中国地图数据位于 src/echarts/geo-json/china.json。在创建图表前使用 registerMap() 注册数据；geo.map 与地图系列的 map 使用相同名称。

import * as echarts from 'echarts';
import chinaJson from './src/echarts/geo-json/china.json';

echarts.registerMap('china', chinaJson);

const option: echarts.EChartsOption = {
  geo: {
    map: 'china',
  },
  series: [
    {
      type: 'map',
      map: 'china',
    },
  ],
};

更多参数见 ECharts registerMap API。

color

提供十六进制颜色与 RGBA 之间的转换能力。

scene

提供多选默认项切换、带空值兜底的排序和按键防抖调度等场景工具。

相关测试：toggleSelectionValue.cy.ts、sortRecordsBySortStateNilLast.cy.ts、keyedDebounceScheduler.cy.ts

相关源码：keyedDebounceScheduler.ts、d3LeanLabeler.ts

toggleSelectionValue<T extends string | number>(params: { selectedValues: T[] | undefined; toggledValue: T; selected: boolean; defaultValue: T; isDefaultSelected: (value: T[] | undefined) => boolean; }): T[]

切换多选值，并在取消最后一个普通项时回退到默认值。适用于“全部”与普通选项互斥的场景。

import { scene } from '@d-matrix/utils';

const defaultValue = 'all';
const isDefaultSelected = (value: string[] | undefined) => scene.hasSameSelectionValues(value, [defaultValue]);

scene.toggleSelectionValue({
  selectedValues: [defaultValue],
  toggledValue: 'A',
  selected: true,
  defaultValue,
  isDefaultSelected,
}); // ['A']

scene.toggleSelectionValue({
  selectedValues: ['A'],
  toggledValue: 'A',
  selected: false,
  defaultValue,
  isDefaultSelected,
}); // ['all']

createKeyedDebounceScheduler<TKey>(delay: number): KeyedDebounceScheduler<TKey>

创建按键管理的防抖调度器。同一个键重复调度时只执行最后一次回调，不同键的回调互不影响。

import { scene } from '@d-matrix/utils';

const scheduler = scene.createKeyedDebounceScheduler<string>(300);
const fetchContacts = (groupId: string) => {
  console.log(`获取分组 ${groupId} 下的联系人`);
};

scheduler.schedule('record-1', () => {
  fetchContacts('record-1');
});

scheduler.cancel('record-1');
scheduler.dispose();

dispose() 用于在组件卸载或页面离开时结束调度器的生命周期：

会取消所有 key 对应的待执行定时器，因此这些回调不会再执行；
已经执行完成的回调不受影响；
调用后调度器不可恢复，再次调用 schedule() 只会直接忽略，不会创建新的定时器；
重复调用 dispose() 是安全的，不会产生额外副作用。

如果只是想取消某个分组当前尚未执行的任务，应使用 cancel(key)；取消后调度器仍可继续调用 schedule()：

scheduler.cancel('record-1');
scheduler.schedule('record-1', () => {
  fetchContacts('record-1');
});

如果已经调用 dispose()，原调度器就不能再次复用。后续仍需要调度任务时，必须重新创建实例：

scheduler.dispose();

const nextScheduler = scene.createKeyedDebounceScheduler<string>(300);
nextScheduler.schedule('record-1', () => {
  fetchContacts('record-1');
});

hasSameSelectionValues<T extends string | number>(selectedValues: T[] | undefined, nextSelectedValues: T[]): boolean

判断两次选中值是否一致。undefined 会按空数组处理。

scene.hasSameSelectionValues(undefined, []); // true
scene.hasSameSelectionValues(['A', 'B'], ['A', 'B']); // true
scene.hasSameSelectionValues(['A', 'B'], ['B', 'A']); // false

sortRecordsBySortStateNilLast<T extends object>(records: T[] | undefined, sortState: VirtualTableSort | undefined, options?: { getSortValue?: (record: T, field: keyof T) => unknown; }): T[] | undefined

根据排序状态对记录排序，并将 null / undefined 放到结果末尾。

import { scene } from '@d-matrix/utils';

const records = [{ value: 3 }, { value: undefined }, { value: 1 }];

scene.sortRecordsBySortStateNilLast(records, {
  field: 'value',
  direction: scene.VirtualTableSortDirection.ASC,
});
// [{ value: 1 }, { value: 3 }, { value: undefined }]

d3LeanLabeler(): D3LeanLabeler

基于模拟退火的标签避让器，用于减少标签重叠、标签与锚点重叠，以及引导线相交。

注意事项：

这是 src/scene/d3LeanLabeler.ts 的命名导出函数，当前不会通过根入口的 scene 命名空间暴露。
label() 与 anchor() 传入的数组需要等长，且按索引一一对应。
start() 会原地修改 label 数组中的 x、y 坐标。
alt_schedule() 目前只保留兼容签名，实际仍使用内置的线性降温策略。

import { d3LeanLabeler, type Anchor, type Label } from '@d-matrix/utils/dist/scene/d3LeanLabeler';

const labels: Label[] = [
  { x: 120, y: 110, width: 80, height: 20, id: 'A' },
  { x: 160, y: 118, width: 80, height: 20, id: 'B' },
];

const anchors: Anchor[] = [
  { x: 100, y: 100, r: 4, id: 'A' },
  { x: 140, y: 108, r: 4, id: 'B' },
];

const labeler = d3LeanLabeler().width(800).height(600).label(labels).anchor(anchors);

labeler.start(200);

console.log(labels); // 坐标已被原地更新

链式 API：

width(width) / height(height)：设置布局边界。
label(labels) / anchor(anchors)：注入标签与锚点数据。
alt_energy(fn)：覆盖默认能量函数。
alt_schedule(fn)：兼容接口，当前不会真正生效。
start(nsweeps)：执行退火布局。

VirtualTableSortDirection

排序方向常量。

scene.VirtualTableSortDirection.NONE; // 0
scene.VirtualTableSortDirection.ASC; // 1
scene.VirtualTableSortDirection.DESC; // -1

VirtualTableSort

排序状态类型。

type VirtualTableSort = {
  field: string;
  direction: ValueOf<typeof scene.VirtualTableSortDirection>;
};

测试与开发

测试

运行全部组件测试：

npm run cy:component:all

运行单个组件测试：

npm run cy:component -- tests/date.cy.ts

运行类型测试：

npm run test:tsd

运行 E2E 测试前，先将 src 通过 tsc 构建到 public/dist 目录：

npm run build:public

启动一个 Web 服务器访问 public/index.html，dist 目录脚本可通过 <script type="module" /> 引入：

npm run start

最后启动 Cypress GUI 客户端并选择 E2E 测试：

npm run cy:open

本地开发

构建 npm 包输出到 dist 目录：

npm run build

启动本地示例页服务：

npm run start

如果需要先为示例页准备 public/dist 下的构建产物，请先执行：

npm run build:public

发布说明

默认发布路径改为“打版本 tag 触发 GitHub Actions 自动发布”。发布前建议先在本地执行一次完整校验：

npm run release:verify

更新 package 版本：

npm version <minor> or <major>...

npm version 会更新版本、创建 git tag，并通过 postversion 自动 push commit 与 tag。tag 推送后，GitHub Actions 会执行：

npm ci
npm run build
npm run test:types
npm run cy:component:all
npm pack --dry-run
npm publish --access public
自动创建 GitHub Release

如果只想本地验证产物而不发布，可单独执行：

npm run pack:check

不再建议把 npm publish 作为常规发布入口；除非自动发布链路不可用且你明确要走人工兜底。

网络原因导致连接 registry 服务器超时时，可在人工兜底发布时指定 proxy：

npm --proxy http://127.0.0.1:7890 publish

镜像站查询版本与手动同步：

npm 镜像站

GitHub Release 默认由 Actions 自动创建，并启用 GitHub 的自动 release notes 分类；只有在需要补充说明时，才需要手动编辑 release 内容。

git log --oneline --decorate

补充链接

与发布和包维护相关的补充资料：

Name		Name	Last commit message	Last commit date
.github		.github
cypress		cypress
docs/superpowers		docs/superpowers
public		public
scripts		scripts
src		src
tests		tests
types		types
.gitignore		.gitignore
.npmrc		.npmrc
LICENSE		LICENSE
cypress.config.ts		cypress.config.ts
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md
tsconfig.e2e.json		tsconfig.e2e.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation