← 返回自动完成组件参考 · 全部使用指导

自动完成使用指导

• 自动完成使用指导
  • 工作原理
  • 快速上手
  • 案例一：记住搜索历史
  • 案例二：省份与城市两级联动
  • 案例三：联网搜索建议
  • 常见问题
  • 平台说明
  • 完整 .aia 源码：大学查询与输入联想
    • 大学查询与输入联想

自动完成给文本输入框加上下拉联想：用户每输入一个字，输入框下方弹出匹配的候选词，点一下自动填入。 常用于搜索框、城市和商品名输入、历史记录提示，能减少打字、避免输错。

工作原理

• 不替换输入框：组件只在输入框下方挂一个候选列表，输入框原有的属性、事件照常可用；
• 一个组件管多个输入框：对每个输入框分别调用设置候选词（文本输入框，候选词）（SetSuggestions）即可， 再次调用会替换这个输入框原来的候选词；
• 匹配规则：默认「包含即匹配」（输入「京」能匹配「北京」「南京」），任意位置匹配（MatchAnywhere） 设为假时只匹配开头；英文不区分大小写；
• 何时弹出：输入字数达到起始字数（Threshold）（默认 1）时开始提示，最多显示最多条数（MaxResults）条（默认 8）；
• 用户点了候选词后触发选中候选词时（文本输入框，选择项）（SuggestionSelected），此时候选词已填进输入框。

快速上手

拖一个文本输入框、一个标签和一个自动完成：

when Screen1.Initialize() {
  自动完成1.SetSuggestions(文本输入框1, list("北京", "上海", "广州", "深圳", "南京", "东京"))
}

when 自动完成1.SuggestionSelected(文本输入框, 选择项) {
  标签1.Text = join("你选了：", 选择项)
}

在输入框里打「京」，下方弹出「北京」「南京」「东京」；点「南京」，输入框自动填入，标签显示「你选了：南京」。

案例一：记住搜索历史

每次搜索后把关键词存进微数据库，下次打开 App 输入时就能从历史里联想：

global 历史 = []

when Screen1.Initialize() {
  历史 = 微数据库1.GetValue("搜索历史", [])
  自动完成1.SetSuggestions(文本输入框_搜索, 历史)
}

when 按钮_搜索.Click() {
  if not contains(历史, 文本输入框_搜索.Text) {
    listAdd(历史, 文本输入框_搜索.Text)
    微数据库1.StoreValue("搜索历史", 历史)
    自动完成1.SetSuggestions(文本输入框_搜索, 历史)
  }
  标签_结果.Text = join("搜索：", 文本输入框_搜索.Text)
}

历史变了之后重新调用一次设置候选词（文本输入框，候选词）（SetSuggestions），新的候选立刻生效。

案例二：省份与城市两级联动

两个输入框：先输入省份，选中后城市输入框的候选词换成该省的城市：

when Screen1.Initialize() {
  自动完成1.SetSuggestions(文本输入框_省份, list("广东", "江苏", "浙江"))
}

when 自动完成1.SuggestionSelected(文本输入框, 选择项) {
  if 选择项 == "广东" {
    自动完成1.SetSuggestions(文本输入框_城市, list("广州", "深圳", "珠海", "佛山", "东莞"))
  } else if 选择项 == "江苏" {
    自动完成1.SetSuggestions(文本输入框_城市, list("南京", "苏州", "无锡", "常州"))
  } else if 选择项 == "浙江" {
    自动完成1.SetSuggestions(文本输入框_城市, list("杭州", "宁波", "温州", "绍兴"))
  }
}

一个自动完成组件同时管着两个输入框；事件里的「选择项」只可能来自省份框的候选（城市名不会是省份名），所以直接按选中的文字判断即可。

案例三：联网搜索建议

候选词来自服务器：输入框内容一变就请求接口，接口返回用逗号分隔的建议词（如 苹果手机,苹果汁,苹果派）， 收到后拆成列表设为候选：

when 文本输入框_搜索.TextChanged() {
  Web1.Url = join("https://example.com/api/suggest?q=", Web1.UriEncode(文本输入框_搜索.Text))
  Web1.Get()
}

when Web1.GotText(URL网址, 响应代码, 响应类型, 响应内容) {
  if 响应代码 == 200 {
    自动完成1.SetSuggestions(文本输入框_搜索, split(响应内容, ","))
  }
}

要点：

• 把起始字数（Threshold）设为 2，少发无意义的请求；
• 接口返回 JSON 时，用 Web 的「解码 JSON 文本」取出建议列表再设置；
• 网络慢时候选会晚一点出现，属于正常现象。

常见问题

平台说明

• 安卓：完整支持；
• 鸿蒙：候选浮层独立更新，输入时不重建输入框；选中写回文本并触发真实事件。失焦或空候选关闭浮层。真机键盘、焦点及触摸效果尚未实测。

完整 .aia 源码：大学查询与输入联想

下载 .aia 源码

资料沿用中国大学排名案例，20所大学、真实校徽与资料来源全部打包，无需联网或账号。导入AutoCompleteAllFeatures.aia，空关键词先显示全部。输入“京”可选北京大学或南京大学，点击候选或搜索结果看对应大学的排名、特色与来源。“上次查看的大学”读取独立本地记录，重新打开仍可查看。

联想设置默认收起；可分别调整起始字数、最多条数、是否匹配任意位置，并显示实际属性读回。三个设计器属性明确非默认配置，初始化按界面1／8／真同步；暂停候选不影响实际查询，恢复使用资料中的真实大学名称。错误整数拒绝，未知关键词显示零结果，不虚构候选事件。

覆盖AutoComplete的所有11项接口配置与读写。校验记录内部保留；真机和伴侣尚未实测。资料时期、排名及特色引用方式沿用大学资料来源。

大学查询与输入联想

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 随工程打包真实大学资料和校徽；输入大学名片段可选择联想候选，也可查看搜索结果、大学详情和上次查看记录。联想设置默认收起。无需网络或账号。 覆盖11/11，正式编辑器首次载入与保存重开零错误，后台导入及安装包编译通过。真机／伴侣尚未实测。