# @askdialog/dialog-react 中文文档 规范地址：https://npmcn.com/package/%40askdialog/dialog-react/ 版本：3\.3\.0 npm 元数据更新时间：2026-10-31T13:33:04.066Z 中文译文更新时间：2026-10-31T14:31:17.337Z 软件包许可：未声明 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40askdialog/dialog-react 原文对照：https://npmcn.com/package/%40askdialog/dialog-react/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：85.5 kB，36 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@askdialog/dialog-sdk ^3\.1\.0 - 首次发布：2025-11-27T15:23:12.913Z - 最新版本发布：2026-10-31T13:33:03.909Z - 已发布版本数：107（近 12 个月 107 个） ## 中文简介 用于Dialog ai产品辅助的React组件库。 ## 安装 ```sh npm install @askdialog/dialog-react ``` 也可以使用：`pnpm add @askdialog/dialog-react`、`yarn add @askdialog/dialog-react`、`bun add @askdialog/dialog-react` ## README # @askdialog / dialog-react 用于Dialog ai产品辅助的React组件库。 ## 目录表 - [安装](https://npmcn.com/package/%40askdialog/dialog-react/#readme-installation) - [使用](https://npmcn.com/package/%40askdialog/dialog-react/#readme-usage) - [可用的组件](https://npmcn.com/package/%40askdialog/dialog-react/#readme-available-components) - [DialogProductBlock](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialogproductblock) - [DialogInput](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialoginput) - [店面搜索](https://npmcn.com/package/%40askdialog/dialog-react/#readme-storefront-search) - [useDialogSearch](https://npmcn.com/package/%40askdialog/dialog-react/#readme-usedialogsearch) - [DialogSearchBar](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialogsearchbar) - [DialogSearchResults](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialogsearchresults) - [DialogSearchPagination](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialogsearchpagination) - [DialogSearchProductCard](https://npmcn.com/package/%40askdialog/dialog-react/#readme-dialogsearchproductcard) - [从2.x升级](https://npmcn.com/package/%40askdialog/dialog-react/#readme-upgrading-from-2x) - [主题](https://npmcn.com/package/%40askdialog/dialog-react/#readme-theming) - [开发](https://npmcn.com/package/%40askdialog/dialog-react/#readme-development) - [打印稿](https://npmcn.com/package/%40askdialog/dialog-react/#readme-typescript) - [反应版本](https://npmcn.com/package/%40askdialog/dialog-react/#readme-react-version) ## 安装 ```bash npm install @askdialog/dialog-react @askdialog/dialog-sdk # or pnpm add @askdialog/dialog-react @askdialog/dialog-sdk # or yarn add @askdialog/dialog-react @askdialog/dialog-sdk ``` ## 使用 ```tsx import { Dialog } from '@askdialog/dialog-sdk'; import { DialogInput, DialogProductBlock } from '@askdialog/dialog-react'; import '@askdialog/dialog-react/style.css'; const client = new Dialog({ apiKey: 'your-api-key', locale: 'en', currency: 'EUR', callbacks: { addToCart: () => Promise.resolve(), getProduct: () => Promise.resolve({ // Product data }), }, }); function App() { return ( ); } ``` ## 可用的组件 ### DialogProductBlock 产品块，最多有2个产品问题和一个“问别的”按钮，打开助手，最多有5个关于产品的产品问题。按钮标签根据客户端的语言环境使用英语、法语或西班牙语（否则使用英语）。 **道具:** - `client` （Dialog） - Dialog SDK客户端实例（必需） - `productId` （字符串）-产品编号（必需） - `productTitle` （字符串）-产品名称（必需） - `selectedVariantId` （字符串，可选）-选定的变体ID - `enableInput` （boolean，可选）-已弃用。显示输入字段，而不是“Ask something else”按钮（默认值：false） **例子:** ```tsx ``` ### DialogInput 用于提问的独立输入组件。它显示了固定的“问AI一个问题”文本和AI披露行，根据客户端区域使用英语，法语或西班牙语（否则为英语）。 **道具:** - `client` （Dialog） - Dialog SDK客户端实例（必需） - `productId` （字符串）-产品编号（必需） - `productTitle` （字符串）-产品名称（必需） - `placeholder` （字符串，可选）-已弃用，忽略 - `selectedVariantId` （字符串，可选）-选定的变体ID **例子:** ```tsx ``` ### 店面搜索 `useDialogSearch` 的搜索控制器 `@askdialog/dialog-sdk` 到组件状态。控制器保存搜索状态、结果和上下文（语言、国家、业务排名、文本），并管理请求和分析；这些组件呈现SDK的连接器（搜索框、点击、部分、分页）并处理导航。 ```tsx import { Dialog } from '@askdialog/dialog-sdk'; import { DialogSearchBar, DialogSearchResults, useDialogSearch, } from '@askdialog/dialog-react'; import '@askdialog/dialog-react/style.css'; const client = new Dialog({ apiKey: 'your-api-key', locale: 'en-US', currency: 'USD' }); function SearchPage() { const { controller, state, theme } = useDialogSearch({ client, language: 'en', country: 'US' }); return ( <> ); } ``` #### useDialogSearch 为每个钩子实例创建一个搜索控制器，并在卸载时处理它。控制器加载商家的业务排名和搜索配置 `client.apiKey` 在第一次打开或搜索。 **选项:** - `client` （Dialog） - Dialog SDK客户端实例（必需） - `language` （字符串，必需）-小写的ISO 639-1语言代码，例如： `fr` - `country` （字符串，必选）-购物者的ISO 3166-1 alpha-2国家，例如。 `BE`;价格随市场而定 - `surface` （SearchSurface，可选）-显示结果的地方，用于分析(默认： `'search_page'`） - `navigate` （(url, hit: SearchProductHit) => void, optional） -选择属性后调用的路由器适配器(例如： `(url) => router.push(url)`）. 省略它，让卡片更清晰 `` 链接本地导航。 - `storefrontRoot` （字符串，可选）-命中的相对路径 `_display.url` 解决以下问题，例如： `/` 或者 `/fr-fr/` (Shopify `window.Shopify.routes.root`）; 默认的 `/` - `buildProductUrl` （已弃用，忽略）-每个命中的链接都是它的 `_display.url` - `debounceMs` （数字，可选）-击键计数（默认：100） - `hitsPerPage` （数目，可选）-每页结果（默认：12） - `sections` （SearchSection\[\]，可选）-与产品一起搜索的额外索引； `collections` 的集合列 `DialogSearchResults`． 只请求目录公开的索引：缺少索引将使整个搜索失败。 搜索语言和国家是明确而独立的 `client.locale`，它可以是区域区域设置，例如 `fr-FR`. **返回:** `{ controller, state, theme }` -将它们传递给下面的组件。 - `controller` （SearchController） -的控制器 `@askdialog/dialog-sdk`;将其传递给SDK的连接器(`connectHits(controller)`，…)来构建自定义UI - `state` （SearchSnapshot） -控制器的快照，在每次更改时重新渲染： `searchState` （查询和请求的页面，按索引名称键入）， `results` （`status` 是 `idle` / `loading` / `success` / `empty` / `error`， `products`， `sections`， `error`), `context` （`language`， `country`， `businessRanking`， `texts`） - `theme` （主题）-客户的主题，为 `DialogSearchResults` 对于公开集合索引的目录，使用collections列： ```tsx const { controller, state, theme } = useDialogSearch({ client, language: 'en', country: 'US', sections: [{ index: 'collections', hitsPerPage: 5 }], }); ``` #### DialogSearchBar 搜索输入绑定到搜索框连接器：它的值是控制器的查询，输入运行一个去绑定的搜索，提交（Enter）立即搜索。聚焦输入打开搜索，它发出 `TRACK_OPENED_SEARCH` 分析事件并运行空查询搜索。 **道具:** - `controller` （SearchController） - From `useDialogSearch` (必需) - `placeholder` （字符串，可选）-输入占位符文本 - `autoFocus` （布尔值，可选）-将输入集中在mount上 - `submitAriaLabel` （字符串，可选）-提交按钮的可访问标签(默认： `'Search'`） #### DialogSearchResults 浮动结果面板覆盖页面内容：传送到 `document.body` 在 `position: fixed`，位于条的中心（最大1440px宽，填充视口），并锚定在组件渲染的位置（将其放置在条的后面），因此没有祖先堆叠上下文或 `overflow: hidden` 可以隐藏它。它显示了与Shopify搜索覆盖相同的布局：在左边有一个集合列 `sections` 请求它们，将右边的产品作为列表或3列网格，查询匹配在每个标题中强调，并且，当 `seeAllHref` 设置后，有“查看所有结果”按钮；没有它，面板只显示点击的第一页，不分页。在768px以下，面板堆叠，集合在产品上方的水平轨道上。颜色，半径和字体遵循SDK主题(深色调色板时 `backgroundColor` 是暗角、直角还是圆角呢 `ctaBorderType`）. 每个产品卡呈现点击连接器的点击显示，Algolia的Shopify记录：its `_display.image` (点击需要 `_display`，服务器从DAT-2016开始计算；当 `_display.image` 是缺席，没有缩略图；它的 `shape` 用主题的角来绘制 `theme`，直角 `square`，圆角 `rounded` 作为一个圆圈 `round`),其 `_display.title`,它的 `_display.price` （由服务器以购物者的市场货币进行格式化），在它旁边敲开 `_display.compare_at_price` 当存在时，和它 `_display.url` (相对的，在 `storefrontRoot`）; 没有价格的成功说明没有价值。每张卡片都链接到产品页面，并自动记录搜索属性（视图印象，点击和中键选择）。点击面板外（和栏外）关闭它；再次输入或重新聚焦工具条将重新打开，并保留结果。 **道具:** - `controller` （SearchController） - From `useDialogSearch` (必需) - `state` （SearchSnapshot） - From `useDialogSearch` (必需) - `locale` （string，可选）-计数和标签的BCP 47语言环境；省略，在搜索中使用连接器的显示 `language`． 价格由服务器格式化。 - `theme` （主题，可选）-客户端的主题，由 `useDialogSearch`;样式面板（调色板，半径，字体） - `layout` （`'list' | 'grid'`，可选)-产品布局(默认： `'list'`） - `seeAllHref` （(query) => string, optional） -“查看所有结果”页脚按钮的链接；省略后，面板只显示第一页的点击，没有分页 #### DialogSearchPagination 带有页面指示器的“上一步”/“下一步”控件，绑定到分页连接器；在加载和只有一个页面时隐藏。不是由 `DialogSearchResults`，它不会分页：在您自己的结果页面上使用它。 **道具:** - `controller` （SearchController） - From `useDialogSearch` (必需) - `state` （SearchSnapshot） - From `useDialogSearch` (必需) - `locale` （string，可选）-按钮标签的区域设置；省略时的搜索语言 #### DialogSearchProductCard 一个产品卡，如 `DialogSearchResults` 渲染它，用于自定义布局。它呈现hit连接器的显示 `state.results.products.hits[index]` 记录它的印象和选择；它没有为一个不受欢迎的打击提供任何东西 `index` 在显示的结果中。 **道具:** - `controller` （SearchController） - From `useDialogSearch` (必需) - `hit` (SearchProductHit) - `state.results.products.hits[index]` (必需) - `index` （数字）-命中在显示结果中的位置（必填） #### 从2.x升级 组件保留它们的道具和呈现，除了分页 `DialogSearchResults`； `useDialogSearch` 保留它的选项。改变什么: - `DialogSearchResults` 不再分页：没有 `seeAllHref` 它只显示第一页的点击。集 `seeAllHref`，或渲染 `DialogSearchPagination` 在你自己的搜索结果页面上。 - `controller` 的控制器 `@askdialog/dialog-sdk`： `setQuery`， `submit` 和 `setPage` 都被 `setSearchState` 和 `search` （或SDK的连接器）， `getState` 由 `getSnapshot`， `observeResult` / `selectResult` 由 `observeHit` / `selectHit`. - `state` 控制器的快照是否已读 `state.results.status`， `state.results.products` 和 `state.results.sections` 而不是 `state.status`， `state.response` 和 `state.sections`, `state.context.businessRanking` 而不是 `state.businessRanking`. - 没有一个 `locale` 道具，文本和价格跟随搜索 `language` 和 `country` 而不是英文和浏览器的数字格式。 - 对等 `@askdialog/dialog-sdk` 是3. x。 ## 主题 组件使用CSS变量进行主题化。您可以通过Dialog SDK客户端自定义主题： ```tsx const client = new Dialog({ apiKey: 'your-api-key', theme: { backgroundColor: 'pink', primaryColor: 'pink', ctaTextColor: 'white', ctaBorderType: 'rounded', capitalizeCtas: true, fontFamily: 'Arial', highlightProductName: true, title: { fontSize: '22px', color: 'purple', }, description: { color: 'blue', fontSize: '18px', }, content: { color: 'green', fontSize: '10px', }, }, }); ``` ## 开发 本节是为库本身工作的贡献者编写的。 ### 先决条件 - Node.js >= 22 - PNPM >= 10 ### 设置 ```bash # From monorepo root pnpm install ``` ### 开发工作流程 #### 日常开发 对组件进行即时反馈； ```bash # From monorepo root pnpm dev:react-example # Opens react-example app at http://localhost:5173 ``` **发生了什么:** - 示例应用程序在Vite开发服务器上运行 - 组件从 **源文件** （`packages/react/src/`)通过别名 - 对组件的更改立即反映出来（启用HMR） - 无需重建 #### 测试构建库 测试这个库，就像消费者从npm接收它一样： ```bash # Step 1: Build the library pnpm build:react # Step 2: Run example app against built dist/ cd packages/react-example pnpm dev:test-dist # Or from root: TEST_DIST=true pnpm dev:react-example ``` **何时使用：** - 在创建拉取请求之前 - 修改构建配置后 - 验证构建工作是否正确 - 在发布新版本之前 ### 构建命令 ```bash # Build the library only pnpm build:react # Build all packages in the monorepo pnpm build # Clean dist folder pnpm --filter @askdialog/dialog-react clean # Lint code pnpm --filter @askdialog/dialog-react lint # Fix linting issues pnpm --filter @askdialog/dialog-react lint:fix ``` ### 项目结构 ``` packages/react/ ├── src/ │ ├── main.ts # Library entry point │ ├── components/ # Exported components │ │ ├── index.ts # Component barrel export │ │ └── DialogProductBlock/ │ │ ├── DialogProductBlock.tsx │ │ ├── DialogProductBlock.css │ │ ├── DialogInput.tsx │ │ ├── DialogInput.css │ │ ├── ThemeProvider.tsx │ │ └── ... │ └── icons/ # Icon components ├── dist/ # Build output (gitignored) ├── package.json ├── vite.config.ts # Library build configuration └── project.json # Nx configuration ``` ### 测试包 #### 完全集成测试 在真实的React项目中测试这个包： ```bash # 1. Build and pack cd packages/react pnpm build pnpm pack # 2. Create test project cd /tmp pnpm create vite test-dialog --template react-ts cd test-dialog pnpm install # 3. Install from tarball pnpm add /path/to/askdialog-dialog-react-*.tgz # 4. Test imports and functionality pnpm dev ``` ### 出版 ```bash # From monorepo root pnpm publish:react ``` **Pre-publish清单:** - [ ] 所有测试都通过 - [ ] 版本更新于 `package.json` - [ ] 使用内置库进行测试(`pnpm dev:test-dist`） - [ ] Tarball检查 `pnpm pack` - [ ] 更新日志更新 ## 打印稿 这个包包含TypeScript类型定义。这些类型在安装包时自动可用。 ## 反应版本 这个包需要React 19或更高版本作为对等依赖。 ## 常见问题 ### @askdialog/dialog-react 是什么？ 用于Dialog ai产品辅助的React组件库。 ### 如何安装 @askdialog/dialog-react？ 在项目目录运行 npm install @askdialog/dialog-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@askdialog/dialog-sdk（^3\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @askdialog/dialog-react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @askdialog/dialog-react 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @askdialog/dialog-react 可以商用吗？ @askdialog/dialog-react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @askdialog/dialog-react 还在维护吗？ 最新版本 3\.3\.0 发布于 2026/10/31（2 天前）；至今共发布 107 个版本，其中过去 12 个月发布了 107 个；首次发布于 2025/11/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。