数字输入框

用于输入数字，并使用步进按钮增加或减少值。

import { NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="10" width="200px">
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

用法

import { NumberInput } from "@chakra-ui/react"

<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.ValueText />
  <NumberInput.Control>
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
  <NumberInput.Scrubber />
  <NumberInput.Input />
</NumberInput.Root>

信息

如果您喜欢封闭式组件组合，请查看下面的代码片段。

快捷方式

NumberInput 组件提供了一组常用用例的快捷方式

NumberInputControl

此组件默认在其内部渲染 NumberInput.IncrementTrigger 和 NumberInput.DecrementTrigger。

写成这样

<NumberInput.Control />

如果您不需要自定义触发器，这是写成这样的简写形式

<NumberInput.Control>
  <NumberInput.IncrementTrigger />
  <NumberInput.DecrementTrigger />
</NumberInput.Control>

示例

尺寸

将 size 属性传递给 NumberInput.Root 组件以更改数字输入框的尺寸。

import { For, NumberInput, Stack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack gap="5" width="200px">
      <For each={["xs", "sm", "md", "lg"]}>
        {(size) => (
          <NumberInput.Root size={size} key={size} defaultValue="10">
            <NumberInput.Control />
            <NumberInput.Input />
          </NumberInput.Root>
        )}
      </For>
    </Stack>
  )
}

格式化

将 formatOptions 属性传递给 NumberInput.Root 组件以格式化数字输入值。此属性的值映射到 Intl.NumberFormatOptions 并根据当前区域设置应用。

import { NumberInput, Stack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack gap="5" maxW="200px">
      <NumberInput.Root
        defaultValue="5"
        step={0.01}
        formatOptions={{
          style: "percent",
        }}
      >
        <NumberInput.Control />
        <NumberInput.Input />
      </NumberInput.Root>

      <NumberInput.Root
        defaultValue="45"
        formatOptions={{
          style: "currency",
          currency: "EUR",
          currencyDisplay: "code",
          currencySign: "accounting",
        }}
      >
        <NumberInput.Control />
        <NumberInput.Input />
      </NumberInput.Root>

      <NumberInput.Root
        defaultValue="4"
        formatOptions={{
          style: "unit",
          unit: "inch",
          unitDisplay: "long",
        }}
      >
        <NumberInput.Control />
        <NumberInput.Input />
      </NumberInput.Root>
    </Stack>
  )
}

最小值和最大值

将 min 和 max 属性传递给 NumberInput.Root 组件以设置数字输入框的最小值和最大值。

如果输入的值小于 min 或大于 max，则在失焦或按下回车键时，该值将被限制在最近的边界。

import { NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <NumberInput.Root width="200px" defaultValue="10" min={5} max={50}>
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

步长

将 step 属性传递给 NumberInput.Root 组件以更改数字输入框的增量或减量间隔。

import { NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <NumberInput.Root maxW="200px" defaultValue="2" step={3}>
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

受控

将 value 和 onValueChange 属性传递给 NumberInput.Root 组件以控制数字输入框的值。

"use client"

import { NumberInput } from "@chakra-ui/react"
import { useState } from "react"

const Demo = () => {
  const [value, setValue] = useState("10")
  return (
    <NumberInput.Root
      maxW="200px"
      value={value}
      onValueChange={(e) => setValue(e.value)}
    >
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

移动步进器

这是一个如何将数字输入框组合为移动步进器的示例。

import { HStack, IconButton, NumberInput } from "@chakra-ui/react"
import { LuMinus, LuPlus } from "react-icons/lu"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="3" unstyled spinOnPress={false}>
      <HStack gap="2">
        <NumberInput.DecrementTrigger asChild>
          <IconButton variant="outline" size="sm">
            <LuMinus />
          </IconButton>
        </NumberInput.DecrementTrigger>
        <NumberInput.ValueText textAlign="center" fontSize="lg" minW="3ch" />
        <NumberInput.IncrementTrigger asChild>
          <IconButton variant="outline" size="sm">
            <LuPlus />
          </IconButton>
        </NumberInput.IncrementTrigger>
      </HStack>
    </NumberInput.Root>
  )
}

鼠标滚轮

将 allowMouseWheel 属性传递给 NumberInput.Root 组件以启用或禁用鼠标滚轮更改值

import { NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="10" width="200px" allowMouseWheel>
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

禁用

将 disabled 属性传递给 NumberInput.Root 组件以禁用数字输入框。

import { NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="10" width="200px" disabled>
      <NumberInput.Control />
      <NumberInput.Input />
    </NumberInput.Root>
  )
}

无效

使用 Field 组件和 invalid 属性来指示数字输入框无效。

输入数字

输入无效

import { Field, NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root invalid>
      <Field.Label>Enter Number</Field.Label>
      <NumberInput.Root defaultValue="10" width="200px">
        <NumberInput.Control />
        <NumberInput.Input />
      </NumberInput.Root>
      <Field.ErrorText>The entry is invalid</Field.ErrorText>
    </Field.Root>
  )
}

辅助文本

组合 Field 和 Field.HelperText 组件，为数字输入框添加辅助文本。

输入数字

输入一个介于1到10之间的数字

import { Field, NumberInput } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Enter Number</Field.Label>
      <NumberInput.Root width="200px">
        <NumberInput.Control />
        <NumberInput.Input />
      </NumberInput.Root>
      <Field.HelperText>Enter a number between 1 and 10</Field.HelperText>
    </Field.Root>
  )
}

元素

这是一个如何将数字输入框与输入组组件组合，以在左侧或右侧添加元素的示例。

import { InputGroup, NumberInput } from "@chakra-ui/react"
import { LuDollarSign } from "react-icons/lu"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="10" width="200px">
      <NumberInput.Control />
      <InputGroup startElement={<LuDollarSign />}>
        <NumberInput.Input />
      </InputGroup>
    </NumberInput.Root>
  )
}

微调器

使用 NumberInput.Scrubber 组件，使数字输入框支持微调交互。

import { InputGroup, NumberInput } from "@chakra-ui/react"
import { LuArrowRightLeft } from "react-icons/lu"

const Demo = () => {
  return (
    <NumberInput.Root defaultValue="10" width="200px">
      <NumberInput.Control />
      <InputGroup
        startElementProps={{ pointerEvents: "auto" }}
        startElement={
          <NumberInput.Scrubber>
            <LuArrowRightLeft />
          </NumberInput.Scrubber>
        }
      >
        <NumberInput.Input />
      </InputGroup>
    </NumberInput.Root>
  )
}

Hook Form

这是如何将 NumberInput 组件与 react-hook-form 配合使用的示例。

"use client"

import { Button, Field, NumberInput } from "@chakra-ui/react"
import { zodResolver } from "@hookform/resolvers/zod"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"

const formSchema = z.object({
  number: z.string({ message: "Number is required" }),
})

type FormValues = z.infer<typeof formSchema>

const Demo = () => {
  const {
    control,
    handleSubmit,
    formState: { errors },
  } = useForm<FormValues>({
    resolver: zodResolver(formSchema),
  })

  const onSubmit = handleSubmit((data) => console.log(data))

  return (
    <form onSubmit={onSubmit}>
      <Field.Root invalid={!!errors.number}>
        <Field.Label>Number</Field.Label>
        <Controller
          name="number"
          control={control}
          render={({ field }) => (
            <NumberInput.Root
              disabled={field.disabled}
              name={field.name}
              value={field.value}
              onValueChange={({ value }) => {
                field.onChange(value)
              }}
            >
              <NumberInput.Control />
              <NumberInput.Input onBlur={field.onBlur} />
            </NumberInput.Root>
          )}
        />
        <Field.ErrorText>{errors.number?.message}</Field.ErrorText>
      </Field.Root>
      <Button size="sm" type="submit" mt="4">
        Submit
      </Button>
    </form>
  )
}

