【免费下载链接】wp-calypso
The JavaScript and API powered WordPress.com
导读
SearchBoxHeader 是 wp-calypso(WordPress.com 的 JavaScript 与 API 驱动前端)中插件市场(Plugins Marketplace)页面顶部的核心组件,它同时负责渲染市场页面的主标题、一个可交互的插件搜索框,以及一组循环轮换的推荐搜索词。本文以 client/my-sites/plugins/search-box-header/README.md 为骨架,结合其源码实现 index.jsx、样式文件 style.scss 以及上游调用方 plugins-browser/index.jsx,完整讲解该组件的 Props 契约、交互逻辑、吸顶行为、推荐搜索动画原理及其在插件浏览器中的实际装配方式,帮助你理解并复用这一组件。
一、组件定位:插件市场的"门面"
从 README 的定义来看,这个组件承担了三件事:
This component is used to render the heading of the plugin marketplace, a search bar and a list of recommended searches.
即:渲染插件市场的标题(heading)、一个搜索栏(search bar)、以及一组推荐搜索(recommended searches)。在 plugins-browser/index.jsx 中,它被装配在 FullWidthSection(灰色通栏)内,作为未登录(logged-out)视图下插件浏览页的头部;而登录视图则使用同系列的 SearchCategories 组件。二者共享相同的搜索交互与推荐词机制,SearchBoxHeader 偏向"市场门户"式的展示型头部。
二、如何使用:最小示例与完整装配
2.1 README 给出的最小用法
README 提供了一个直接可用的示例:
import SearchBoxHeader from 'calypso/my-sites/plugins/search-box-header';
<SearchBoxHeader
searchTerm={ search }
siteSlug={ siteSlug }
title={ translate( 'Plugins you need to get your projects done' ) }
searchTerms={ [ 'shipping', 'seo', 'portfolio', 'chat', 'mailchimp' ] }
/>;
其中 translate 来自 i18n-calypso,用于国际化标题文案;search 与 siteSlug 分别来自路由查询参数与当前选中站点。
2.2 生产环境中的完整装配(源码级)
在 plugins-browser/index.jsx 中,真实装配远比最小示例复杂,它展示了全部 Props 的协作方式:
<FullWidthSection
className="plugins-browser__search-header full-width-section--gray"
enabled={ isMarketplaceRedesignEnabled }
>
<SearchBoxHeader
searchRef={ searchRef }
categoriesRef={ categoriesRef }
stickySearchBoxRef={ searchHeaderRef }
isSticky={ isAboveElement }
searchTerm={ search }
isSearching={ isFetchingPluginsBySearchTerm }
title={
isMarketplaceRedesignEnabled
? __( 'Plug into possibility' )
: __( 'Flex your site’s features with plugins' )
}
subtitle={
isMarketplaceRedesignEnabled
? __(
'Add new features or connect your favorite tools with thousands of plugins — available on all paid WordPress.com plans.'
)
: __(
'Add new functionality and integrations to your site with thousands of plugins.'
)
}
searchTerms={ searchTerms }
renderTitleInH1={ ! category }
/>
</FullWidthSection>
注意几点生产细节:
searchTerms在浏览器入口中定义为一组固定的推荐词:[ 'woocommerce', 'seo', 'file manager', 'jetpack', 'ecommerce', 'form' ](见 plugins-browser/index.jsx),源码注释特别提醒:如果新增更长的搜索词,务必保证搜索输入框宽度足够容纳;- 标题与副标题会依据
isMarketplaceRedesignEnabled(市场改版开关,由useIsMarketplaceRedesignEnabledhook 提供)切换两套文案; renderTitleInH1在无分类浏览时渲染为<h1>,保证页面唯一主标题的 SEO/语义结构,进入分类页后则退化为普通<div>,避免 H1 重复。
三、Props 契约:文档定义与源码实际扩展
README 只列出了 4 个 Props,但源码实现(index.jsx)实际解构了 8 个。下表将文档契约与源码扩展合并呈现:
| Props | 类型 | 必选 | 说明 |
|---|---|---|---|
searchTerm | string | 是 | 当前用于搜索插件的关键词,作为受控输入框的 value |
siteSlug | string | 可选 | 当前选中站点的 URL 别名,拼接进搜索跳转路径 |
title | string | 是 | 渲染在标题位置(<h1> 或 <div>)的文案 |
searchTerms | string[] | 是 | 推荐搜索词数组,用于轮换展示与占位符提示 |
subtitle | string | 可选 | 标题下方的副标题段落,README 未提及但生产环境广泛使用 |
isSticky | boolean | 可选 | 是否启用吸顶(fixed-top)样式,滚动时固定搜索框 |
stickySearchBoxRef | Ref | 可选 | 吸顶锚点引用,用于外部判断滚动位置 |
categoriesRef | Ref | 可选 | 分类区 DOM 引用,搜索后用于精确滚动定位 |
renderTitleInH1 | boolean | 可选 | 为 true 时标题渲染为 <h1>,否则为 <div> |
其中 siteSlug 在文档中描述为 "A string representing the url of the current selected site, it can be optional",源码中通过 selectedSite?.slug 从 getSelectedSite selector 实时获取(见 index.jsx),因此调用方可以不传而由 Redux 自动注入。
四、核心交互逻辑:从输入到 URL 更新的调用链
搜索框使用了 @wordpress/components 的 SearchControl,并通过 styled(Emotion)定制字号与占位符颜色(见 index.jsx)。其交互遵循"输入不实时搜索,回车/清空才更新 URL"的设计:
4.1 清空搜索(onChange)
仅在输入被清空时触发(源码注释 "Only update URL on clear"):
onChange={ ( newValue ) => {
if ( newValue === '' ) {
recordSearchEvent( 'SearchCleared' );
page.show( localizePath( `/plugins/${ selectedSite?.slug || '' }` ) );
setQueryArgs( {} );
}
} }
清空后通过 page.show(@automattic/calypso-router)跳回 /plugins 根路径并清空查询参数,同时上报 Google Analytics 事件 SearchCleared(recordGoogleEvent,事件类别固定为 'PluginsBrowser')。
4.2 提交搜索(onKeyDown + Enter)
onKeyDown={ ( event ) => {
if ( event.key === 'Enter' && event.target ) {
event.preventDefault();
const value = event.target.value;
recordSearchEvent( 'SearchInitiated' );
page.show( localizePath( `/plugins/${ selectedSite?.slug || '' }` ) );
setQueryArgs( value ? { s: value } : {} );
if ( value && categoriesRef?.current ) {
scrollTo( {
x: 0,
y:
categoriesRef.current.getBoundingClientRect().y -
categoriesRef.current.getBoundingClientRect().height,
duration: 300,
} );
}
}
} }
回车后的调用链为:
recordSearchEvent( 'SearchInitiated' )—— 打点记录搜索行为;page.show( localizePath(/plugins/${ siteSlug }) )—— 先导航到插件页根路径;setQueryArgs( { s: value } )—— 再把关键词写入 URL 查询参数s,插件搜索结果页通过该参数驱动;- 若有关键词且存在
categoriesRef,调用scrollTo(来自calypso/lib/scroll-to)以 300ms 动画滚动到分类区上方(滚动距离为分类区 y 坐标减去其自身高度,即"停在分类区顶部但不露出分类内容")。
同一交互逻辑在登录视图的 SearchCategories/index.tsx 中通过 updateSearch 回调以几乎相同的方式实现,并额外通过命令式 handle 暴露 blur/focus/clear/setKeyword 四个方法给外部 searchRef 调用(见 search-categories/index.tsx),可见这是插件搜索体系的统一约定。
4.3 响应式
组件通过 useViewportMatch( 'large' )(@wordpress/compose)判断是否桌面宽度,非桌面时给搜索框追加 components-search-control--mobile 类(index.jsx 与 search-categories/index.tsx),配合样式切换移动端布局。
五、推荐搜索轮换:useTermsSuggestions 的"打字机"动画
searchTerms 数组最亮眼的效果是输入框占位符会每隔几秒自动轮换一个推荐词,且带逐字敲出的打字动画:
placeholder={ translate( 'Try searching "%(searchTermSuggestion)s"', {
args: { searchTermSuggestion: useTermsSuggestions( searchTerms ) || 'ecommerce' },
textOnly: true,
} ) }
其底层实现是 use-terms-suggestions/index.js 中的 useTermsSuggestions hook:
- 轮换节奏:
INTERVAL_BETWEEN_TERMS = 5000,即每 5 秒切换到下一个推荐词; - 打字动画:
INTERVAL_ANIMATION = 50,每 50ms 追加一个字符,直到完整词显示; - 滚动暂停:监听全局
scroll事件,一旦用户向下滚动即clearInterval暂停动画,滚回window.scrollY < 100时重新恢复(见 use-terms-suggestions/index.js),避免滚动时干扰视觉; - 循环机制:用模块级
previousIndex配合取模termSuggestions.length实现无限循环;卸载时清理 interval 与 scroll 监听。
若数组为空,则回退到默认词 'ecommerce'(|| 'ecommerce')。
六、样式体系:居中布局、吸顶与登录态差异
样式全部集中在 style.scss,包含三块:
6.1 基础布局
- 根容器
display: flex; flex-direction: column; align-items: center,移动端(≤660px)加 16px 左右内边距; - 搜索区
margin-top: 24px,内部 SearchControl 输入底座高 55px,搜索框最大宽 504px; - 标题使用
@extend .wp-brand-font品牌字体,字号$font-title-large,颜色var(--studio-blue-90),居中 40px 行高。
6.2 吸顶模式(.fixed-top)
当 isSticky 为 true 时(插件浏览器中由 useScrollAboveElement 的返回值 isAboveElement 驱动,见 plugins-browser/index.jsx),在 ≥783px 宽度下搜索区变为 position: fixed,top: var(--masterbar-height)、z-index: 20,白底加底边框;同时针对 2026 新版导航(x-nav--2026-redesign)和侧边栏布局(.layout__secondary ~ .layout__primary)分别做了偏移与宽度补偿,代码注释解释了这套 "baton-pass" 吸顶衔接机制(style.scss)。
6.3 未登录视图(main.is-logged-out)
在未登录状态下标题左对齐、字号放大至 rem(44px)(全宽内容区下甚至到 rem(70px)),搜索框改为左对齐并带多层柔和阴影,整体呈现"市场落地页"风格(style.scss)。
注意:README 提到的 "a list of recommended searches"(推荐搜索列表)在当前版本的 index.jsx 渲染中已由占位符轮换(placeholder)机制替代,列表样式类(
search-box-header__recommended-searches*)仍保留在 style.scss 中(含逗号分隔符、hover 下划线、选中态等规则),可作为历史形态参考。
七、源码结构速览
| 文件 | 职责 |
|---|---|
| search-box-header/README.md | 组件文档:用途、用法示例、Props 说明 |
| search-box-header/index.jsx | 组件主实现:渲染、搜索交互、事件打点 |
| search-box-header/style.scss | 全部样式:居中布局、吸顶、登录/未登录差异化 |
| plugins-browser/index.jsx | 主要调用方:未登录视图下的完整装配与状态驱动 |
| search-categories/index.tsx | 登录视图的同类搜索头,共享搜索交互约定 |
| use-terms-suggestions/index.js | 推荐词轮换 + 打字动画 hook |
八、复用建议与注意事项
- 受控组件:
searchTerm必须由外部(通常是路由查询参数s)驱动,组件自身不维护输入状态,只在回车/清空时通过 URL 同步; - 国际化:
title、subtitle与占位符文案都应经过translate/__处理,占位符中嵌入推荐词时使用textOnly: true避免多语言嵌套插值问题; - 可访问性:
renderTitleInH1建议在页面根级标题场景下开启,保证 H1 唯一; - 性能:若复用
useTermsSuggestions,注意其基于模块级previousIndex的全局轮换游标,多个实例会共享轮换进度,且列表变化会重建 interval——高频变更的数组需谨慎; - 样式覆盖:组件样式依赖
--studio-*与--color-link等 CSS 变量及@automattic/typography变量,脱离 calypso 样式体系使用前需确保变量定义完整。
至此,你可以直接基于 README 示例快速接入该组件,也可深入 index.jsx 与 plugins-browser/index.jsx 理解它在插件市场中的完整运行链路。
【免费下载链接】wp-calypso
The JavaScript and API powered WordPress.com
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



