企业官网建设流程全解析

• 前端
• CMS

导读

本文深入解析 wp-calypso 中驱动 Reader 搜索页的 Search Stream 模块：它是/discover/search页面背后的完整文章流（post stream），涵盖搜索输入框、查询建议、相关度/日期排序控件与结果列表四大部分。通过阅读本文，你将掌握该模块的 Props 契约、路由控制器如何组装streamKey、建议（suggestions）的生成与推荐埋点机制，以及搜索结果如何复用通用的reader/stream组件完成加载、占位与空状态渲染，从而能够快速定位并修改 Reader 搜索的任何环节。

模块概览：Search Stream 是什么

Search Stream 位于 client/reader/search-stream，其 README 的定义非常简洁：

The post stream behind the Reader's Search tab at/discover/search: the search input, the query suggestions, the relevance/date sort control, and the results.

也就是说，Search Stream 并非单独负责“搜索请求”，而是整条搜索页文章流——从用户输入关键词、看到建议、切换排序方式，到最终渲染搜索结果列表，全部由该模块承接。它不是一个孤立的页面，而是挂在 Reader「发现（Discover）」体系下的一个 Tab，路由常量为SEARCH_TAB = 'search'（见 client/reader/discover/helper/index.ts）。

从目录结构看，该模块由 8 个文件组成，职责划分清晰：

Props 契约：Search Stream 对外接口

README 明确给出了 Search Stream 的 Props：

• query：搜索词（search term）
• sort：relevance（默认）或date
• 其余 Props 继承自reader/stream

在 client/reader/search-stream/index.jsx 中，组件类仅声明了两个自有 PropTypes：

static propTypes = { query: PropTypes.string, streamKey: PropTypes.string, };

其余属性（如sort、autoFocusInput、trendingTags、trackScrollPage等）由路由控制器传入并透传给底层的Stream。sort虽未在 propTypes 中声明，但实际由控制器以 URL 查询参数?sort=提供，默认值为relevance，可选值为relevance与date。

路由入口：search 控制器如何组装页面

Search Stream 是懒加载（异步）挂载到路由上的。在 client/reader/discover/search-controller.jsx 中，通过 webpack 代码分割按需加载：

const loadSearchStream = () => import( /* webpackChunkName: "async-load-calypso-reader-search-stream" */ 'calypso/reader/search-stream' );

路由在 client/reader/discover/routes/index.ts 中注册为/${ DISCOVER_PREFIX }/${ SEARCH_TAB }，即/discover/search。

控制器search函数（search-controller.jsx）完成以下关键工作：

1. 解析查询参数：const { sort = 'relevance', q: searchSlug } = context.query;——默认排序为relevance，q为搜索词。
2. 构造 streamKey：

const streamKey = searchSlug ? 'search:' + JSON.stringify( { sort, q: searchSlug } ) : 'custom_recs_sites_with_images';

有搜索词时，streamKey 编码了排序方式与关键词（如search:{"sort":"date","q":"cats"}），保证不同搜索词对应独立流缓存；无搜索词时，回退到推荐流custom_recs_sites_with_images，此时页面展示的是推荐内容而非空页。 3.埋点区分：有搜索词记录calypso_reader_search_performed（携带query与sort），无搜索词记录calypso_reader_search_loaded。 4.输入聚焦策略：const autoFocusInput = ! searchSlug || context.query.focus === '1';——空搜索页自动聚焦输入框，带focus=1时同样聚焦。 5.登录态分叉：fetchTrendingTagsIfLoggedOut中间件在未登录时预先请求 trending tags，用于给访客生成搜索建议（详见下文建议机制）。 6. 通过AsyncLoad渲染 Search Stream，并传入streamKey、query、sort、autoFocusInput、trendingTags、trackScrollPage、onUpdatesShown等 Props。

顶层容器：输入、排序与建议的协同

client/reader/search-stream/index.jsx 的渲染结构分为“固定区（fixed-area）”和“结果区（post-results）”两部分：

<DocumentHead title={ documentTitle } /> <DiscoverHeaderAndNavigation selectedTab={ SEARCH_TAB } /> <div className="search-stream__fixed-area" ref={ this.handleFixedAreaMounted }> <CompactCard className="search-stream__input-card"> <SearchInput onSearch={ this.updateQuery } ... /> </CompactCard> { query && ( <div className={ toggleGroupControlClasses }>...排序控件...</div> ) } { ! query && ( <BlankSuggestions suggestions={ suggestionList } ... /> ) } </div> <div className="search-stream__post-results"> <PostResults { ...this.props } fixedHeaderHeight={ fixedAreaHeight } /> </div>

