企业官网建设流程全解析

• CMS
• 后端
• 前端

导读

本文以 October CMS 仓库中 search-input 控件文档 为主体，系统讲解后台搜索输入框的完整技术方案：包括带清空按钮、加载状态与搜索图标的 HTML 结构、data-*属性约定、前端控件的生命周期与交互逻辑，以及与之配套的后端SearchWidget 与会话存储机制。读完本文，你将能够在 October CMS 的列表页、设置页等后台场景中，独立实现一个可实时触发 AJAX 请求、支持一键清空并自动刷新数据的搜索框。

一、控件概览：一个完整的搜索输入框由什么组成

在 October CMS 的 Toolbox 前端框架中，搜索输入（Search Input）是一个开箱即用的交互控件。按照 官方控件文档 的定义，它需要同时具备三项能力：

• 清空输入（clear input）：输入有内容时显示清空按钮，点击后一键清空；
• 加载状态（loading state）：发起 AJAX 请求时显示加载指示器；
• 搜索图标（search icon）：输入框内渲染一个搜索图标（通过storm-icon-pseudo伪元素类实现）。

该控件在仓库中的完整实现位于 modules/system/assets/toolbox/controls/search-input/ 目录，包含三个文件：

从 toolbox.js 的源码可以看到，该控件在 Toolbox 中通过registerControl('search-input', SearchInputControl)完成注册，任何页面只要引入 Toolbox 并在元素上声明对应的data-control属性即可自动激活。

需要特别指出一个值得注意的细节：README.md 中示例使用data-control="searchwidget"，但仓库内实际注册的控件名是search-input（见 toolbox.js），后端 Search Widget 的渲染 partial 与 UI 辅助视图 中使用的也都是data-control="search-input"。因此实际使用时请以search-input为准。

二、基本用法：纯 HTML 上手（官方示例完整还原）

官方文档给出的最小可用示例是纯 HTML 结构，不依赖任何后端代码，适合直接在页面中验证控件行为。完整代码如下：

<div>init() { this.$form = this.element.closest('form'); this.$triggerEl = this.$form ? this.$form : this.element; this.$input = this.element.querySelector('[data-search-input]'); this.$clearBtn = this.element.querySelector('[data-search-clear]'); this.extraData = null; }

初始化阶段完成三件事：向上查找最近的<form>（若控件位于表单内，后续 AJAX 请求将以表单为触发容器，自动携带表单数据）；定位[data-search-input]输入框与[data-search-clear]清空按钮；预留extraData字段供请求附加数据。

3.2 连接（connect）与事件监听

connect() { this.element.classList.add('control-search'); this.element.classList.add('size-input-text'); this.element.classList.add('loading-indicator-container'); this.listen('ajax:setup', this.linkToListWidget); this.listen('ajax:request-complete', this.$triggerEl, this.toggleClearButton); this.listen('input', this.$input, this.toggleClearButton); this.listen('click', this.$clearBtn, this.clearInput); this.toggleClearButton(); }

连接阶段注册了四条关键监听：

• ajax:setup：在每次 AJAX 请求配置阶段执行linkToListWidget，将列表联动数据注入请求上下文；
• ajax:request-complete：请求完成后同步清空按钮的显隐状态（例如服务端重置了搜索词后按钮应隐藏）；
• input：用户键入时实时切换清空按钮；
• click：点击清空按钮时执行clearInput。

同时disconnect()会移除上述三个样式类，保证控件销毁后不污染页面样式。

3.3 清空与重新搜索（clearInput）

clearInput() { this.$input.value = ''; this.toggleClearButton(); if (this.$input.dataset.request) { oc.request(this.$input); } }

这是该控件最实用的行为：点击清空按钮后不仅清空输入内容，还会自动重新发起一次 AJAX 请求（前提是输入框定义了data-request）。因此，"清空搜索条件并刷新列表"无需任何额外代码即可实现——这也是搜索体验中非常常见的需求。

3.4 与列表联动（linkToListWidget）

linkToListWidget(ev) { var listId = $(this.element).closest('[data-list-linkage]').data('list-linkage'); if (!listId) { return; } var $widget = $('#'+listId+' > .control-list:first'); if (!$widget.data('oc.listwidget')) { return; } ev.detail.context.options.data.allChecked = $widget.listWidget('getAllChecked'); }

当搜索框外层存在data-list-linkage属性（指向某个 List Widget 的 ID）时，控件会在 AJAX 请求前把列表当前"全选"状态（allChecked）注入请求数据，从而保证搜索过滤时不会丢失用户的选择状态。源码中该处带有// @todo this should be moved to the list widget注释，可见官方倾向未来将此联动逻辑下沉到 List Widget 内部，从源码结构看这是已知的演进方向。

四、与后端 Search Widget 的结合：列表页搜索的真实用法

