Moodle 搜索输入组件（Search Input）完整指南：三种模板的用法、变量与源码解析

教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载本指南围绕 Moodle 核心组件库中的 search-input 组件文档系统讲解 Moodle 中搜索输入框的三种标准形态默认搜索表单、自动搜索输入带清除按钮与导航栏搜索表单。读完本文你将掌握每个模板的全部上下文变量、适用的 UI 场景选择标准并能从 Mustache 模板源码 与 渲染器实现 层面理解其底层工作原理从而在插件或自定义主题中正确地复刻与扩展这些搜索组件。组件概述Moodle 如何统一搜索交互Moodle 的搜索输入组件core/search_input、core/search_input_auto、core/search_input_navbar于 Moodle 3.10 引入对应 MDL-69454定位为组件库Component library中的标准 UI 构件覆盖在数据集合中查找条目这一通用需求。从 search-input.md 的说明看搜索输入组件有两大行为模式立即反馈式用户输入后立刻借助 JS更新输入框下方展示的数据例如用户列表、设置项表格的即时过滤提交反馈式用户将搜索内容 POST/GET 提交给 Moodle 后由服务端返回结果页。这些搜索框被广泛用于页面导航栏navbar、区块blocks、模块页面、设置页面以及内容库contentbank等位置。Moodle 将其收敛为核心模板正是为了让全站各处的搜索交互保持一致的外观、可访问性与交互细节。默认搜索输入core/search_input最小示例组件库文档给出了默认搜索输入的完整 Mustache 渲染上下文JSON{ action: https://moodle.local/admin/search.php, extraclasses: my-2, inputname: search, inform: false, searchstring: Search something, hiddenfields: [ { name: context, value: 11 } ] }该 JSON 直接对应 search_input.mustache 模板的Example context (json)块。渲染后生成一个simplesearchform包裹的 GET 表单输入框form-control、隐藏字段hiddenfields与提交按钮默认使用btn-submit样式并内嵌a/search图标。模板中{{^inform}}与{{#inform}}的逻辑分支决定了是否输出form标签——当inform为 true 时搜索框作为大表单的一部分嵌入不再自建表单。强调样式搜索输入.btn-primary当搜索是页面上的默认操作且是全页唯一搜索框时导航栏搜索除外文档建议使用强调样式{ action: https://moodle.local/admin/search.php, extraclasses: my-2, uniqid: Unique string, inputname: search, inform: false, btnclass: btn-primary, searchstring: Search something, hiddenfields: [ { name: context, value: 11 } ] }关键在于btnclass变量。对照 search_input.mustache 第 68 行源码button typesubmit classbtn {{^btnclass}}btn-submit{{/btnclass}} {{ btnclass }} search-icon可以确认未提供btnclass时回退到btn-submit默认搜索按钮视觉提供btn-primary时按钮即变为高强调样式。文档给出的选型原则是搜索不是页面主操作 → 使用默认搜索输入btn-submit搜索是页面默认动作、且页面内唯一的搜索框 → 使用强调样式btn-primary。全部上下文变量文档列出的默认搜索模板变量如下结合模板源码可补充细节变量作用源码中对应位置action指定表单get提交的 action 地址模板第 48 行form ... action{{ action }}extraclasses附加到搜索外层 wrapper 的 CSS 类第 46 行simplesearchform {{ extraclasses }}uniqid唯一字符串用于生成输入框 idsearchinput-{{uniqid}}避免重复页面中的 id 冲突第 55 行inputname搜索输入框的表单字段名第 59 行name{{ inputname }}inform是否作为更大表单的一部分true 时不输出form标签第 47-49、79-81 行{{^inform}}/{{#inform}}query用户当前输入的搜索值用于回填输入框第 62 行value{{ query }}btnclass按钮设计使用的 btn 类btn-secondary、btn-primary等第 68 行searchstring描述当前搜索的字符串同时用作 placeholder 与 aria-label第 57、58、65、72 行hiddenfields附加隐藏表单字段的 name/value 键值对数组第 50-52 行buttonattributes模板扩展支持附加到提交按钮上的自定义属性键值对第 69 行注意searchstring在模板中同时填充placeholder、aria-label与辅助技术可见的visually-hidden文本因此它既承担视觉提示也承担无障碍语义是组件库强调搜索提示即无障碍标签的体现。自动搜索输入core/search_input_auto当输入应立即触发下方数据如用户名表格、设置项列表更新时使用自动搜索模板{ placeholder: Search settings, uniqid: 45 }对应 search_input_auto.mustache其核心特征输入框带data-regioninput与data-actionsearch标记第 47 行供 JS 监听输入事件附带一个默认隐藏的清除按钮btn-clear d-nonedata-actionclearsearch用户开始输入后出现点击即清空输入框输入框样式为form-control withclear roundedplaceholder 缺省时回退到search语言字符串模板支持$placeholder、$value、$label、$additionalattributes等 Mustache 块覆盖点方便子模板定制。文档给出的变量仅两个uniqid唯一字符串与placeholder搜索占位文本。其清除交互的底层由 JS 驱动在 search_combobox.js 的选择器定义中[data-actionsearch]与[data-actionclearsearch]正是自动搜索输入框与清除按钮的标准钩子JS 侧通过防抖debounce取自core/utils将输入转换为对下方数据源的即时查询并在输入为空或点击清除时复位结果。导航栏搜索表单core/search_input_navbar导航栏搜索用于触发全站级搜索每页只出现一次且必须尽量少占用空间以免移动端布局被破坏{ action: https://moodle.local/admin/search.php, inputname: search, searchstring: Search, hiddenfields: [ { name: cmid, value: 11 } ] }对照 search_input_navbar.mustache其交互特征与实现要点如下点击搜索按钮开始输入页面初始只显示一个搜索图标a/search通过data-bs-togglecollapse展开#searchform-navbar折叠区域点击关闭按钮隐藏搜索表单内的btn-close按钮绑定data-actionclosesearch收起时清空输入值并恢复搜索图标模板内置的 JS 块监听hidden.bs.collapse/show.bs.collapse/shown.bs.collapse事件并在展开后自动聚焦输入框回车提交表单表单 method 为 get、action 指向搜索地址且内置 JS 会在输入为空时拦截提交submit.addEventListener(click, ...)占用空间极小未展开时仅一个图标符合移动端要求移动端覆盖导航栏折叠面板在窄屏上会叠在导航栏之上展示。该模板在真实页面中的调用点可从 core_renderer.php 的search_box()方法看到当全局搜索启用$CFG-enableglobalsearch且当前用户具备moodle/search:query能力时方法构造action指向/search/index.php、hiddenfields携带当前页面 context id、inputnameq、searchstring与grouplabelsitewidesearch语言串等数据最终调用render_from_template(core/search_input_navbar, $data)渲染。这验证了文档所述导航栏搜索触发全站搜索的事实。此外仓库中还提供了core/search_input_navbar_inlinesearch_input_navbar_inline.mustache这一桌面端内联变体始终可见、不使用折叠与切换适合桌面端导航栏直接展示搜索框的布局场景。选型速查与实战建议综合文档与源码三四种模板的适用场景可归纳如下模板触发方式适用场景关键差异core/search_input表单提交GET普通页面搜索非主操作或作为大表单的一部分inform: true可配btnclass强调支持query回填core/search_input强调样式表单提交页面默认动作且全页唯一搜索框btnclass: btn-primarycore/search_input_autoJS 即时过滤输入即时更新下方数据表格、设置列表内置清除按钮需配合data-action钩子与 JS 监听core/search_input_navbar折叠展开 表单提交每页一次的全局搜索入口空间极小、移动端覆盖导航栏、自带折叠与聚焦逻辑core/search_input_navbar_inline常驻可见 表单提交桌面端导航栏直接展示无折叠始终可见在插件开发中使用这些组件时推荐直接在 PHP 侧构造与文档示例一致的 context 数组并调用$OUTPUT-render_from_template(core/search_input_auto, $data)或复用core_renderer::search_box()的思路传递action/hiddenfields/inputname。若需自定义自动搜索的过滤逻辑可在页面上引入core/comboboxsearch/search_combobox模块源码见 search_combobox.js它已经内置了对[data-actionsearch]输入框、[data-actionclearsearch]清除按钮、下拉结果区与查看全部链接的标准事件绑定是扩展自动搜索交互的现成基础。最后提醒由于这些模板属于核心组件库组件文档位于 public/admin/tool/componentlibrary主题与插件作者应优先复用核心模板而非自行重写搜索框这样既能保证全站一致的视觉与无障碍标准也能在核心组件升级如导航栏搜索交互调整时自动获得改进。赞分享教育后端前端【免费下载链接】moodleMoodle - the worlds open source learning platform项目地址https://gitcode.com/gh_mirrors/mo/moodle点击查看免费下载相关推荐Moodle Toggle Input开关输入组件开发指南core/toggle 模板的参数、块复用与真实用例Moodle Toggle Input开关输入组件开发指南core/toggle 模板的参数、块复用与真实用例 Moodle 4.0 起引入的 core/教育后端前端formily/element Password 密码输入框组件三种 Schema 用法与源码实现解析formily/element Password 密码输入框组件三种 Schema 用法与源码实现解析 本文围绕 Formily 生态中 Element 版前端UI组件Formily Next 组件详解Input 文本输入框的三种 Schema 接入方式与源码原理Formily Next 组件详解Input 文本输入框的三种 Schema 接入方式与源码原理 本指南以 Formily 的 Next 适配层 form前端UI组件上一篇30分钟生成可引导EFIOpCore-Simplify 黑苹果自动配置教程下一篇如何快速修复损坏的视频文件Untrunc完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考