Radio 单选框组件 #

基本用法 #

jsx
import { Radio, RadioGroup } from '@chakra-ui/react'

function Example() {
  const [value, setValue] = useState('1')

  return (
    <RadioGroup onChange={setValue} value={value}>
      <HStack spacing={4}>
        <Radio value="1">选项一</Radio>
        <Radio value="2">选项二</Radio>
        <Radio value="3">选项三</Radio>
      </HStack>
    </RadioGroup>
  )
}

单选框状态 #

禁用状态 #

jsx
<Radio isDisabled>禁用单选框</Radio>

只读状态 #

jsx
<Radio isReadOnly>只读单选框</Radio>

无效状态 #

jsx
<Radio isInvalid>无效单选框</Radio>

单选框尺寸 #

jsx
<RadioGroup defaultValue="1">
  <HStack spacing={4}>
    <Radio size="sm" value="1">小</Radio>
    <Radio size="md" value="2">中等(默认)</Radio>
    <Radio size="lg" value="3">大</Radio>
  </HStack>
</RadioGroup>

单选框颜色 #

jsx
<RadioGroup defaultValue="1">
  <HStack spacing={4}>
    <Radio colorScheme="red" value="1">红色</Radio>
    <Radio colorScheme="green" value="2">绿色</Radio>
    <Radio colorScheme="blue" value="3">蓝色</Radio>
    <Radio colorScheme="orange" value="4">橙色</Radio>
  </HStack>
</RadioGroup>

RadioGroup 属性 #

name 属性 #

jsx
<RadioGroup name="my-radio-group" defaultValue="1">
  <HStack>
    <Radio value="1">选项一</Radio>
    <Radio value="2">选项二</Radio>
  </HStack>
</RadioGroup>

onChange 回调 #

jsx
function RadioExample() {
  const [value, setValue] = useState('')

  return (
    <RadioGroup
      onChange={(value) => {
        console.log('选中值:', value)
        setValue(value)
      }}
      value={value}
    >
      <VStack align="start">
        <Radio value="apple">苹果</Radio>
        <Radio value="banana">香蕉</Radio>
        <Radio value="orange">橙子</Radio>
      </VStack>
    </RadioGroup>
  )
}

配合 FormControl #

jsx
import { FormControl, FormLabel, FormHelperText } from '@chakra-ui/react'

function FormRadio() {
  const [value, setValue] = useState('')

  return (
    <FormControl as="fieldset">
      <FormLabel as="legend">选择支付方式</FormLabel>
      <RadioGroup onChange={setValue} value={value}>
        <VStack align="start">
          <Radio value="alipay">支付宝</Radio>
          <Radio value="wechat">微信支付</Radio>
          <Radio value="card">银行卡</Radio>
        </VStack>
      </RadioGroup>
      <FormHelperText>请选择您的支付方式</FormHelperText>
    </FormControl>
  )
}

使用 Stack 布局 #

水平排列 #

jsx
<RadioGroup defaultValue="1">
  <HStack spacing={4}>
    <Radio value="1">选项一</Radio>
    <Radio value="2">选项二</Radio>
    <Radio value="3">选项三</Radio>
  </HStack>
</RadioGroup>

垂直排列 #

jsx
<RadioGroup defaultValue="1">
  <VStack align="start">
    <Radio value="1">选项一</Radio>
    <Radio value="2">选项二</Radio>
    <Radio value="3">选项三</Radio>
  </VStack>
</RadioGroup>

使用 Stack 组件 #

jsx
<RadioGroup defaultValue="1">
  <Stack direction="row" spacing={4}>
    <Radio value="1">选项一</Radio>
    <Radio value="2">选项二</Radio>
    <Radio value="3">选项三</Radio>
  </Stack>
</RadioGroup>

实用示例 #

性别选择 #

jsx
function GenderSelect({ value, onChange }) {
  return (
    <FormControl>
      <FormLabel>性别</FormLabel>
      <RadioGroup value={value} onChange={onChange}>
        <HStack spacing={6}>
          <Radio value="male">男</Radio>
          <Radio value="female">女</Radio>
          <Radio value="other">其他</Radio>
        </HStack>
      </RadioGroup>
    </FormControl>
  )
}

配送方式选择 #

jsx
function ShippingMethod() {
  const [method, setMethod] = useState('standard')

  return (
    <RadioGroup value={method} onChange={setMethod}>
      <VStack align="stretch" spacing={4}>
        <Box p={4} borderWidth="1px" borderRadius="md" borderColor={method === 'standard' ? 'blue.500' : 'gray.200'}>
          <Radio value="standard">
            <HStack justify="space-between" w="full">
              <Box>
                <Text fontWeight="medium">标准配送</Text>
                <Text fontSize="sm" color="gray.500">3-5 个工作日</Text>
              </Box>
              <Text fontWeight="bold">免费</Text>
            </HStack>
          </Radio>
        </Box>
        <Box p={4} borderWidth="1px" borderRadius="md" borderColor={method === 'express' ? 'blue.500' : 'gray.200'}>
          <Radio value="express">
            <HStack justify="space-between" w="full">
              <Box>
                <Text fontWeight="medium">快速配送</Text>
                <Text fontSize="sm" color="gray.500">1-2 个工作日</Text>
              </Box>
              <Text fontWeight="bold">¥15</Text>
            </HStack>
          </Radio>
        </Box>
      </VStack>
    </RadioGroup>
  )
}

评分选择 #

jsx
function RatingSelect({ value, onChange }) {
  return (
    <FormControl>
      <FormLabel>满意度评分</FormLabel>
      <RadioGroup value={value} onChange={onChange}>
        <HStack spacing={2}>
          {[1, 2, 3, 4, 5].map((n) => (
            <Radio key={n} value={String(n)} colorScheme="yellow">
              {n} 星
            </Radio>
          ))}
        </HStack>
      </RadioGroup>
    </FormControl>
  )
}

主题选择 #

jsx
function ThemeSelect() {
  const [theme, setTheme] = useState('light')

  return (
    <FormControl>
      <FormLabel>选择主题</FormLabel>
      <RadioGroup value={theme} onChange={setTheme}>
        <SimpleGrid columns={3} spacing={4}>
          <Box p={4} borderWidth="1px" borderRadius="md" textAlign="center">
            <Radio value="light">浅色</Radio>
          </Box>
          <Box p={4} borderWidth="1px" borderRadius="md" textAlign="center">
            <Radio value="dark">深色</Radio>
          </Box>
          <Box p={4} borderWidth="1px" borderRadius="md" textAlign="center">
            <Radio value="system">跟随系统</Radio>
          </Box>
        </SimpleGrid>
      </RadioGroup>
    </FormControl>
  )
}

Radio 属性速查表 #

属性 说明
value 选项值 string
isChecked 是否选中 true, false
isDisabled 禁用 true, false
isInvalid 无效 true, false
isReadOnly 只读 true, false
size 尺寸 sm, md, lg
colorScheme 颜色方案 blue, green, red…
name 表单名称 string

RadioGroup 属性速查表 #

属性 说明
value 当前选中值 string
defaultValue 默认值 string
onChange 值变化回调 (value: string) => void
name 表单名称 string

下一步 #

现在你已经掌握了 Radio 组件,接下来学习 Switch 开关,了解如何使用开关切换组件!

最后更新:2026-03-28