# @constructor-io/constructorio-ui-autocomplete 中文文档
规范地址：https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/
版本：1\.30\.1
npm 元数据更新时间：2026-09-05T02:56:57.332Z
中文译文更新时间：2026-11-10T16:16:20.290Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40constructor-io/constructorio-ui-autocomplete
原文对照：https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/?lang=original
项目主页：https://github.com/Constructor-io/constructorio-ui-autocomplete#readme
源码仓库：https://github.com/Constructor-io/constructorio-ui-autocomplete
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：592 kB，131 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14
- 运行依赖：0 个
- peer 依赖：react \>=16\.12\.0，tslib ^2\.5\.0，downshift ^7\.2\.1，react-dom \>=16\.12\.0，@constructor-io/constructorio-client-javascript ^2\.67\.6
- 首次发布：2023-01-31T18:26:55.353Z
- 最新版本发布：2026-07-14T10:10:08.114Z
- 近 30 天下载量：12242（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：123（近 12 个月 16 个）
## 中文简介
用于 Web 应用程序的自动完整 UI 库
## 安装
```sh
npm install @constructor-io/constructorio-ui-autocomplete
```
也可以使用：`pnpm add @constructor-io/constructorio-ui-autocomplete`、`yarn add @constructor-io/constructorio-ui-autocomplete`、`bun add @constructor-io/constructorio-ui-autocomplete`
## README
# 自动完成 UI
轻而易举、最小化和完全定制的自动完成组件,用于快速、无障碍和灵活的搜索体验 [构造器.io的自动建议服务](https://constructor.com/solutions/search)
 [](https://www.npmjs.com/package/@constructor-io/constructorio-ui-autocomplete) [](https://github.com/Constructor-io/constructorio-ui-autocomplete/blob/main/LICENSE)
## 文档
查看完整的组件文档和现场实例 [故事书](https://constructor-io.github.io/constructorio-ui-autocomplete/?path=/docs/getting-started-introduction--docs)
## 目录
- [概览](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-overview)
- [安装和快速启动](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-installation--quick-start)
- [基本用途( 反应)](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-basic-usage-react)
- [整合模式](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-integration-modes)
- [购买](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-shopify)
- [安装和快速启动](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-installation--quick-start-1)
- [++ 存储- 特定默认值](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme--shopify-specific-defaults)
- [Bundle (瓦努阿图联署材料)](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-bundle-vanilla-js)
- [安装和快速启动](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-installation--quick-start-2)
- [自定义](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-customization)
- [解决问题](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-troubleshooting)
- [补充资源](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-complementary-resources)
- [捐款](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-contributing)
- [许可证](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/#readme-license)
## 概览
Autocomplete UI提供轻量级和自定义的自定义自定义完成组件. 它使开发者能够快速地用 Constructionor 执行快速,可访问的搜索体验. io的自动建议服务.
- QQ Easy Introduction – 作为插件和游戏回放组件快速与您的应用程序集成
- QQ 轻快- 小捆绑大小, 为速度优化
- QQ自定义 UI – 样式最小, 支持自定义标记
- QQ 键盘导航 – 完全支持可访问键盘导航
- QQ 访问( a11y) – 为屏幕阅读器建有 ARIA 支持
- QQ 在类型安全的脚本中写入
**[探索完整的文件 −](https://constructor-io.github.io/constructorio-ui-autocomplete/?path=/docs/getting-started-introduction--docs)**
## 安装和快速启动
安装库
```sh
npm i @constructor-io/constructorio-ui-autocomplete
```
### 基本用途( 反应)
导入和使用 `CioAutocomplete` 组件
```tsx
import { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';
import '@constructor-io/constructorio-ui-autocomplete/styles.css';
function YourComponent() {
return (
{console.log(e)}}
/>
);
}
```
## 整合模式
### 购买
#### 安装和快速启动
构造器自动完整组件作为组件的一部分可用 [构造器.io 商店化应用程序](https://apps.shopify.com/constructor-connect)
在安装了应用程序后, 您可以在主题编辑器中点击“ 添加部分” 并添加“ 构造器” 自动完整液体组件
更多深度指示请查看 [购买文档](https://docs.constructor.com/docs/integrating-with-constructor-platform-connectors-frontend-connectors-shopify-ui)。 。 。 .
#### ++ 存储- 特定默认值
如果您正在使用 Hishify 内部的构造器自动补全组件而不使用 [构造器.io 商店化应用程序](https://apps.shopify.com/constructor-connect),可以使用 `useShopifyDefaults` 启用自动导航处理的道具 :
```tsx
```
**它会做什么:**
- **产品选择**: 自动重定向到产品细节页面
- **搜索建议**: 以选定的查询重定向到搜索结果页面
- **手动搜索**: 用输入的查询重定向到搜索结果页面
- **查询参数**: 保存所有已存在的 URL 查询参数( 如 UTM 参数)
**配置 :**
- `shopifySettings.searchUrl`: 搜索结果页 URL( 如: `'{{ block.settings.search_url }}'` 液体模板)
**说明:** 何时 `useShopifyDefaults={true}`,任何习惯 `onSubmit` 您提供的处理器将覆盖默认行为 .
## Bundle (瓦努阿图联署材料)
这是一种框架不可知论方法,可用于任何JavaScript项目. CioAutocomplete功能提供了一个简单的接口,可以将整个Autocomplete UI注入到所提供的选择器中. 除了Autocomplete组件道具,此功能还接受一个选择器并包含CSS.
#### 安装和快速启动
安装库
```sh
npm i @constructor-io/constructorio-ui-autocomplete
```
导入和使用 `CioAutocomplete` 组件
```javascript
import CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/constructorio-ui-autocomplete-bundled';
CioAutocomplete({
selector: '#autocomplete-container',
includeCSS: true, // Include the default CSS styles. Defaults to true.
apiKey: 'key_M57QS8SMPdLdLx4x',
onSubmit: (submitEvent) => console.dir(submitEvent),
// ... additional arguments
});
```
## 自定义
CSS样式并非默认导入. 将此添加到您的代码中以导入基本样式
```tsx
import '@constructor-io/constructorio-ui-autocomplete/styles.css';
```
所有风格都标注在.cio-autocomplete下. 你可以通过瞄准选择者来扩展它们.
```css
/* Custom Style Sheet */
.cio-autocomplete .cio-submit-btn {
border-radius: 10px;
border: 1px solid red;
}
```
如果你想要覆盖或扩展基地 `className`,你可以做到这一点与 `autocompleteClassName` 参数
```tsx
import { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';
import '@constructor-io/constructorio-ui-autocomplete/styles.css';
function YourComponent() {
return (
{ console.log(e)}}
autocompleteClassName="cio-autocomplete custom-autocomplete-container"
/>
);
```
然后可以修改这样的风格
```css
/* Custom Style Sheet */
.cio-autocomplete.custom-autocomplete-styles .cio-input {
font-weight: bold;
}
```
## 解决问题
共同的问题和解决办法.
| 问题 | 说明 | 解决方案 |
| --- | --- | --- |
| 旧的 Java 脚本环境 | 图书馆提供两种不同的建筑. 通用JS(cjs)和ECMAScript模块(mjs)
对于 ECMAScript 模块 (mjs) 构建, JavaScript 版本是 ESNext, 您的环境可能不支持它 。 如果情况是这样,而你的环境正在使用像ES6(ES-2015)这样的更古老的Javascript版本,你可能会得到这个错误.
`Module parse failed: Unexpected token (15:32) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file` | 要解决这个问题,您可以导入支持ES6(ES-2015)语法的普通JS(cjs)构建:
`import CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/cjs'` |
| ESLint 语录 | ESLint有一个众所周知的问题,即它未能解决国家预防机制一揽子计划出口说明所暴露的道路.
为ECMAScript模块(mjs)所建. Javascript 版本是 ESNext, 它可能不会被您的环境所支持 。 如果情况是这样,而你的环境正在使用像ES6(ES-2015)这样的更古老的Javascript版本,你可能会得到这个错误.
`Unable to resolve path to module '@constructor-io/constructorio-ui-autocomplete/styles.css'`
相关的未决问题:
- [问题1868](https://github.com/import-js/eslint-plugin-import/issues/1868)
- [问题1810](https://github.com/import-js/eslint-plugin-import/issues/1810)
| 如果您收到以下错误, 您可以使用 ESLint 安全禁用 `// eslint-disable-line` 为这条线. |
| 同伴依赖关系 | 库需要安装一对对等的依赖,所以如果还没有安装,就确保安装.
1. [构造- 客户- javascript](https://github.com/Constructor-io/constructorio-client-javascript)
2. [下调](https://github.com/downshift-js/downshift)
| 运行 `npm i downshift @constructor-io/constructorio-client-javascript` |
需要帮忙吗? 加入我们 [GitHub 讨论](https://github.com/Constructor-io/constructorio-ui-autocomplete/discussions)
## 补充资源
- 完整文档 : [故事书](https://constructor-io.github.io/constructorio-ui-autocomplete/)
- JS客户端: [SDK 文档](https://constructor-io.github.io/constructorio-client-javascript/module-autocomplete.html#~getAutocompleteResults)
- \* 购买应用程序 : [App Store 链接](https://apps.shopify.com/constructor-connect)
- (原始内容存档于2018-10-21) (英语). Restor's REST API: [自动完成](https://docs.constructor.com/reference/v1-autocomplete-get-autocomplete-results)
## 捐款
1. 叉出 repo 创建新分支( C) .
2. 运行 `npm install` 以安装依赖.
3. 在进行预期修改后, 运行 `npm run tests && npm run lint` 当地.
4. 提交公关审查.
## 许可证
[MIT 许可证](https://npmcn.com/package/%40constructor-io/constructorio-ui-autocomplete/LICENSE)
版权(c) 2022年至今
## 常见问题
### @constructor-io/constructorio-ui-autocomplete 是什么？
用于 Web 应用程序的自动完整 UI 库
### 如何安装 @constructor-io/constructorio-ui-autocomplete？
在项目目录运行 npm install @constructor-io/constructorio-ui-autocomplete，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.12\.0）、tslib（^2\.5\.0）、downshift（^7\.2\.1）、react-dom（\>=16\.12\.0）、@constructor-io/constructorio-client-javascript（^2\.67\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @constructor-io/constructorio-ui-autocomplete 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @constructor-io/constructorio-ui-autocomplete 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @constructor-io/constructorio-ui-autocomplete 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @constructor-io/constructorio-ui-autocomplete 可以商用吗？
@constructor-io/constructorio-ui-autocomplete 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @constructor-io/constructorio-ui-autocomplete 的下载量有多少？
根据 npm 官方下载统计，@constructor-io/constructorio-ui-autocomplete 在 2026/10/11 – 2026/11/09 这 30 天内被下载 12,242 次，日均约 408 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @constructor-io/constructorio-ui-autocomplete 还在维护吗？
最新版本 1\.30\.1 发布于 2026/07/14（3 个月前）；至今共发布 123 个版本，其中过去 12 个月发布了 16 个；首次发布于 2023/02/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。