这里有一个重要的布局技巧：固定区（输入框 + 排序 + 建议）通过handleFixedAreaMounted记录自身高度fixedAreaHeight，并传给结果区，让Stream能正确计算首屏滚动位置，避免固定头部遮挡首条内容。

搜索输入：防抖、裁剪与 URL 同步

输入框使用calypso/components/search的SearchInput：

<SearchInput onSearch={ this.updateQuery } onSearchClose={ this.scrollToTop } autoFocus={ this.props.autoFocusInput } delaySearch delayTimeout={ 500 } placeholder={ searchPlaceholderText } initialValue={ query || '' } value={ query || '' } />

• delaySearch+delayTimeout={ 500 }：输入防抖 500ms，用户停止输入半秒后才触发搜索，避免每敲一个字符就发起请求。
• placeholder来自 utils.js 的getSearchPlaceholderText()，即 i18n 翻译后的“Search Reader”。
• initialValue与value均绑定 URL 中的query，保证刷新/回退后输入框内容与页面状态一致。

输入变化由updateQuery处理（index.jsx）：

updateQuery = ( newValue ) => { this.scrollToTop(); const trimmedValue = ( newValue ?? '' ).trim().substring( 0, 1024 ); if ( ( trimmedValue !== '' && trimmedValue.length > 1 && trimmedValue !== this.props.query ) || newValue === '' ) { updateQueryArg( { q: trimmedValue } ); } };

要点：

• 先滚动回页面顶部（window.scrollTo( 0, 0 )），避免结果更新时用户停留在旧位置。
• 去除首尾空白，且截断到 1024 字符，防止超长恶意输入。
• 长度 > 1 才触发搜索（单字符不搜），输入为空时直接清空 URL 参数。
• URL 同步使用page.replace( addQueryArgs( params, window.location.pathname + window.location.search ) )，即替换当前历史记录而非压栈，避免用户搜索多个词后浏览器后退行为异常。

排序控件：Relevance / Date

仅当存在query时才显示排序控件，使用 WordPress 组件的实验性 ToggleGroupControl：

<ToggleGroupControl hideLabelFromVision isBlock value={ sortOrder } onChange={ this.onChangeSortPicker } > <ToggleGroupControlOption label={ TEXT_RELEVANCE_SORT } value="relevance" /> <ToggleGroupControlOption label={ TEXT_DATE_SORT } value="date" /> </ToggleGroupControl>

切换排序时（index.jsx）：

• 记录统计动作：search_page_clicked_date_sort/search_page_clicked_relevance_sort；
• 发送 Tracks 事件calypso_reader_clicked_search_sort，携带query与sort；
• 通过updateQueryArg( { sort } )更新 URL 的sort参数，streamKey随之改变，Stream 会按新排序重新拉取。

排序控件还有一个响应式细节：容器宽度超过 660px（WIDE_DISPLAY_CUTOFF）时添加is-wide类（index.jsx），以便在宽屏下平铺两个选项。这个宽度值由withDimensions高阶组件测量后通过props.width传入。

空查询时的建议区

当query为空时，不显示排序控件，而是展示BlankSuggestions（来自calypso/reader/components/reader-blank-suggestions），其建议列表由当前查询无关的“通用建议”构成（见下文建议机制），同时提供跳转到 Tags 页的链接（trackTagsPageLinkClick埋点clicked_reader_search_tags_page_link）。

建议机制：从已关注标签到推荐词

建议（suggestions）由SuggestionProvider这个高阶组件注入（suggestion-provider.jsx）。它在index.jsx的导出链中位于最外层之外：

export default connect( null, { recordReaderTracksEvent, } )( localize( SuggestionProvider( wrapWithMain( withDimensions( SearchStream ) ) ) ) );

SuggestionProvider( Element, count = 3 )默认提供3 条建议，其数据来源分三层：

1. 已关注标签（登录用户）：通过useFollowedTags()获取用户订阅的标签。suggestionsFromTags要求标签总数大于所需数量才生成建议（否则返回空数组），随机打乱（shuffle）后取前count个，标签名中的-会被替换为空格展示，且带ui_algo: 'read:search-suggestions:tags/1'。
2. Trending tags（未登录访客）：未登录用户没有标签订阅，控制器会通过fetchTrendingTagsIfLoggedOut预取 trending tags，trendingTagsToTags将其映射为{ displayName, slug }后走同一套生成逻辑。
3. 语言预设词库（Picks）：当标签不足时，回退到 suggestions.js 中按语言维护的词库，按当前 locale 取词（getLocaleSlug().split('-')[0]），随机取count条，ui_algo: 'read:search-suggestions:picks/1'。目前内置 en（70+ 词）、es、fr、de 四套词库，例如英文词库涵盖 Anime、Art、Cocktails、Elasticsearch、Fitness、WordPress、Writing 等热门话题。

