气泡卡片

用于在弹出框中显示详细信息

import { Button, Input, Popover, Portal, Text } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              <Popover.Title fontWeight="medium">Naruto Form</Popover.Title>
              <Text my="4">
                Naruto is a Japanese manga series written and illustrated by
                Masashi Kishimoto.
              </Text>
              <Input placeholder="Your fav. character" size="sm" />
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

用法

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

<Popover.Root>
  <Popover.Trigger />
  <Popover.Positioner>
    <Popover.Content>
      <Popover.CloseTrigger />
      <Popover.Arrow>
        <Popover.ArrowTip />
      </Popover.Arrow>
      <Popover.Body>
        <Popover.Title />
      </Popover.Body>
    </Popover.Content>
  </Popover.Positioner>
</Popover.Root>

快捷方式

Popover 为常见用例提供了快捷方式。

箭头

Popover.Arrow 默认在其中渲染 Popover.ArrowTip 组件。

这可行

<Popover.Arrow>
  <Popover.ArrowTip />
</Popover.Arrow>

如果您不需要自定义箭头提示，这可能更简洁。

<Popover.Arrow />

示例

受控

使用 open 和 onOpenChange 来控制气泡卡片的可见性。

"use client"

import { Button, Popover, Portal } from "@chakra-ui/react"
import { useState } from "react"

const Demo = () => {
  const [open, setOpen] = useState(false)
  return (
    <Popover.Root open={open} onOpenChange={(e) => setOpen(e.open)}>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              This is a popover with the same width as the trigger button
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

尺寸

使用 size 属性来改变气泡卡片组件的尺寸。

import {
  Button,
  For,
  Input,
  Popover,
  Portal,
  Stack,
  Text,
} from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack align="center" direction="row" gap="10">
      <For each={["xs", "sm", "md", "lg"]}>
        {(size) => (
          <Popover.Root key={size} size={size}>
            <Popover.Trigger asChild>
              <Button size={size} variant="outline">
                Click me
              </Button>
            </Popover.Trigger>
            <Portal>
              <Popover.Positioner>
                <Popover.Content>
                  <Popover.Arrow />
                  <Popover.Body>
                    <Popover.Title fontWeight="medium">
                      Naruto Form
                    </Popover.Title>
                    <Text my="4">
                      Naruto is a Japanese manga series written and illustrated
                      by Masashi Kishimoto.
                    </Text>
                    <Input placeholder="Your fav. character" size={size} />
                  </Popover.Body>
                </Popover.Content>
              </Popover.Positioner>
            </Portal>
          </Popover.Root>
        )}
      </For>
    </Stack>
  )
}

延迟挂载

使用 lazyMounted 和/或 unmountOnExit 属性来延迟挂载气泡卡片内容，直到其被打开。

import { Button, Popover, Portal, Text } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root lazyMount unmountOnExit>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              <Popover.Title fontWeight="medium">Naruto Form</Popover.Title>
              <Text my="4">
                Naruto is a Japanese manga series written and illustrated by
                Masashi Kishimoto.
              </Text>
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

定位

使用 positioning.placement 属性来配置底层的 floating-ui 定位逻辑。

import { Button, Popover, Portal } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root positioning={{ placement: "bottom-end" }}>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>Some content</Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

偏移

使用 positioning.offset 属性来调整气泡卡片内容的位置。

import { Button, Popover, Portal } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root positioning={{ offset: { crossAxis: 0, mainAxis: 0 } }}>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Open
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Body>
              This popover has a custom offset from its trigger
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

等宽

使用 positioning.sameWidth 属性使气泡卡片内容与触发器等宽。

import { Button, Popover, Portal } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root positioning={{ sameWidth: true }}>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline" minW="xs">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content width="auto">
            <Popover.Arrow />
            <Popover.Body>
              This is a popover with the same width as the trigger button
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

当在气泡卡片内部嵌套气泡卡片、选择框、菜单等叠加元素时，请将它们的 portalled 属性设置为 false。

这是一个嵌套气泡卡片的示例。

import { Button, Popover, Portal, Text } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              <Text mb="4">
                Naruto is a Japanese manga series written and illustrated by
                Masashi Kishimoto.
              </Text>

              <Popover.Root>
                <Popover.Trigger asChild>
                  <Button variant="outline" size="xs">
                    Open Nested Popover
                  </Button>
                </Popover.Trigger>
                <Popover.Positioner>
                  <Popover.Content>
                    <Popover.Arrow />
                    <Popover.Body>Some nested popover content</Popover.Body>
                  </Popover.Content>
                </Popover.Positioner>
              </Popover.Root>
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

初始焦点

使用 initialFocusEl 属性来设置气泡卡片内容的初始焦点。

"use client"

import { Box, Button, Group, Popover, Portal } from "@chakra-ui/react"
import { useRef } from "react"

