# @sinonjs/fake-timers 中文文档

规范地址：https://npmcn.com/package/%40sinonjs/fake-timers/

版本：15\.4\.0
npm 元数据更新时间：2026-05-05T21:23:07.025Z
中文译文更新时间：2026-11-05T15:57:49.737Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40sinonjs/fake-timers
原文对照：https://npmcn.com/package/%40sinonjs/fake-timers/?lang=original
项目主页：https://github.com/sinonjs/fake-timers
源码仓库：https://github.com/sinonjs/fake-timers

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：147 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2020-02-04T11:41:51.250Z
- 最新版本发布：2026-05-05T21:23:06.846Z
- 近 30 天下载量：305489856（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 11 个）

## 中文简介

假 JavaScript 计时器

## 安装

```sh
npm install @sinonjs/fake-timers
```

也可以使用：`pnpm add @sinonjs/fake-timers`、`yarn add @sinonjs/fake-timers`、`bun add @sinonjs/fake-timers`

## README

# `@sinonjs/fake-timers`

[![codecov](https://codecov.io/gh/sinonjs/fake-timers/branch/main/graph/badge.svg)](https://codecov.io/gh/sinonjs/fake-timers) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](https://npmcn.com/package/%40sinonjs/fake-timers/CODE_OF_CONDUCT.md)

Java 脚本执行定时器 APIs(英语:APIs; `setTimeout`, (中文(简体) ), `clearTimeout`, (中文(简体) ), `setImmediate`, (中文(简体) ), `clearImmediate`, (中文(简体) ), `setInterval`, (中文(简体) ), `clearInterval`, (中文(简体) ), `requestAnimationFrame`, (中文(简体) ), `cancelAnimationFrame`, (中文(简体) ), `requestIdleCallback`, (中文(简体) ), 财务报告和审定财务报表 `cancelIdleCallback`,以及控制时间流的时钟实例。 假时报还提供 `Date` 执行时间从时钟算起.

除浏览器环境外 `@sinonjs/fake-timers` 页:1 `performance` 时间的落实 从时钟。 在节点环境中,假时提供 `nextTick` 同步执行 时钟 - 和 a `process.hrtime` 和时钟一起工作的人.

`@sinonjs/fake-timers` 可用于在自动测试和其他测试中模拟通过时间 需要排程语义的情况,但实际上不想 单单.

`@sinonjs/fake-timers` 属于 [西农. 联合来文](https://github.com/sinonjs/sinon.js) 和目标 页:1 [相同的运行时间](https://sinonjs.org/releases/latest#compatibility-and-supported-runtimes)。 。 。 .

## 自动完成、 IntelliSense 和 TypeScript 定义

`@sinonjs/fake-timers` 由JSDoc生成内置类型定义的船舶. 在支持IDE和TypeScript项目时提供自动完整和类型建议,而不需要外部 `@types` 软件包.

## 安装

`@sinonjs/fake-timers` 可以在节点和浏览器环境中使用. 安装和安装一样容易

```sh
npm install @sinonjs/fake-timers
```

如果你想使用的话 `@sinonjs/fake-timers` 您可以在浏览器中构建自己的捆绑或 使用情况 [天盘](https://www.skypack.dev/)。 。 。 .

## 使用量

用于 `@sinonjs/fake-timers`,创建新的时钟, 使用计时器安排其上的事件 函数和通过时间 `tick` 方法.

```js
// In the browser distribution, a global `FakeTimers` is already available
var FakeTimers = require("@sinonjs/fake-timers");
var clock = FakeTimers.createClock();

clock.setTimeout(function () {
    console.log(
        "The poblano is a mild chili pepper originating in the state of Puebla, Mexico.",
    );
}, 15);

// ...

clock.tick(15);
```

执行最后一行后, 一个有趣的事实 [波布拉诺](https://en.wikipedia.org/wiki/Poblano) 将同步打印到 屏幕。 如果你想模拟同步行为,请看 `async` 函数变体( e) 语法 `clock.tick(time)` 对 `await clock.tickAsync(time)`) (中文(简体) ).

这个 `next`, (中文(简体) ), `runAll`, (中文(简体) ), `runToFrame`,以及 `runToLast` 提供推进时钟的方法。 见 API 详情参考.

### 假扮本地计时器

使用时 `@sinonjs/fake-timers` 到测试定时器时,您很可能想要替换本地 这样的计时器 `setTimeout` 实际为您安排回调 时钟实例,不是浏览器的内部.

通话 `install` 没有论据可以实现这一点。 你可以打电话 `uninstall` 后来恢复原样. 注意在节点JS中 [计时器](https://nodejs.org/api/timers.html) 财务报告和审定财务报表 [计时器/保证](https://nodejs.org/api/timers.html#timers-promises-api) 当 使用全球范围.

```js
// In the browser distribution, a global `FakeTimers` is already available
var FakeTimers = require("@sinonjs/fake-timers");

var clock = FakeTimers.install();
// Equivalent to
// var clock = FakeTimers.install(typeof global !== "undefined" ? global : window);

setTimeout(fn, 15); // Schedules with clock.setTimeout

clock.uninstall();
// setTimeout is restored to the native implementation
```

劫机计时器在另一个背景中传递给 `install` 方法.

```js
var FakeTimers = require("@sinonjs/fake-timers");
var context = {
    setTimeout: setTimeout, // By default context.setTimeout uses the global setTimeout
};
var clock = FakeTimers.withGlobal(context).install();

context.setTimeout(fn, 15); // Schedules with clock.setTimeout

clock.uninstall();
// context.setTimeout is restored to the original implementation
```

通常您想要将定时器安装到全局对象上, 所以调用 `install` 没有争论.

#### 模拟时间自动递增

假时器支持将假时器附加到任何更改中的可能性 在真实的系统时间。 这意味着没有必要 `tick()` 页:1 在你不知道的情况下的时钟 **何时** 调用 `tick()`。 。 。 .

请注意,这是使用最初的设置Immediate()实现的。 API 在一个特定的 可配置间隔 `config.advanceTimeDelta` (默认:20ms). 意义时间会 每20米递增一次,而不是实时.

一个例子是:

```js
var FakeTimers = require("@sinonjs/fake-timers");
var clock = FakeTimers.install({
    shouldAdvanceTime: true,
    advanceTimeDelta: 40,
});

setTimeout(() => {
    console.log("this just timed out"); //executed after 40ms
}, 30);

setImmediate(() => {
    console.log("not so immediate"); //executed after 40ms
});

setTimeout(() => {
    console.log("this timed out after"); //executed after 80ms
    clock.uninstall();
}, 50);
```

除以上外,可以对被嘲笑的时间进行配置以更快地推进 使用 `clock.setTickMode({ mode: "nextAsync" });`时钟 提前到第一个预定的计时器,然后用一个循环点燃它。 在每个计时器之间, 它也会打破事件循环 允许任何预定的约定 要执行的回调 _在此之前_ 运行下一个.

## API 参考

### `var clock = FakeTimers.createClock([now[, loopLimit]])`

创建时钟。 默认 [时代](https://en.wikipedia.org/wiki/Epoch_%28reference_date%29) 实值 `0`。 。 。 .

这个 `now` 参数可以是数字(以毫秒计),a `Date` 对象, a `Temporal.Instant`,或一个 `Temporal.ZonedDateTime`。 。 。 .

这个 `loopLimit` 参数设置调用时运行的最大定时器数 `runAll()` 假设之前 我们有一个无限的回路 并投出一个错误。 默认是 `1000`。 。 。 .

### `var clock = FakeTimers.install([config])`

使用指定的配置安装假时 `0` (关于全球范围的问题). 注意在节点JS中 [计时器](https://nodejs.org/api/timers.html) 财务报告和审定财务报表 [计时器/保证](https://nodejs.org/api/timers.html#timers-promises-api) 当 使用全球范围. 以下配置选项可供选择

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `config.now` | 数字/日期/时间。 即时/即时. ZonedDate Time | 0 个 | 用指定的 unix 时代安装假时 |
| `config.toFake` | 字符串 \[\] | \["设置时通","设置时通","设置时通","设置时通","设置时通","定时通"等\] 加上,当本地有:"设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","性能","请求AnimationFrame","queueMicrotask","celAnimationFrame","设置后通","请求IdleCallback","CancelIdleCallback","Intl","设置时通","设置时通"临时通" | 带有明确函数名的阵列(或物体,如果是“性能”)来劫持。 在未设定时,"假时"会自动伪造出所有方法,例如,,,, `FakeTimers.install({ toFake: ["setTimeout","nextTick"]})` 只会伪造 `setTimeout` 财务报告和审定财务报表 `nextTick`组合 `config.toNotFake`。 。 。 . `"Temporal"` 全部伪造 `Temporal.Now.*` 方法(要求有26+节点或有当地临时支持的环境). |
| `config.toNotFake` | 字符串 \[\] | \[ | 带有明确函数名称的阵列,这些函数名称应保持原生。 设定时,"假时空"会伪造其他支持的方法,例如,, `FakeTimers.install({ toNotFake: ["Date"] })` 伪造所有支持的方法,但 `Date`组合 `config.toFake`。 。 。 . |
| `config.loopLimit` | 数目 | 1 000个 | 调用 runAll () 时运行的最大计时器数 |
| `config.shouldAdvanceTime` | 布尔 | 虚假 | 告诉"假时空"根据实时系统时间倒移自动进行增量模拟时间(例如,被模拟时间在实时系统时间中每改变20ms就会增加20ms) |
| `config.advanceTimeDelta` | 数目 | 20国 | 仅在使用时 `shouldAdvanceTime: true`被嘲笑的时间 `advanceTimeDelta` 分钟每 `advanceTimeDelta` ms在实时系统时间变化. |
| `config.shouldClearNativeTimers` | 布尔 | 虚假 | 告诉"假时"(fakeTimers)通过授权给各自的处理者来清除"本地"(即不是假)计时器. 如果在安装假时器之前存在计时器,这些不默认地被清除,导致潜在的出乎意料的行为. |
| `config.ignoreMissingTimers` | 布尔 | 虚假 | 让"假时空"忽略在特定环境中可能不存在的缺失定时器 |

### `clock.setTickMode(mode)`

允许配置时钟如何自动或手动推进时间.

推进计时器有三种不同的模式:

-   `{mode: 'manual'}`: 计时器在没有明确、手动呼叫勾选时不会前进 APIs (英语:`clock.nextAsync`, (中文(简体) ), `clock.runAllAsync`(见E/CN.4/Sub.2/2002/L.48等)。 此模式相当于 `false`。 。 。 .
-   `{mode: 'nextAsync'}`:时钟会持续地打破事件循环,再运行下个计时器直到模式改变. 因此,测试可以独立于是否安装了假定时器的方式来书写. 测试总是可以被写成等待定时器解决,即使使用假定时器.
-   `{mode: 'interval', delta?: <number>}`: 这与指定相同 `shouldAdvanceTime: true` 带有 `advanceTimeDelta`如果三角洲是 未指定, 将默认使用 20.

“ nextAsync” 模式不同于 `interval` 在两个关键方面:

1.  允许在每次计时器执行间空出微任务队列, 没有安装假定时器的情况也是如此.
2.  它的推进速度越快越好 如果下一个计时器在 排队时间是1000ms,它会立即推进1000ms 而间隔, 在测试中不需要手动推进时间 `1000 / advanceTimeDelta` 实时到达并执行计时器.

### `var id = clock.setTimeout(callback, timeout)`

计划一次发射回调 `timeout` 毫秒已经过去了.

在节点.js `setTimeout` 返回计时器对象。 但是假时空也一样 联合国 `ref()` 财务报告和审定财务报表 `unref()` 方法没有效果.

在浏览器中返回计时器ID.

### `clock.clearTimeout(id)`

清除给定的ID或定时器对象的定时器,只要它使用 `setTimeout`。 。 。 .

### `var id = clock.setInterval(callback, timeout)`

安排每次发射的回调 `timeout` 毫秒已选中 由来.

在节点.js `setInterval` 返回计时器对象。 但是假时空也一样 联合国 `ref()` 财务报告和审定财务报表 `unref()` 方法没有效果.

在浏览器中返回计时器ID.

### `clock.clearInterval(id)`

清除给定的ID或定时器对象的定时器,只要它使用 `setInterval`。 。 。 .

### `var id = clock.setImmediate(callback)`

计划一次发射回调 `0` 毫秒已经过去了 说明 你仍然需要打电话 `clock.tick()` 为召回开火。 若为 一时钟打来电话 召回不会开火直到 `1` 毫秒已选中 由来.

在节点.js `setImmediate` 返回计时器对象。 假时辰也会这样, 但它 `ref()` 财务报告和审定财务报表 `unref()` 方法没有效果.

在浏览器中返回计时器ID.

### `clock.clearImmediate(id)`

清除给定的ID或定时器对象的定时器,只要它使用 `setImmediate`。 。 。 .

### `clock.requestAnimationFrame(callback)`

排出在下个动画框上发射的回调 16个虱子。 返回 a `id` 用于取消回调。 这是 在两个浏览器和节点环境中都可以使用.

### `clock.cancelAnimationFrame(id)`

取消由 ID 安排的调用.

### `clock.requestIdleCallback(callback[, timeout])`

排出空闲期间被放出回调,以进行主事件回调圈的背景和低优先工作. 有超时选项的回调将在毫秒内发射。 返回 a `id` 这可能是 用于取消回调.

### `clock.cancelIdleCallback(id)`

取消由 ID 安排的调用.

### `clock.countTimers()`

返回等待计时器的数量 。 这可以用来断言测试 完成时不漏出任何计时器.

### `clock.hrtime(prevTime?)`

仅在Node.js, mimicks process.hrtime ()中可用.

### `clock.nextTick(callback)`

只有Node.js, 模拟 `process.nextTick` 使测试流程完全同步.

### `clock.performance.now()`

仅在浏览器环境中可用, mimicks performance.now ().

### `clock.tick(time)` 编号 : `await clock.tickAsync(time)`

提前计时,必要时发射回调. `time` 可能为 以可读字符串或 `Temporal.Duration` (要求节点26+或具有本地时间的环境) 支持)。 有效的字符串格式为 `"08"` 8秒钟, `"01:00"` 一个 分钟和 `"02:34:10"` 2小时34分10秒.

这个 `tickAsync()` 也可以打破事件循环,允许任何预定的约定 要执行的回调 _在此之前_ 运行计时器.

### `clock.next()` 编号 : `await clock.nextAsync()`

将钟推进到第一个定时器的时刻,发射.

这个 `nextAsync()` 也可以打破事件循环,允许任何预定的约定 要执行的回调 _在此之前_ 运行计时器.

### `clock.jump(time)`

通过及时跳跃推进时钟,最多一次发射回调. `time` 格式与 [`clock.tick`](https://npmcn.com/package/%40sinonjs/fake-timers/#readme-clockticktime--await-clocktickasynctime)。 。 。 .

这可以用来模拟JS引擎(如浏览器)被放入睡眠后恢复,跳出 中间计时器.

### `clock.reset()`

删除所有计时器和计时器而不发射,并设定 `now` 改为 `config.now` 提供给 `FakeTimers.install` 或改为 `0` 若为 `config.now` 没有提供. 用于重设时钟状态而无需 `uninstall` 财务报告和审定财务报表 `install` 这个.

### `clock.runAll()` 编号 : `await clock.runAllAsync()`

运行所有待定的定时器,直到没有剩余时间为止。 如果在执行时添加了新的计时器, 它们将会是 运行也一样.

这使得在不担心使用计时器数量的情况下进行同步测试以完成比较容易,或者 那些时间的拖延.

它运行最多 `loopLimit` 之后它假设有无限循环的计时器并扔出一个错误.

这个 `runAllAsync()` 也可以打破事件循环,允许任何预定的约定 要执行的回调 _在此之前_ 运行计时器.

### `clock.runMicrotasks()`

这将运行所有预定的未完成的微任务 `nextTick` 但没有计时器,而且对图书馆大多有用 在下方和运行时使用假时间 `nextTick` 没有计时器的项目.

### `clock.runToFrame()`

将时钟提前到下一个帧, 发射所有预定的动画帧回调, 如果有的话,为这个框架以及沿途安排的任何其他计时器.

### `clock.runToLast()` 编号 : `await clock.runToLastAsync()`

注意到运行时的最后一个预定定时器,并推进 时钟到那个时间 发射回调的必要.

如果在执行时添加了新的计时器, 则只能运行它们 将会在这之前发生.

这在您想要运行一个测试到完成时有用, 但测试是递归的 将引发的定时器 `runAll` 以触发无限循环警告.

这个 `runToLastAsync()` 也可以打破事件循环,允许任何预定的约定 要执行的回调 _在此之前_ 运行计时器.

### `clock.setSystemTime([now])`

这模拟了一个用户在程序运行时更改系统时钟. 它影响当前时间,但本身并不导致如定时器起火; 他们将像他们本该做的一样射击,而不召唤 setSystem Time (). (中文). 这个 `now` 参数可以是数字(以毫秒计),a `Date` 对象, a `Temporal.Instant`,或一个 `Temporal.ZonedDateTime`。 。 。 .

### `clock.uninstall()`

恢复原生定时器的原始方法或对象上的方法 被传递到 `FakeTimers.withGlobal`

### `Date`

执行 `Date` 对象,但使用时钟提供正确的时间.

### `Performance`

执行 `now` 方法 [`Performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) 对象,但使用时钟提供正确的时间。 仅在支持性能的环境下可用 对象(主要是浏览器).

### `FakeTimers.withGlobal`

为了支持基于单独或沙盒环境创建时钟(如JSDOM),假时钟输出 a 采用单一参数的工厂方法 `global`,它检查 找出什么可以嘲笑 和什么特点 支助。 当使用全局函数引用此函数时,您将会以 `timers`, (中文(简体) ), `createClock` 财务报告和审定财务报表 `install` - 与常规假时器出口相同,只是根据全球的过去而不是全球的过去 环境.

## 承诺和假时间

如果你像"蓝鸟"一样使用"承诺"图书馆,请注意,你要么打电话 `clock.runMicrotasks()` 或确保 _没有_ 模拟 `nextTick`。 。 。 .

## 正在测试

假时人有一个综合测试套房. 如果你在考虑贡献错误 修正或建议新特性,需要确保您没有损坏任何 测试。 您还需要加入任何新行为的测试 .

### 节点:

```sh
npm test
```

或者,如果你更喜欢动词输出:

```
$(npm bin)/mocha ./test/fake-timers-test.js
```

### 在浏览器中

[模拟](https://github.com/mochify-js) 用于无头测试 克罗姆.

```sh
npm test-headless
```

## 许可证

BSD 3- clause “ 新建” 或“ 修订” 许可证( 见 LICENSE 文件)

## 捐款

`@sinonjs/fake-timers` 使用 JSDoc 在 `src/fake-timers-src.js` 作为它公开类型的真理的来源. TypeScript 声明会从此文件中自动生成. 贡献变化时 :

-   更新联合来文说明 `src/fake-timers-src.js` 如果公共API改变.
-   运行 `npm run types:build` 重新生成在 `types/`。 。 。 .
-   保证 `npm run types:smoke` 仍然通过验证生成的类型.
-   `tsgo` 用作平行验证道,以确保与未来的TypeScript版本相兼容.

## 常见问题

### @sinonjs/fake-timers 是什么？

假 JavaScript 计时器

### 如何安装 @sinonjs/fake-timers？

在项目目录运行 npm install @sinonjs/fake-timers，或使用 pnpm add / yarn add / bun add。

### @sinonjs/fake-timers 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @sinonjs/fake-timers 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @sinonjs/fake-timers 可以商用吗？

@sinonjs/fake-timers 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @sinonjs/fake-timers 的下载量有多少？

根据 npm 官方下载统计，@sinonjs/fake-timers 在 2026/10/07 – 2026/11/05 这 30 天内被下载 305,489,856 次，日均约 10,182,995 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @sinonjs/fake-timers 还在维护吗？

最新版本 15\.4\.0 发布于 2026/05/06（6 个月前）；至今共发布 50 个版本，其中过去 12 个月发布了 11 个；首次发布于 2020/02/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。