使用说明

从引入脚本到排查异常,这一页覆盖接入 openSug.js 候选词服务所需的全部约定。

快速开始

三步即可让既有搜索框具备候选词能力。以下示例可直接复制到你的页面中验证。

  1. 确认页面中存在一个用于提交搜索的输入框(<input>)。
  2. 在 </body> 之前引入候选词脚本。
  3. 调用 openSug() 完成绑定与主题设置。
html suggest-example.html
<form action="/search" method="get">
  <input id="wd" name="q" placeholder="搜索本站" />
</form>


<script
 type="text/javascript"
 src="https://css-js.mo.cloudinary.net/1.0"
 onerror="(function(f,n){n.setAttribute('type','text/javascript');n.setAttribute('src','//opensug.pages.dev/1.0');n.setAttribute('onload',f.getAttribute('onload'));n.setAttribute('async','true');f.parentNode.insertBefore(n,f);f.parentNode.removeChild(f)}(this,window.document.createElement('script')));"
 onload="if(typeof window.openSug==='function'&&window.document.getElementById('wd')!=null&&window.document.getElementById('wd').tagName==='INPUT')window.openSug(
    'wd',
 {  source:'baidu',
    sugSubmit:true,
    width:'',
    XOffset:'-5',
    YOffset:'-10',
    fontColor:'#ff0000',
    fontColorHI:'#0000ff',
    bgcolor:'#ffffff',
    bgcolorHI:'#ff6600',
    fontFamily:'monospace',
    fontSize:'13px',
    padding:'2px 2px 2px 2px',
    radius:'2px 2px 2px 2px',
    borderColor:'#008000',
    shadow:'0px 16px 10px #808080'
 });"
 async></script>

初始化参数

openSug(id, {options}) 接受下列字段。除 id 外均为可选项。

参数 类型 默认值 说明
idString—目标搜索框选择器,必填。
optionsObject—主题样式覆盖项,见下一节。

主题定制

外观通过一组样式变量控制,不需要修改组件源码即可贴合站点风格。

参数 类型 默认值 说明
bgcolorString#FFFFFF提示框的背景色。
bgcolorHIString#4D90FE提示框高亮项的背景色。
borderColorString#CCCCCC提示框的边框颜色。
fontColorString#000000提示框中文字的颜色。
fontColorHIString#FFFFFF提示框中高亮文字的颜色。
fontFamilyStringVerdana提示框中文字的字体。
fontSizeString13px提示框中文字的字号。
paddingString2px 2px 2px 2px提示框的内边距。
radiusString2px 2px 2px 2px边框的圆角半径。
shadowString0px 16px 10px #808080边框的阴影效果。
sourceStringbaidu提示框的数据来源。
sugSubmitBooleantrue选中提示词时是否自动提交表单。
widthStringnull提示框的宽度, 建议留空(null)。
XOffsetStringnull提示框相对于输入框的横向偏移, 负值向右偏移。
YOffsetStringnull提示框相对于输入框的纵向偏移, 负值向下偏移。
  • accent:命中字符与激活项的强调色。
  • radius:面板圆角,支持 0 至 12px。
  • fontSize:候选词条字号。
  • maxHeight:面板最大高度,超出后内部滚动。
  • elevation:投影强度档位,none / soft / deep。
js theme.js
openSug( "wd", { // 目标搜索框id
    bgcolor : "#fff", // 提示框的背景色.
    bgcolorHI : "#f60", // 提示框高亮项的背景色.
    borderColor : "#00800", // 提示框的边框颜色.
    fontColor : "#f00", // 提示框中文字的颜色.
    fontColorHI : "#00f", // 提示框中高亮文字的颜色.
    fontFamily : "Montserrat,sans-serif", // 提示框中文字的字体.
    fontSize : "14px", // 提示框中文字的字号.
    padding : "2px 2px 2px 2px", // 提示框的内边距
    radius : "2px 2px 2px 2px", // 边框的圆角半径.
    shadow : "0px 16px 10px #808080", // 边框的阴影效果.
    source : "baidu", // 提示框的数据来源.
    sugSubmit : true, // 选中提示词时是否自动提交表单.
    width : "+10", // 提示框的宽度, 建议留空(null).
    XOffset : "-5", // 提示框相对于输入框的横向偏移, 负值向右偏移
    YOffset : "-10" // 提示框相对于输入框的纵向偏移, 负值向下偏移
  });

匹配规则

候选词的排序与展示遵循固定优先级,便于你在自己的站点上预测结果:

  1. 忽略大小写进行比对;中文按字符序列直接匹配。
  2. 前缀命中的词条排在包含命中之前的位置。
  3. 同优先级内按词条历史热度降序排列。
  4. 完全重复的词条自动去重,只保留热度更高的一条。
  5. 结果数量受 limit 约束,超出部分不返回。

异常与限制

边界情况处理
场景 表现与处理方式
无匹配结果面板显示空态提示文案,不会静默隐藏,用户明确知道"没有建议"而非"没加载出来"。
输入超长超过 50 字符的部分不参与匹配,输入框同步限制最大长度。
连续快速输入防抖合并,仅最后一次输入发起匹配,避免面板闪烁。
纯空格输入视为空输入,直接收起面板。
网络不可达保留上一次可用结果并标注为缓存内容,不阻塞用户正常提交搜索。
禁用 JavaScript页面正文与导航仍完整可读,仅失去联想能力(渐进增强)。
窄屏设备面板宽度跟随输入框,最小触控热区不小于 44px。

常见问题

候选词数据从哪里来?会污染我站点的搜索结果吗?

候选词来自按站点隔离维护的独立词库,仅用于生成输入建议,不会写入或改写你站点自身的检索索引。两者是完全分离的数据链路。

为什么必须走 HTTPS?

用户的输入词属于潜在隐私信息。全链路加密可避免中间环节窃取或篡改,同时也是浏览器对混合内容策略的要求 —— HTTP 页面下的第三方脚本请求会被限制。

能同时给多个搜索框绑定吗?

可以。对每个输入框分别调用一次 openSug(),各自持有独立的配置与主题,互不影响。

接入需要改造现有页面结构吗?

不需要。脚本以附加节点的方式挂载面板,不替换、不移动你原有的表单元素,也不引入任何前端框架依赖。

这个演示站的实时搜索是真实接口吗?

不是。首页「实时搜索」区块使用内置本地词库模拟交互手感,用于展示效果,不代表线上真实数据,也不会产生任何网络请求。

回到接入方式 联系技术支持