FinalizationRegistry.prototype.register()

Baseline 广泛可用 *

此特性已得到良好支持,可在多种设备和浏览器版本上使用。自 2021 年 4 月起,所有浏览器均已支持此特性。

* 此特性的某些部分可能存在不同级别的支持。

register() 方法用于将一个值注册到 FinalizationRegistry 实例中,以便在该值被垃圾回收时,可以调用注册表的 [callback function](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#callback_function) 。

语法

js
register(target, heldValue)
register(target, heldValue, unregisterToken)

参数

目标

要注册的目标值。

heldValue

要传递给此 target 的 finalizer 的值。它不能是 target 本身,但可以是任何其他内容,包括函数和原始类型。

unregisterToken 可选

一个可用于稍后通过 unregister 方法取消注册目标值的 token。如果提供了此参数(且不为 undefined),则它必须是一个对象或一个 [未注册的 Symbol](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry)。如果未提供,则无法取消注册目标。

返回值

无(undefined)。

异常

TypeError

在以下情况之一中抛出

  • target 不是一个对象或一个 [未注册的 Symbol](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry)(与原始类型相对,函数也是对象)
  • targetheldValue 相同 (target === heldValue)
  • unregisterToken 不是一个对象或一个 [未注册的 Symbol](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry)

描述

有关重要的注意事项,请参阅 FinalizationRegistry 页面的 [Avoid where possible](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#avoid_where_possible) 和 [Notes on cleanup callbacks](https://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#notes_on_cleanup_callbacks) 部分。

示例

使用 register

以下代码注册了由 target 引用的值,传递了 held 值 "some value",并将 target 本身作为 unregistration token:

js
registry.register(target, "some value", target);

以下代码注册了由 target 引用的值,传递了另一个对象作为 held 值,并且没有传递任何 unregistration token(这意味着 target 无法被取消注册):

js
registry.register(target, { useful: "info about target" });

规范

规范
ECMAScript® 2026 语言规范
# sec-finalization-registry.prototype.register

浏览器兼容性

另见