封闭组件

以下是如何为封闭式组件组合设置数字输入框。

import { NumberInput as ChakraNumberInput } from "@chakra-ui/react"
import * as React from "react"

export interface NumberInputProps extends ChakraNumberInput.RootProps {}

export const NumberInputRoot = React.forwardRef<
  HTMLDivElement,
  NumberInputProps
>(function NumberInput(props, ref) {
  const { children, ...rest } = props
  return (
    <ChakraNumberInput.Root ref={ref} variant="outline" {...rest}>
      {children}
      <ChakraNumberInput.Control>
        <ChakraNumberInput.IncrementTrigger />
        <ChakraNumberInput.DecrementTrigger />
      </ChakraNumberInput.Control>
    </ChakraNumberInput.Root>
  )
})

export const NumberInputField = ChakraNumberInput.Input
export const NumberInputScrubber = ChakraNumberInput.Scrubber
export const NumberInputLabel = ChakraNumberInput.Label

如果您想自动将封闭组件添加到您的项目中，请运行此命令

npx @chakra-ui/cli snippet add number-input

以下是使用方法

<NumberInputRoot>
  <NumberInputField />
</NumberInputRoot>

属性

根 (Root)

属性	默认	类型
`allowOverflow`	`true`	`boolean` 是否允许值超出最小值/最大值范围
`clampValueOnBlur`	`true`	`boolean` 输入框失焦时是否限制值
`focusInputOnChange`	`true`	`boolean` 值改变时是否聚焦输入框
`inputMode`	`'\'decimal\''`	`InputMode` 提示用户可能输入的数据类型。它还决定了移动设备上向用户显示的键盘类型。
`locale`	`'\'en-US\''`	`string` 当前区域设置。基于 BCP 47 定义。
`max`	`'Number.MAX_SAFE_INTEGER'`	`number` 数字输入框的最大值
`min`	`'Number.MIN_SAFE_INTEGER'`	`number` 数字输入框的最小值
`pattern`	`'\'[0-9]*(.[0-9]+)?\''`	`string` 用于检查 <input> 元素值是否符合的模式
`spinOnPress`	`true`	`boolean` 按下增加/减少按钮时是否旋转值
`step`	`'1'`	`number` 增加或减少值的量
`colorPalette`	`'gray'`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` 组件的调色板
`size`	`'md'`	`'xs' \| 'sm' \| 'md' \| 'lg'` 组件的尺寸
`variant`	`'outline'`	`'outline' \| 'subtle' \| 'flushed'` 组件的变体
`allowMouseWheel`		`boolean` 是否允许鼠标滚轮更改值
`asChild`		`boolean` 使用提供的子元素作为默认渲染元素，结合它们的属性和行为。更多详情，请阅读我们的组合指南。
`defaultValue`		`string` 数字输入框首次渲染时的初始值。在您不需要控制数字输入框状态时使用。
`disabled`		`boolean` 数字输入框是否被禁用。
`form`		`string` 输入元素的关联表单。
`formatOptions`		`NumberFormatOptions` 传递给 `Intl.NumberFormat` 构造函数的选项
`id`		`string` 机器的唯一标识符。
`ids`		`Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` 数字输入框中元素的ID。对组合很有用。
`invalid`		`boolean` 数字输入框的值是否无效。
`name`		`string` 数字输入框的名称属性。对表单提交很有用。
`onFocusChange`		`(details: FocusChangeDetails) => void` 数字输入框聚焦时调用的函数
`onValueChange`		`(details: ValueChangeDetails) => void` 值改变时调用的函数
`onValueInvalid`		`(details: ValueInvalidDetails) => void` 值超出或低于最小值/最大值范围时调用的函数
`readOnly`		`boolean` 数字输入框是否为只读
`required`		`boolean` 数字输入框是否为必填
`translations`		`IntlTranslations` 指定标识可访问性元素及其状态的本地化字符串
`value`		`string` 输入框的值

菜单

分页

数字输入框

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}用法

用法