useCounter

跟踪数值的 React hook。

useCounter 管理一个整数计数器，内置 inc、dec、set 和 reset 函数。它返回一个 [current, set, inc, dec, reset] 元组。你可以选择指定 max 和 min 边界；计数器将被钳制在这些限制内。初始值默认为 0，可以是数字或返回数字的函数。

使用场景

  • 实现数量选择器、分页控件或步进器输入
  • 跟踪带有强制最小/最大边界的分数、投票或项目计数
  • 任何受益于专用递增、递减和重置操作的数值状态

注意事项

  • 有界值：当提供 max 或 min 时，每次操作后计数器都会被钳制。设置超出边界的值将被静默调整。
  • SSR 安全：内部仅使用 React 状态，无浏览器 API 依赖。
  • 参见 useCycleList 了解在固定列表项目之间循环而非开放的数值范围。

Usage

Live Editor

function Demo() {
  const [current, set, inc, dec, reset] = useCounter(10, 100, 1);

  return (
    <div>
      <p>{current} 最大值: 100; 最小值: 1;</p>
      <div>
        <button
          type="button"
          onClick={() => {
            inc();
          }}
          style={{ marginRight: 8 }}
        >
          inc()
        </button>
        <button
          type="button"
          onClick={() => {
            dec();
          }}
          style={{ marginRight: 8 }}
        >
          dec()
        </button>
        <button
          type="button"
          onClick={() => {
            set(3);
          }}
          style={{ marginRight: 8 }}
        >
          set(3)
        </button>
        <button type="button" onClick={reset} style={{ marginRight: 8 }}>
          reset()
        </button>
      </div>
    </div>
  );
};
Result

API

useCounter

Returns

readonly [number, (newState: number | ((prev: number) => number) | (() => number)) => void, (delta?: number | undefined) => void, (delta?: number | undefined) => void, () => void]: 包含以下元素的元组：

  • 计数器的当前值。
  • 设置计数器状态的函数。 它可以接受数字或返回数字的函数。
  • 递增计数器的函数。 它可以选择接受一个数字来增加计数器，默认为 1。
  • 递减计数器的函数。 它可以选择接受一个数字来减少计数器，默认为 1。
  • 将计数器重置为其初始值的函数。

Arguments

参数名描述类型默认值
initialValue初始值，可以为数字或者一个初始化的函数number | (() => number) | undefined0
max最大值。不提供则无上限number | null | undefined-
min最小值。不提供则无下限number | null | undefined-