const Demo = () => {
  const ref = useRef<HTMLButtonElement | null>(null)
  return (
    <Popover.Root initialFocusEl={() => ref.current}>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Header>Manage Your Channels</Popover.Header>
            <Popover.Arrow />
            <Popover.Body>
              This is a popover with the same width as the trigger button
            </Popover.Body>
            <Popover.Footer>
              <Box fontSize="sm" flex="1">
                Step 2 of 4
              </Box>
              <Group>
                <Button size="sm" ref={ref}>
                  Prev
                </Button>
                <Button size="sm">Next</Button>
              </Group>
            </Popover.Footer>
            <Popover.CloseTrigger />
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

表单

这是一个内部包含表单的气泡卡片示例。

import {
  Button,
  Field,
  Input,
  Popover,
  Portal,
  Stack,
  Textarea,
} from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              <Stack gap="4">
                <Field.Root>
                  <Field.Label>Width</Field.Label>
                  <Input placeholder="40px" />
                </Field.Root>
                <Field.Root>
                  <Field.Label>Height</Field.Label>
                  <Input placeholder="32px" />
                </Field.Root>
                <Field.Root>
                  <Field.Label>Comments</Field.Label>
                  <Textarea placeholder="Start typing..." />
                </Field.Root>
              </Stack>
            </Popover.Body>
            <Popover.CloseTrigger />
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

自定义背景

使用 --popover-bg CSS 变量来改变气泡卡片内容及其箭头的背景颜色。

import { Button, Input, Popover, Portal, Text } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content css={{ "--popover-bg": "lightblue" }}>
            <Popover.Arrow />
            <Popover.Body>
              <Popover.Title fontWeight="medium">Naruto Form</Popover.Title>
              <Text my="4">
                Naruto is a Japanese manga series written and illustrated by
                Masashi Kishimoto.
              </Text>
              <Input bg="bg" placeholder="Your fav. character" size="sm" />
            </Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

在对话框内

要在 Dialog 中使用 Popover，您需要避免将 Popover.Positioner 传送到文档的 body 中。

-<Portal>
  <Popover.Positioner>
    <Popover.Content>
      {/* ... */}
    </Popover.Content>
  </Popover.Positioner>
-</Portal>

"use client"

import {
  Button,
  CloseButton,
  Dialog,
  Popover,
  Portal,
  Text,
} from "@chakra-ui/react"

const Demo = () => {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <Button variant="outline">Open Dialog</Button>
      </Dialog.Trigger>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            <Dialog.CloseTrigger asChild>
              <CloseButton />
            </Dialog.CloseTrigger>
            <Dialog.Header>
              <Dialog.Title>Popover in Dialog</Dialog.Title>
            </Dialog.Header>
            <Dialog.Body>
              <DialogPopover />
            </Dialog.Body>
            <Dialog.Footer />
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

function DialogPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Popover.Positioner>
        <Popover.Content>
          <Popover.Arrow />
          <Popover.Body>
            <Popover.Title fontWeight="medium">Naruto Form</Popover.Title>
            <Text my="4">
              Naruto is a Japanese manga series written and illustrated by
              Masashi Kishimoto.
            </Text>
          </Popover.Body>
        </Popover.Content>
      </Popover.Positioner>
    </Popover.Root>
  )
}

属性

根

属性	默认值	类型
`autoFocus`	`true`	`boolean` 打开气泡卡片时，是否自动将焦点设置在气泡卡片内的第一个可聚焦内容上。
`closeOnEscape`	`true`	`boolean` 按下 Esc 键时是否关闭气泡卡片。
`closeOnInteractOutside`	`true`	`boolean` 当用户点击气泡卡片外部时是否关闭气泡卡片。
`lazyMount`	`false`	`boolean` 是否启用延迟挂载
`modal`	`false`	`boolean` 气泡卡片是否应为模态。当设置为 `true` 时： - 与外部元素的交互将被禁用 - 只有气泡卡片内容对屏幕阅读器可见 - 滚动被阻止 - 焦点被限制在气泡卡片内
`portalled`	`true`	`boolean` 气泡卡片是否被传送。这将代理制表符行为，无论气泡卡片内容的 DOM 位置如何。
`unmountOnExit`	`false`	`boolean` 退出时是否卸载。
`colorPalette`	`'gray'`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` 组件的调色板
`size`	`'md'`	`'xs' \| 'sm' \| 'md' \| 'lg'` 组件的尺寸
`defaultOpen`		`boolean` 气泡卡片首次渲染时的初始打开状态。当您不需要控制其打开状态时使用。
`id`		`string` 机器的唯一标识符。
`ids`		`Partial<{ anchor: string trigger: string content: string title: string description: string closeTrigger: string positioner: string arrow: string }>` 气泡卡片中元素的 ID。对于组合非常有用。
`immediate`		`boolean` 是否立即同步当前更改或将其推迟到下一帧
`initialFocusEl`		`() => HTMLElement \| null` 气泡卡片打开时要聚焦的元素。
`onEscapeKeyDown`		`(event: KeyboardEvent) => void` 按下 Esc 键时调用的函数
`onExitComplete`		`() => void` 动画在关闭状态下结束时调用的函数
`onFocusOutside`		`(event: FocusOutsideEvent) => void` 焦点移出组件时调用的函数
`onInteractOutside`		`(event: InteractOutsideEvent) => void` 组件外部发生交互时调用的函数
`onOpenChange`		`(details: OpenChangeDetails) => void` 气泡卡片打开或关闭时调用的函数
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` 指针在组件外部按下时调用的函数
`open`		`boolean` 气泡卡片是否打开
`persistentElements`		`(() => Element \| null)[]` 返回持续存在的元素，这些元素： - 不应禁用指针事件 - 不应触发关闭事件
`positioning`		`PositioningOptions` 用户提供的用于定位气泡卡片内容的选项
`present`		`boolean` 节点是否存在（由用户控制）
`as`		`React.ElementType` 要渲染的底层元素。
`asChild`		`boolean` 使用提供的子元素作为默认渲染元素，结合它们的属性和行为。更多详情，请阅读我们的组合指南。
`unstyled`		`boolean` 是否移除组件的样式。

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

用法