定价

SearchBox

Figma 源代码

提供打开搜索浮层的入口，整块区域均可点击，可组合快捷键提示，适合全局搜索。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于打开全局搜索浮层的可点击入口，并非直接编辑查询的输入框。工具栏或列表直接输入查询用 SearchInput。

  • 这是可点击搜索入口；bind:open 同步浮层状态，value 用于展示当前查询。

  • 通过 children 组合浮层或快捷键提示；需要直接编辑查询时使用 SearchInput。

  • 默认占位和清除名称随 LocaleProvider 切换；显式 placeholder（含空字符串）与 aria-label 优先，查询值保持原样。

导入

import { SearchBox } from '@snowui-design-system/components';

用法

描边

清除

禁用状态

收起

API 参考

属性 类型 默认值 示例 描述
parts ComponentPartsOf<{ Button: typeof Button }> — parts={{ Button: { size: "md" } }} 配置内部生成的清除 Button；显式子内容不消费该默认配置。
variant "gray" | "outline" "gray" variant="gray" 搜索框样式
gap number — gap={42} 继承 Frame 的间距 token 索引；省略时保留原首选间距，显式值覆盖首选间距；有效图文间距至少为 4 CSS px，显式零、根字号或间距缩放不压低下限。
value string | number — bind:value={query} 当前搜索文本或展示值
placeholder string — placeholder="Search…" 占位文本；未传时使用 searchBox.placeholder，zh-CN 为“搜索”、en-US 为“Search”；显式空字符串保留
open boolean false bind:open={open} 浮层打开状态，支持 bind:open
disabled boolean false disabled 禁用触发器
readonly boolean false readonly 只读触发器，不响应打开
showSearchIcon boolean true showSearchIcon 是否渲染默认搜索图标
collapseBelow number — collapseBelow={42} 当组件自身宽度小于或等于该 px 阈值时，仅保留 leading 搜索图标；未传时不启用
clearable boolean true clearable 有值时是否显示清除按钮
children Snippet — <SearchBox><Kbd as="trailing" variant="solid" style="background-color: var(--surface-3);">⌘K</Kbd></SearchBox> 外置 leading/trailing，如 Kbd
onOpenChange (open: boolean) => void — onOpenChange={(next) => open = next} 打开状态变化回调
onClear () => void — onClear={() => message = "Search cleared"} 清除回调
onclick (event: MouseEvent) => void — onclick={(event) => console.log(event.type)} 入口点击后调用，参数为原始 MouseEvent；非 disabled、非 readonly 时组件先打开搜索层，回调不能取消已执行的打开。
onkeydown (event: KeyboardEvent) => void — onkeydown={(event) => console.log(event.key)} 处理 Escape 关闭及 Enter/Space 打开后调用，接收原始 KeyboardEvent；不能撤销已经发生的状态变化。