@askdialog / dialog-react
用于Dialog ai产品辅助的React组件库。
目录表
安装
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
使用
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
client={client}
productId="product-123"
productTitle="Product Name"
/>
);
}
可用的组件
DialogProductBlock
产品块，最多有2个产品问题和一个“问别的”按钮，打开助手，最多有5个关于产品的产品问题。按钮标签根据客户端的语言环境使用英语、法语或西班牙语（否则使用英语）。
道具:
client（Dialog） - Dialog SDK客户端实例（必需）productId（字符串）-产品编号（必需）productTitle（字符串）-产品名称（必需）selectedVariantId（字符串，可选）-选定的变体IDenableInput（boolean，可选）-已弃用。显示输入字段，而不是“Ask something else”按钮（默认值：false）
例子:
<DialogProductBlock
client={client}
productId="9403924119882"
productTitle="Blizzard King All-Mountain Snowboard"
selectedVariantId="variant-123"
/>
DialogInput
用于提问的独立输入组件。它显示了固定的“问AI一个问题”文本和AI披露行，根据客户端区域使用英语，法语或西班牙语（否则为英语）。
道具:
client（Dialog） - Dialog SDK客户端实例（必需）productId（字符串）-产品编号（必需）productTitle（字符串）-产品名称（必需）placeholder（字符串，可选）-已弃用，忽略selectedVariantId（字符串，可选）-选定的变体ID
例子:
<DialogInput
client={client}
productId="9403924119882"
productTitle="Product Name"
/>
店面搜索
useDialogSearch 的搜索控制器 @askdialog/dialog-sdk 到组件状态。控制器保存搜索状态、结果和上下文（语言、国家、业务排名、文本），并管理请求和分析；这些组件呈现SDK的连接器（搜索框、点击、部分、分页）并处理导航。
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 (
<>
<DialogSearchBar controller={controller} placeholder="Search products..." />
<DialogSearchResults controller={controller} state={state} theme={theme} />
</>
);
}
useDialogSearch
为每个钩子实例创建一个搜索控制器，并在卸载时处理它。控制器加载商家的业务排名和搜索配置 client.apiKey 在第一次打开或搜索。
选项:
client（Dialog） - Dialog SDK客户端实例（必需）language（字符串，必需）-小写的ISO 639-1语言代码，例如：frcountry（字符串，必选）-购物者的ISO 3166-1 alpha-2国家，例如。BE;价格随市场而定surface（SearchSurface，可选）-显示结果的地方，用于分析(默认：'search_page'）navigate（(url, hit: SearchProductHit) => void, optional） -选择属性后调用的路由器适配器(例如：(url) => router.push(url)）. 省略它，让卡片更清晰<a href>链接本地导航。storefrontRoot（字符串，可选）-命中的相对路径_display.url解决以下问题，例如：/或者/fr-fr/(Shopifywindow.Shopify.routes.root）; 默认的/buildProductUrl（已弃用，忽略）-每个命中的链接都是它的_display.urldebounceMs（数字，可选）-击键计数（默认：100）hitsPerPage（数目，可选）-每页结果（默认：12）sections（SearchSection[]，可选）-与产品一起搜索的额外索引；collections的集合列DialogSearchResults． 只请求目录公开的索引：缺少索引将使整个搜索失败。
搜索语言和国家是明确而独立的 client.locale，它可以是区域区域设置，例如 fr-FR.
返回: { controller, state, theme } -将它们传递给下面的组件。
controller（SearchController） -的控制器@askdialog/dialog-sdk;将其传递给SDK的连接器(connectHits(controller)，…)来构建自定义UIstate（SearchSnapshot） -控制器的快照，在每次更改时重新渲染：searchState（查询和请求的页面，按索引名称键入），results（status是idle/loading/success/empty/error，products，sections，error),context（language，country，businessRanking，texts）theme（主题）-客户的主题，为DialogSearchResults
对于公开集合索引的目录，使用collections列：
const { controller, state, theme } = useDialogSearch({
client,
language: 'en',
country: 'US',
sections: [{ index: 'collections', hitsPerPage: 5 }],
});
DialogSearchBar
搜索输入绑定到搜索框连接器：它的值是控制器的查询，输入运行一个去绑定的搜索，提交（Enter）立即搜索。聚焦输入打开搜索，它发出 TRACK_OPENED_SEARCH 分析事件并运行空查询搜索。
道具:
controller（SearchController） - FromuseDialogSearch(必需)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） - FromuseDialogSearch(必需)state（SearchSnapshot） - FromuseDialogSearch(必需)locale（string，可选）-计数和标签的BCP 47语言环境；省略，在搜索中使用连接器的显示language． 价格由服务器格式化。theme（主题，可选）-客户端的主题，由useDialogSearch;样式面板（调色板，半径，字体）layout（'list' | 'grid'，可选)-产品布局(默认：'list'）seeAllHref（(query) => string, optional） -“查看所有结果”页脚按钮的链接；省略后，面板只显示第一页的点击，没有分页
DialogSearchPagination
带有页面指示器的“上一步”/“下一步”控件，绑定到分页连接器；在加载和只有一个页面时隐藏。不是由 DialogSearchResults，它不会分页：在您自己的结果页面上使用它。
道具:
controller（SearchController） - FromuseDialogSearch(必需)state（SearchSnapshot） - FromuseDialogSearch(必需)locale（string，可选）-按钮标签的区域设置；省略时的搜索语言
DialogSearchProductCard
一个产品卡，如 DialogSearchResults 渲染它，用于自定义布局。它呈现hit连接器的显示 state.results.products.hits[index] 记录它的印象和选择；它没有为一个不受欢迎的打击提供任何东西 index 在显示的结果中。
道具:
controller（SearchController） - FromuseDialogSearch(必需)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客户端自定义主题：
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
设置
# From monorepo root
pnpm install
开发工作流程
日常开发
对组件进行即时反馈；
# From monorepo root
pnpm dev:react-example
# Opens react-example app at http://localhost:5173
发生了什么:
- 示例应用程序在Vite开发服务器上运行
- 组件从 源文件 （
packages/react/src/)通过别名 - 对组件的更改立即反映出来（启用HMR）
- 无需重建
测试构建库
测试这个库，就像消费者从npm接收它一样：
# 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
何时使用：
- 在创建拉取请求之前
- 修改构建配置后
- 验证构建工作是否正确
- 在发布新版本之前
构建命令
# 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项目中测试这个包：
# 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
出版
# From monorepo root
pnpm publish:react
Pre-publish清单:
- 所有测试都通过
- 版本更新于
package.json - 使用内置库进行测试(
pnpm dev:test-dist） - Tarball检查
pnpm pack - 更新日志更新
打印稿
这个包包含TypeScript类型定义。这些类型在安装包时自动可用。
反应版本
这个包需要React 19或更高版本作为对等依赖。