高级搜索 · PowerSearch

使用组合条件构建更丰富的搜索界面。

安装与前置条件

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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Power Search

PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.

属性	类型	默认值	说明
config *	PowerSearchConfig		定义可用字段、运算符及其值类型的配置。
filters *	ReadonlyArray<PowerSearchFilter>		当前活跃的过滤器。
onChange *	(filters: ReadonlyArray<PowerSearchFilter>, changeType: 'add' \| 'edit' \| 'remove', index: number) => void		当过滤器变更时调用。changeType 为 'add'、'edit' 或 'remove'。index 为受影响的过滤器位置。
label	string	'Search'	搜索输入框的无障碍标签。
isLabelHidden	boolean	true	视觉上隐藏标签，同时保持无障碍性。
placeholder	string	'Search...'	未选择过滤器时显示的占位文本。
hasAutoFocus	boolean	false	挂载时自动聚焦输入框。
hasClear	boolean	true	显示清除全部按钮以移除所有过滤器。
isReadOnly	boolean	false	阻止添加、编辑或移除过滤器。
isDisabled	boolean	false	禁用整个组件。
disabledMessage	string		Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
status	{type: 'warning' \| 'error' \| 'success', message?: string}		带有类型和可选消息的验证状态对象。
startIcon	ReactNode \| IconType		在输入框开头（筛选 token 之前）显示的图标，转发给内部的 Tokenizer。接受语义图标名称、SVG 图标组件或直接传入 ReactNode。
statusVariant	'attached' \| 'detached'	'attached'	状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。
maxTokenLength	number	40	令牌中过滤器值显示的最大字符长度。
maxOperatorMenuItems	number	10	字符串和实体值预输入菜单中显示的最大建议数。不影响主字段搜索菜单或枚举值菜单。
maxSearchResults	number	10	非空查询的最大排名结果数。不影响字段值编辑器。使用空查询浏览时最多显示 1,000 个字段。
menuWidth	number		主字段/搜索菜单的像素宽度。不影响字段值编辑器。
popoverSaveButtonLabel	string	'Apply'	编辑弹出窗口中保存按钮的标签。
timezoneID	string		用于日期格式化的时区 ID（例如 "America/New_York"）。
handleRef	Ref<PowerSearchHandle>		提供 focusTypeahead() 和 blurTypeahead() 方法的命令式句柄。
endContent	ReactNode		显示在输入行末尾的内容。适用于操作按钮或其他控件。
resultCount	number \| string		匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。数量变化会通过 polite 实时区域向屏幕阅读器播报。
size	'sm' \| 'md' \| 'lg'	'md'	搜索输入框和标记的尺寸。
menuWidth	number		主字段/搜索菜单的像素宽度。不影响字段值编辑器。
maxOperatorMenuItems	number		字符串和实体值预输入菜单中显示的最大建议数。不影响主字段搜索菜单或枚举值菜单。
tokenOverflowBehavior	'none' \| 'unfocusedInline' \| 'unfocusedLayer'	'none'	Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.
onFocus	(e: React.FocusEvent) => void		Fires when focus enters the search input.
onBlur	(e: React.FocusEvent) => void		Fires when focus leaves the search input.
xstyle	StyleXStyles		用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。

使用建议

Define clear, descriptive field names and aliases so users can quickly find the filter they need.
Provide a result count to give users feedback on how their filters affect the data set.
避免：Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.
避免：Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-power-search"
    }
  ]
}