# 组合框弹层 - 页面: https://jiguang132.com/zh/resources/mantine/docs/combobox-popover - 资源: Mantine Core (https://jiguang132.com/zh/resources/mantine.md) - 全部指南: https://jiguang132.com/zh/resources/mantine/docs.md Mantine Core 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。 ## 安装 ```bash npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1 ``` 入口引入 `@mantine/core/styles.css`，并在根组件使用 `MantineProvider`；通过 `forceColorScheme` 同步深浅色主题。 ## 使用与验证 在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。 ## 来源 https://github.com/mantinedev/mantine/tree/f0e2bc6d28b0f0b8aaefb5b859937bf77f539df7 MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。 --- ## 版本与兼容性 固定的 Mantine Core 9.7.1 要求 React 和 React DOM 满足 `^19.2.0`，并配套 `@mantine/hooks@9.7.1`。此条件来自实际 npm 包的 peerDependencies。React 18 或其他不兼容版本不能强行安装；先向项目负责人说明升级影响并确认方案，不使用 --force/--legacy-peer-deps 掩盖冲突。入口的原生 Provider 开启 `theme.respectReducedMotion`，并用 `forceColorScheme` 控制深浅色。 ## 适用场景 在气泡弹层内组合可搜索选择器。 ## 本地示例使用的原生参数 以下参数由本地、经过类型检查的 JSX 示例提取，按所属组件区分。不是全部属性清单；完整签名和继承关系见下方固定源码参考。 | 组件参数 | 说明 | | --- | --- | | `ComboboxPopover.data` | 本地选项或节点，保持 value 唯一并遵循原生结构。 | | `ComboboxPopover.searchable` | 启用当前组件的本地搜索交互。 | | `ComboboxPopover.value` | 受控值，具体结构由原生类型定义。 | | `ComboboxPopover.onChange` | 原生值或事件回调，保留实际函数签名。 | ## 交互与状态检查 当前场景：默认。切换支持的禁用、错误或只读场景后检查真实行为；无此原生状态的组件不会被强行添加统一属性。验证键盘焦点和退出方式，修改值后按原生回调签名连接业务状态。 ## 业务接入边界 Target 必须接受触发器传入的 props/ref。除非宿主提供远程数据，否则搜索只在本地执行。 ## 宿主配置 先安装固定版本 @mantine/core 和 @mantine/hooks，在入口引入 @mantine/core/styles.css，并使用 MantineProvider。示例的 theme 和 variant 是 JGuang 编写的宿主参数，不是所有原生组件都接受的统一 API；通过 forceColorScheme 同步应用主题。源码面板中的原生实现仅供阅读，使用 npm 导出，不要单独复制内部实现。此批只覆盖 Core，不包括日期、图表和表单扩展包。上游详细说明保留英文，不宣称全文中文化。 ## 可运行用法 以下代码使用资源原生 API；不是把其他设计系统的同名组件替换进来。 ```tsx import { useState } from 'react'; import * as M from '@mantine/core'; import '@mantine/core/styles.css'; const fruit = ["Apple", "Banana", "Orange"]; function ComponentPreview({ variant = 'Default' }: { variant?: string }) { const [value, setValue] = useState(35); const [selection, setSelection] = useState(null); return {selection ?? "Choose a fruit / 选择水果"}; } export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) { return ; } ``` ## 可用状态与示例 默认 示例遵循 Mantine 原生 API。支持多状态的输入组件可将示例中的 variant 改为 Disabled、Invalid 或 Read only；这些只是示例标签，不是新增的组件属性。改造时保留组件要求的数据、受控值、store 和复合子组件结构。 ## Usage `ComboboxPopover` adds a dropdown with selectable options to any button. Unlike `Select` and `MultiSelect`, it does not render an input: pass your own target element to `ComboboxPopover.Target`. The target must be a single element or component that accepts a `ref`. ## Data format `ComboboxPopover` supports the same `data` format as [Select](/core/select) component: an array of strings, objects with `value` and `label`, or grouped items. ## Searchable Set `searchable` prop to add a search input to the dropdown: ## Controlled search value Use `searchValue` and `onSearchChange` props to control the search input value: ## Sort options Use `filter` prop with `searchable` to provide a custom filtering and sorting function: ## Limit options Use `limit` prop with `searchable` to limit the number of options displayed at a time: ## Multiple selection Set `multiple` prop to allow selecting multiple values. `value` type changes from `string | null` to `string[]`. ## Check icon ## Allow deselect By default, the selected option can be deselected by clicking it again. Set `allowDeselect={false}` to prevent this behavior. ## Nothing found message Set `nothingFoundMessage` prop to display a message when no options are available: ## Disabled options ## Groups ## Render option Use `renderOption` prop to customize option rendering: ## Large data sets By default, the dropdown is wrapped with `ScrollArea.Autosize`. Use `maxDropdownHeight` to control the maximum height: ## Control dropdown opened state Use `dropdownOpened`, `onDropdownOpen` and `onDropdownClose` props to control the dropdown state: ## Dropdown position ## Dropdown width By default, the dropdown width matches the target element. Use `comboboxProps` to set a custom width: ## Dropdown animation ## Form submission `ComboboxPopover` renders a hidden input with the selected value for native form submission. Use `name` prop to set the input name. For multiple selection, values are joined with a comma by default – use `hiddenInputValuesDivider` to change the separator. ## 源码参数参考 以下实现签名和类型从本地固定版本源码生成。保留可选属性、原生继承类型、联合分支和 never 限制；不会将其他设计系统的 API 混入。forwardRef 实现中的 ref 属于 React 引用，不是新增业务属性。此区域是原始类型参考，不是上游说明的全文翻译。 ```ts ComboboxPopover(_props) ``` ```ts export type ComboboxPopoverStylesNames = ComboboxLikeStylesNames | 'search'; export interface ComboboxPopoverProps< Multiple extends boolean = false, Value extends Primitive = string, > extends StylesApiProps { /** If set, multiple items can be selected at the same time */ multiple?: Multiple; /** Controlled component value */ value?: ComboboxPopoverValue; /** Uncontrolled component default value */ defaultValue?: ComboboxPopoverValue; /** Called when value changes */ onChange?: (value: ComboboxPopoverValue) => void; /** Data used to generate options */ data?: ComboboxData; /** Controlled dropdown opened state */ dropdownOpened?: boolean; /** Uncontrolled dropdown initial opened state */ defaultDropdownOpened?: boolean; /** Called when dropdown opens */ onDropdownOpen?: () => void; /** Called when dropdown closes */ onDropdownClose?: () => void; /** Called when option is submitted from dropdown with mouse click or Enter key */ onOptionSubmit?: (value: Value) => void; /** Props passed down to Combobox component */ comboboxProps?: ComboboxProps; /** Function based on which items are filtered and sorted */ filter?: OptionsFilter; /** Maximum number of options displayed at a time @default Infinity */ limit?: number; /** Determines whether the options should be wrapped with ScrollArea.AutoSize @default true */ withScrollArea?: boolean; /** max-height of the dropdown @default 220 */ maxDropdownHeight?: number | string; /** If set, the first option is selected when dropdown opens @default false */ selectFirstOptionOnDropdownOpen?: boolean; /** Displays check icon near the selected option label @default true */ withCheckIcon?: boolean; /** Aligns unchecked labels with the checked one @default false */ withAlignedLabels?: boolean; /** Position of the check icon relative to the option label @default 'left' */ checkIconPosition?: 'left' | 'right'; /** Message displayed when no options match the search query or when there is no data */ nothingFoundMessage?: React.ReactNode; /** Allows searching through options @default false */ searchable?: boolean; /** Controlled search value */ searchValue?: string; /** Default search value */ defaultSearchValue?: string; /** Called when search changes */ onSearchChange?: (value: string) => void; /** Allows deselecting the selected option by clicking it (only for single mode) @default true */ allowDeselect?: boolean; /** A function to render content of the option, replaces the default content of the option */ renderOption?: (item: ComboboxLikeRenderOptionInput) => React.ReactNode; /** Props passed down to the underlying ScrollArea component in the dropdown */ scrollAreaProps?: ScrollAreaProps; /** Props passed down to the hidden input */ hiddenInputProps?: Omit, 'value'>; /** Hidden input name for form submission */ name?: string; /** Hidden input form for form submission */ form?: string; /** Content of the component */ children?: React.ReactNode; /** Divider used to separate values in the hidden input value attribute @default ',' */ hiddenInputValuesDivider?: string; } export type ComboboxPopoverFactory = Factory<{ props: ComboboxPopoverProps; ref: HTMLDivElement; stylesNames: ComboboxPopoverStylesNames; signature: ( props: ComboboxPopoverProps ) => React.JSX.Element; staticComponents: { Target: typeof ComboboxPopoverTarget; }; }>; ``` ### 原生与外部类型 以下外部类型仍由 React 或资源自身依赖定义，没有手工展开为虚构属性。实际可用类型以安装版本的 TypeScript 检查为准。 ```ts Factory<{ props: ComboboxPopoverProps; ref: HTMLDivElement; stylesNames: ComboboxPopoverStylesNames; signature: ( props: ComboboxPopoverProps ) => React.JSX.Element; staticComponents: { Target: typeof ComboboxPopoverTarget; }; }> Primitive StylesApiProps Multiple ComboboxPopoverValue Value ComboboxData ComboboxProps OptionsFilter React.ReactNode ComboboxLikeRenderOptionInput ComboboxItem ScrollAreaProps Omit, 'value'> React.ComponentProps<'input'> HTMLDivElement ComboboxLikeStylesNames React.JSX.Element ``` --- JGuang 全部资源索引: https://jiguang132.com/llms.txt