PIN 码输入

用于捕获用户的 PIN 码或 OTP 码。

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

const Demo = () => {
  return (
    <PinInput.Root>
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

用法

¥Usage

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

<PinInput.Root>
  <PinInput.HiddenInput />
  <PinInput.Control>
    <PinInput.Input />
  </PinInput.Control>
</PinInput.Root>

info

如果你更喜欢封闭的组件组合，请查看以下代码片段。

¥If you prefer a closed component composition, check out the snippet below.

示例

¥Examples

尺寸

¥Sizes

将 size 属性传递给 PinInput.Root 组件，以更改引脚输入组件的大小。

¥Pass the size prop to the PinInput.Root component to change the size of the pin input component

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

const Demo = () => {
  return (
    <Stack gap="4">
      <For each={["sm", "md", "lg"]}>
        {(size) => (
          <PinInput.Root key={size} size={size}>
            <PinInput.HiddenInput />
            <PinInput.Control>
              <PinInput.Input index={0} />
              <PinInput.Input index={1} />
              <PinInput.Input index={2} />
              <PinInput.Input index={3} />
            </PinInput.Control>
          </PinInput.Root>
        )}
      </For>
    </Stack>
  )
}

一次性代码

¥One time code

将 otp 属性传递给 PinInput.Root 组件，使引脚输入组件的行为类似于一次性代码输入。这有助于提升用户输入 OTP 代码时的体验。

¥Pass the otp prop to the PinInput.Root component to make the pin input component behave like a one-time code input. This helps improve the user experience when entering OTP codes

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

const Demo = () => {
  return (
    <PinInput.Root otp>
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

蒙版

¥Mask

将 mask 属性传递给 PinInput.Root 组件，以隐藏输入的 PIN 码。

¥Pass the mask prop to the PinInput.Root component to obscure the entered pin code

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

const Demo = () => {
  return (
    <PinInput.Root mask>
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

占位符

¥Placeholder

将 placeholder 属性传递给 PinInPut.Root 组件以向引脚输入添加占位符。

¥Pass the placeholder prop to the PinInPut.Root component to add a placeholder to the pin input

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

const Demo = () => {
  return (
    <PinInput.Root placeholder="🥳">
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

字段

¥Field

以下是如何组合 Field 和 PinInput 组件的示例。

¥Here's an example of how to compose the Field and the PinInput components

Enter otp

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

const Demo = () => {
  return (
    <Field.Root>
      <Field.Label>Enter otp</Field.Label>
      <PinInput.Root>
        <PinInput.HiddenInput />
        <PinInput.Control>
          <PinInput.Input index={0} />
          <PinInput.Input index={1} />
          <PinInput.Input index={2} />
          <PinInput.Input index={3} />
        </PinInput.Control>
      </PinInput.Root>
    </Field.Root>
  )
}

钩子表单

¥Hook Form

以下是如何将 Field 和 PinInput 组件与 react-hook-form 组合的示例。

¥Here's an example of how to compose the Field and the PinInput components with react-hook-form

"use client"

import { Button, Field, PinInput, Stack } 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({
  pin: z
    .array(z.string().min(1), { required_error: "Pin is required" })
    .length(4, { message: "Pin must be 4 digits long" }),
})

type FormValues = z.infer<typeof formSchema>

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

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

  return (
    <form onSubmit={onSubmit}>
      <Stack gap="4" align="flex-start" maxW="sm">
        <Field.Root invalid={!!formState.errors.pin}>
          <Controller
            control={control}
            name="pin"
            render={({ field }) => (
              <PinInput.Root
                value={field.value}
                onValueChange={(e) => field.onChange(e.value)}
              >
                <PinInput.HiddenInput />
                <PinInput.Control>
                  <PinInput.Input index={0} />
                  <PinInput.Input index={1} />
                  <PinInput.Input index={2} />
                  <PinInput.Input index={3} />
                </PinInput.Control>
              </PinInput.Root>
            )}
          />
          <Field.ErrorText>{formState.errors.pin?.message}</Field.ErrorText>
        </Field.Root>
        <Button type="submit">Submit</Button>
      </Stack>
    </form>
  )
}

受控

¥Controlled

将 value 和 onValueChange 属性传递给 PinInPut.Root 组件，以控制引脚输入的值。

¥Pass the value and onValueChange props to the PinInPut.Root component to control the value of the pin input

"use client"

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

const Demo = () => {
  const [value, setValue] = useState(["", "", "", ""])
  return (
    <PinInput.Root value={value} onValueChange={(e) => setValue(e.value)}>
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

商店

¥Store

控制引脚输入的另一种方法是使用 RootProvider 组件和 usePinInput 存储钩子。

¥An alternative way to control the pin input is to use the RootProvider component and the usePinInput store hook.

这样，你就可以从组件外部访问引脚输入状态和方法。

¥This way you can access the pin input state and methods from outside the component.

"use client"

import {
  Button,
  ButtonGroup,
  PinInput,
  Stack,
  usePinInput,
} from "@chakra-ui/react"

const Demo = () => {
  const store = usePinInput()
  return (
    <Stack align="flex-start">
      <PinInput.RootProvider value={store}>
        <PinInput.Control>
          <PinInput.Input index={0} />
          <PinInput.Input index={1} />
          <PinInput.Input index={2} />
          <PinInput.Input index={3} />
        </PinInput.Control>
      </PinInput.RootProvider>

      <ButtonGroup variant="outline" size="sm">
        <Button onClick={() => store.setValue(["1", "2", "3", "4"])}>
          Set value
        </Button>
        <Button onClick={() => store.clearValue()}>Clear value</Button>
      </ButtonGroup>
    </Stack>
  )
}

已附加

¥Attached

将 attached 属性传递给 PinInput.Root 组件以将引脚输入附加到输入字段。

¥Pass the attached prop to the PinInput.Root component to attach the pin input to the input field

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

const Demo = () => {
  return (
    <PinInput.Root attached>
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

字母数字

¥Alphanumeric

将 type 属性传递给 PinInput.Root 组件以允许用户输入字母数字字符。值可以是 alphanumeric、numeric 或 alphabetic

¥Pass the type prop to the PinInput.Root component to allow the user to enter alphanumeric characters. Values can be either alphanumeric, numeric, or alphabetic

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

const Demo = () => {
  return (
    <PinInput.Root type="alphanumeric">
      <PinInput.HiddenInput />
      <PinInput.Control>
        <PinInput.Input index={0} />
        <PinInput.Input index={1} />
        <PinInput.Input index={2} />
        <PinInput.Input index={3} />
      </PinInput.Control>
    </PinInput.Root>
  )
}

已关闭组件

¥Closed Component

以下是如何设置封闭组件组合的引脚输入。

¥Here's how to setup the Pin input for a closed component composition.

import { PinInput as ChakraPinInput, Group } from "@chakra-ui/react"
import * as React from "react"

export interface PinInputProps extends ChakraPinInput.RootProps {
  rootRef?: React.RefObject<HTMLDivElement | null>
  count?: number
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>
  attached?: boolean
}

export const PinInput = React.forwardRef<HTMLInputElement, PinInputProps>(
  function PinInput(props, ref) {
    const { count = 4, inputProps, rootRef, attached, ...rest } = props
    return (
      <ChakraPinInput.Root ref={rootRef} {...rest}>
        <ChakraPinInput.HiddenInput ref={ref} {...inputProps} />
        <ChakraPinInput.Control>
          <Group attached={attached}>
            {Array.from({ length: count }).map((_, index) => (
              <ChakraPinInput.Input key={index} index={index} />
            ))}
          </Group>
        </ChakraPinInput.Control>
      </ChakraPinInput.Root>
    )
  },
)

用法

¥Usage

<PinInput mask />

属性

¥Props

根元素

¥Root

Prop	Default	Type
`placeholder`	`'\'○\''`	`string` The placeholder text for the input
`type`	`'\'numeric\''`	`'numeric' \| 'alphabetic' \| 'alphanumeric'` The type of value the pin-input should allow
`colorPalette`	`'gray'`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` The color palette of the component
`size`	`'md'`	`'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` The size of the component
`variant`	`'outline'`	`'outline' \| 'subtle' \| 'flushed'` The variant of the component
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`unstyled`		`boolean` Whether to remove the component's style.
`autoFocus`		`boolean` Whether to auto-focus the first input.
`blurOnComplete`		`boolean` Whether to blur the input when the value is complete
`count`		`number` The number of inputs to render to improve SSR aria attributes. This will be required in next major version.
`defaultValue`		`string[]` The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input.
`disabled`		`boolean` Whether the inputs are disabled
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string hiddenInput: string label: string control: string input: (id: string) => string }>` The ids of the elements in the pin input. Useful for composition.
`invalid`		`boolean` Whether the pin input is in the invalid state
`mask`		`boolean` If `true`, the input's value will be masked just like `type=password`
`name`		`string` The name of the input element. Useful for form submission.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called on input change
`onValueComplete`		`(details: ValueChangeDetails) => void` Function called when all inputs have valid values
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function called when an invalid value is entered
`otp`		`boolean` If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`.
`pattern`		`string` The regular expression that the user-entered input value is checked against.
`readOnly`		`boolean` Whether the pin input is in the valid state
`required`		`boolean` Whether the pin input is required
`selectOnFocus`		`boolean` Whether to select input value when input is focused
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`string[]` The controlled value of the the pin input.
`attached`		`'true' \| 'false'` The attached of the component

密码输入

单选按钮卡片

PIN 码输入

.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;}用法

用法