关键设计：SuggestionsClass将建议结果记忆化（memoize）——一旦生成非空建议就不再重新计算，避免每次渲染都随机换一批；组件卸载时重置记忆，保证下次进入搜索页能刷新建议。

每条建议都携带 railcar（推荐系统追踪单元）：

function suggestionWithRailcar( text, ui_algo, position ) { return { text: text, railcar: { railcar: createRandomId() + '-' + position, ui_algo: ui_algo, ui_position: position, rec_result: text, }, }; }

createRandomId()优先使用window.crypto.getRandomValues生成 9 字节随机数并 base64 编码（规避填充字符），不支持 crypto 时降级为Math.random方案。

单条建议链接由 suggestion.jsx 渲染：构造{ isSuggestion: 1, q: suggestion, sort }查询参数，并用retrieveLocaleFromPathLocaleInFront探测路径前缀语言，生成形如/discover/search?isSuggestion=1&q=WordPress&sort=date的链接（有语言前缀时如/es/discover/search?...）。该组件还负责两类埋点：挂载时记录calypso_traintracks_render（railcar 曝光），点击时记录calypso_reader_search_suggestion_click与search_suggestion_click（railcar 交互）。

结果流：复用通用 Stream 组件

post-results.jsx 是搜索结果流的薄封装，核心是透传 Props 给通用 client/reader/stream 的Stream：

<Stream { ...this.props } listName={ translate( 'Search' ) } emptyContent={ emptyContent } showFollowInHeader placeholderFactory={ this.placeholderFactory } transformStreamItems={ transformStreamItems } isMain={ false } fixedHeaderHeight={ this.props.fixedHeaderHeight } >

空查询 = 推荐列表

transformStreamItems是关键的“无查询”分支：

const transformStreamItems = ! query || query === '' ? ( postKey ) => ( { ...postKey, isRecommendation: true } ) : defaultTransform;

没有搜索词时，所有流条目被打上isRecommendation: true标记，配合placeholderFactory使用RelatedPostCard（相关文章卡片）渲染占位骨架——这与控制器中 streamKey 回退到custom_recs_sites_with_images的行为一致：空搜索页本质上是“带搜索框的推荐流”。有查询时占位符使用通用的PostPlaceholder。

空状态：No results

当搜索无结果时，渲染 empty.jsx 的空状态：标题“No results”，正文为No posts found for {{query}} for your language.（强调当前语言限制），并提供一个返回「Following」流的按钮（Back to Following，点击埋点calypso_reader_following_on_empty_search_stream_clicked）。该组件还包裹了withReaderPerformanceTrackerStop，在空状态出现时停止性能追踪计时。

埋点与性能追踪体系

Search Stream 贯穿三层数据追踪：

ReaderPerformanceTrackerStop则确保搜索结果渲染完成后正确停止性能埋点，保证阅读器性能数据的准确性。

样式与布局要点

模块样式位于 client/reader/search-stream/style.scss，由index.jsx顶部import './style.scss'引入。从组件类名可以看出布局体系：search-stream__fixed-area（固定输入区）、search-stream__input-card（输入卡片）、search-stream__sort-picker（排序控件，is-wide变体）、search-stream__post-results（结果区）与search-stream__recommendation-list-item（推荐列表项）。整体被ReaderMain（wrapWithMain）包裹，外层类名search-stream，保证与阅读器其余页面的视觉风格一致。

总结

Search Stream 是 wp-calypso Reader 中“小而全”的模块典范：它通过query/sort两个核心 Props 与路由控制器解耦，将搜索词、排序方式编码进streamKey实现流级缓存与按需刷新；在空查询时无缝切换为推荐流并提供三类来源的搜索建议；排序、建议、空状态全部配套 Tracks/railcar 埋点；最终结果渲染完全复用通用Stream组件。无论你要修改搜索输入交互、调整建议生成逻辑、新增排序方式，还是排查搜索页埋点，从 client/reader/search-stream 出发、沿 search-controller.jsx →index.jsx→post-results.jsx→Stream这条链路即可快速定位。

• 前端
• CMS