前端控件只是"壳"，搜索的真正业务逻辑由后端 Backend\Widgets\Search 承担。该类的类注释明确写道："Used for building a toolbar, Renders a search container"，即它专为列表工具栏构建搜索容器而设计。

4.1 可配置属性

通过fillFromConfig（见 Search.php）可知，Search Widget 支持以下配置：

4.2 渲染输出

Widget 渲染时（render()）默认调用 partials/_search.php，其输出与第二节的 HTML 示例结构一致，但加入了 Widget 特有的动态内容：

• data-request="<?= $this->getEventHandler('onSubmit') ?>"：请求指向 Widget 的onSubmit事件处理器；
• name="<?= $this->getName() ?>"：字段名由 getName() 生成，格式为search[term]（别名[term]）；
• <?= !$searchOnEnter ? 'data-track-input' : '' ?>：当配置searchOnEnter: true时，移除data-track-input属性，从而只在回车时触发请求；
• 额外追加is-searchable样式类。

4.3 onSubmit 与搜索词的会话存储

后端处理逻辑集中在 onSubmit()：

1. 通过post($this->getName())读取本次提交的搜索词；
2. 调用setActiveTerm()将搜索词写入会话（session）——空字符串或非字符串值会重置会话，非空值则调用putSession('term', $term)持久化；
3. 触发search.submit事件，供列表等业务方监听并执行过滤；若事件返回数组，则以array_merge合并为可渲染的视图数据；
4. 异常时清空搜索词并重新抛出。

对应的读取侧是getActiveTerm()（见 Search.php），通过getSession('term', '')从会话恢复当前搜索词——这意味着搜索词在请求间天然保持，刷新页面后搜索条件不会丢失。而resetSession()则在搜索词被清空时生效，与前端clearInput()的自动重新请求形成完整闭环。

五、视觉样式：CSS 细节

search-input-control.css 中为.control-search定义了两种特殊场景的视觉规则：

.control-search { &.is-modal-search .form-control, .form-control.recordfinder-search { background-position: right -81px !important; border-top-color: transparent; border-left-color: transparent; border-right-color: transparent; border-radius: 0; padding-left: 22px; } }

• 当容器带有is-modal-search类（弹窗内的搜索框），或输入框带有recordfinder-search类（RecordFinder 控件的搜索框）时，采用"无边框、无圆角、左侧留白 22px"的扁平化样式，使搜索框在弹窗场景下与内容区域融为一体；
• background-position: right -81px !important用于对齐搜索图标的背景位图位置。

六、进阶用法与生态配合

6.1 UI 辅助视图：开箱即用的 PHP 渲染函数

除了手写 HTML 和通过 Widget 渲染，仓库还提供了独立的 UI 辅助视图 modules/system/views/ui/input/search-input.php。它接受name、placeholder、value、handler等变量，并在传入handler时自动追加：

'data-request' => $handler, 'data-request-trigger' => 'input changed delay:500', 'data-load-indicator' => '', 'data-load-indicator-opaque' => true,

其中data-request-trigger="input changed delay:500"表示输入变化后延迟 500ms 防抖再发起请求——这与data-track-input的"即时触发"策略不同，更适合高频输入场景，可显著减少无效请求。

6.2 系统设置侧栏中的搜索

modules/system/partials/_system_sidebar.php 展示了该控件在真实后台页面中的用法：settings-nav控件通过data-search-input="#settings-search-input"指定目标搜索框 ID，实现"在设置列表中键入即过滤菜单项"的效果，点击"Show All Settings"后还会自动$('#settings-search-input').focus()聚焦搜索框。

6.3 与 Toolbox 其他控件的组合

搜索输入控件位于 Toolbox 的controls/目录，与 change-monitor、input-trigger、loader-container、toolbar 等控件平级。实际项目中，搜索框通常作为 Toolbar 的一部分与列表联动——这也正是 Search Widget 类注释中"为构建工具栏而生"的设计定位。

七、总结

October CMS 的 Search Input 解决方案是一条完整的技术链路：

• 前端：data-control="search-input"+data-search-input/data-search-clear属性即可激活控件，自动获得搜索图标、加载指示、实时键入监听与一键清空（清空后自动重新请求）能力，核心逻辑见 search-input-control.js；
• 后端：Backend\Widgets\Search 提供prompt、growable、searchOnEnter等配置项，onSubmit处理器通过search[term]字段读写会话中的搜索词，并通过search.submit事件与列表过滤逻辑解耦；
• 样式：.control-search规则覆盖普通工具栏与弹窗（modal-search / recordfinder-search）两种视觉场景。

无论是手写 HTML 快速验证，还是通过 Search Widget 构建正式列表页搜索，均可直接复用本文的完整示例与源码级解析。

• CMS
• 后端
• 前端