多选器 · MultiSelector

从选项中选择多个值，展示选中项并允许移除。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 多选器 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 多选器 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 多选器 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 多选器 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 多选器 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 多选器 · 搜索 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 多选器 · 交互示例 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Multi Selector

A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.

使用建议

• Use for a moderate, finite set of options where multiple choices are needed.
• Enable search filtering when the list exceeds ~15 options.
• Use renderOption for custom option rows; the checkbox affordance remains owned by MultiSelector.
• Enable select-all when most users will want all or nearly all options selected.
• 避免：Use for single-value selection; use Selector instead.
• 避免：Show more than ~20 options without enabling search.
• 避免：Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-multi-selector",
      "visualProps": [
        "variant",
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    },
    {
      "className": "astryx-multi-selector-empty-state"
    },
    {
      "className": "astryx-multi-selector-search"
    },
    {
      "className": "astryx-multi-selector-section-heading"
    },
    {
      "className": "astryx-multi-selector-indicator-icon",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-multi-selector-option",
      "visualProps": [
        "size"
      ],
      "states": [
        "select-all",
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-multi-selector-popup"
    }
  ]
}

Multi Selector

带复选框的多选下拉框，用于从列表中选择多项。

组件结构

• Field: Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
• Trigger: Painted control that displays the current selection or placeholder and opens the selection surface when editable.
• Icon-rendered start icon: Optional leading semantic icon or icon component rendered through Icon.
• Caller-rendered start content: Optional arbitrary React content rendered directly at the start of the trigger.
• Trigger clear button: Shared clear action that removes every selected value when hasClear is enabled.
• Status icon: Status glyph shown in place of the disclosure indicator for attached or tooltip status.
• Indicator icon: Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.
• Search row: Panel header with a borderless search input and optional clear action.
• Search icon: Leading magnifier rendered through Icon inside the search row.
• Search clear button: Shared clear action shown in the search row while a query is present.
• Option row: Selectable row for an option or the optional select-all choice.
• Option checkbox indicator: CheckboxInput indicator that presents each row’s selected, unselected, or indeterminate state.
• Option divider: Divider supplied in the public options data to separate adjacent option groups.
• Section heading: Visible heading for a labeled group of option rows.
• Empty state: Message shown when the shared panel content has no options or no search matches.
• Pointer popup: Anchored painted surface that hosts the shared panel content for popover presentation.
• Touch sheet heading: Heading above the shared panel content in bottom-sheet presentation.
• Touch sheet: BottomSheet surface that hosts the same panel content for bottom-sheet presentation.