SearchPopup 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

可组合的搜索面板，内置 SearchInput 和可选数据结果，支持无分组、分组标题与显式复杂内容。运行时依赖 @snowui-design-system/components 和 Components；不包含搜索算法、最近浏览、热度或业务路由规则。

使用选择

用于复用搜索输入与结果的标准布局。SearchBox 是打开入口；SearchPopup 是面板，默认静态呈现。设置 backdrop 可启用共享模态遮罩；无遮罩时，锚定触发器使用继承的 Popover 模版或内嵌模式。

• items 生成文字或链接结果，group 可选；showGroupTitles 控制分组标题。

• children 替换全部内置结果；显式标题用 Text as="group-title"，项用 MenuItem as="item"。

• search=false 后可显式提供 SearchInput as="content"；该输入直接配置，不消费 parts。

快速开始

<script lang="ts">    import { SearchPopup } from '@snowui-design-system/components';</script><SearchPopup items={[{ value: 'button', label: 'Button', href: '/components/button', group: 'Recommended components' }]} />

API

兼容属性继承 Popover；默认 size=md、closeOn=manual，标准静态搜索面板宽度名义 480px。显式使用浮层时设置 template/id 或 as="popover"，并按需要设置 closeOn。外层 class 和 style 透传真实 Popover 宿主。模态模式复用 Dialog，不新增模态、定位、滚动和动效系统；class/style 与 parts 仍作用于内部搜索面板，模态外壳使用面板默认宽度。

使用边界与详细说明

默认内置模式生成 SearchInput、Text、MenuItem。parts 不改写显式 children。Input 可通过 parts.SearchInput 配置 placeholder、ARIA 与 autofocus；内置文字沿用 SearchInput 的 locale 默认值，本组件不新增固定业务文案。默认结果 href 使用原生链接；默认数据结果必须提供 href；命令操作等非导航内容使用 children 显式组合具备键盘语义的 Button。

按 Figma SearchPopup 的垂直间距：默认 md 面板上下 padding 为 16px，搜索区上 4px、下 16px；结果区域距输入分隔线 12px。结果按单列排列，标题与 item、相邻 item 之间为 gap-1（4px）；后续分组标题增加 gap-2（8px）上间距，与行间距合计 12px。首个标题不额外叠加 margin；无标题时首项同样距分隔线 12px。标题垂直 padding 为 0、水平 8px，item 上下 padding 为 8px。公开角色 group-title 是多项角色，允许 Text 或原生 data-as；仅控制标题的颜色与间距，不改写业务内容。as=item 保留 MenuItem 自身语义，不创建 Listbox 选择 owner。

标题和分组可省略；显式复杂内容可以组合 Avatar、Icon、MenuItem。设置 backdrop 时由内部 Dialog 管理共享遮罩、渐入渐出、反向接续、减少动效、焦点圈定与恢复、背景滚动锁定。closeOnEscape 控制 Escape 关闭，closeOnOutside 控制遮罩关闭。使用 bind:open 控制显隐；template/id 模式使用 data-dialog-target、data-dialog-close 或 showDialog/hideDialog；as="popover" 在此模式下使用 Dialog 内联触发。不要再包外层 Dialog，避免双重遮罩。模态时内部 Popover 不自行关闭；closeOn/closeOnSelect 仅用于无遮罩模式。默认链接结果会关闭 Dialog；显式结果可使用 data-dialog-close。静态面板 SSR 不访问浏览器全局，动效及 reduced-motion 继承 Popover。不开启定位模式时不新增定位监听器。