UI 片段

你可以使用 Cloudflare AI Search UI 片段库 ↗轻松将 AI Search 添加到网站，该库提供可投入生产、可自定义的 Web 组件。

该库是开源的，地址为 github.com/cloudflare/ai-search-snippet ↗。

可用组件

片段库提供四个 Web 组件。每个组件通过 api-url 属性连接到你的 AI Search 实例，该属性应指向你的公共端点 URL。

组件	说明
`<search-bar-snippet>`	内联搜索栏，结果在下拉列表中显示
`<search-modal-snippet>`	可通过 `Cmd/Ctrl+K` 键盘快捷键打开的搜索模态框
`<chat-bubble-snippet>`	页面角落的浮动聊天气泡
`<chat-page-snippet>`	带对话历史的全页聊天界面

有关高级样式与配置，请访问 search.ai.cloudflare.com ↗。

前提条件

UI 片段通过公共端点连接到 AI Search 实例。使用片段前需要启用该端点。

在 Cloudflare 仪表板中前往 AI Search。
Go to AI Search ↗
选择你的 AI Search 实例。
前往 Settings（设置） > Public Endpoint（公共端点）。
打开 Enable Public Endpoint（启用公共端点）。
复制公共端点 URL。你将在片段中将其用作 api-url 属性。

与 HTML 一起使用

将 script 标签添加到 HTML 文件（例如 index.html）。将 <INSTANCE_ID> 替换为 AI Search 实例公共端点的 ID，可在实例的 Settings（设置） > Public Endpoint（公共端点） 中找到。
```
<script
	type="module"
	src="https://<INSTANCE_ID>.search.ai.cloudflare.com/assets/v0.0.25/search-snippet.es.js"
></script>
```

添加带有你的 api-url 的组件。

<search-bar-snippet
	api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
	placeholder="Search..."
></search-bar-snippet>

测试前，配置 CORS 以允许本地 origin。然后在浏览器中打开 HTML 文件进行测试。

完整 HTML 示例

以下示例展示带搜索栏的完整 HTML 页面。用户在搜索栏中输入时，结果会显示在下方的下拉列表中。

<!doctype html>
<html>
	<head>
		<script
			type="module"
			src="https://<INSTANCE_ID>.search.ai.cloudflare.com/assets/v0.0.25/search-snippet.es.js"
		></script>
	</head>
	<body>
		<search-bar-snippet
			api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
			placeholder="Search..."
			max-results="10"
		></search-bar-snippet>
	</body>
</html>

与框架一起使用

打开 React 项目并安装软件包：

npm install @cloudflare/ai-search-snippet

在组件文件（例如 src/App.tsx）中导入该软件包：
```
import "@cloudflare/ai-search-snippet";
```

将组件添加到 JSX：

export default function App() {
	return (
		<search-bar-snippet
			api-url="https://<INSTANCE_ID>.search.ai.cloudflare.com/"
			placeholder="Search..."
		/>
	);
}

测试前，配置 CORS 以允许本地 origin。然后运行开发服务器：
```
npm run dev
```

该软件包包含 TypeScript 类型，可与 React、Next.js 及其他 React 框架配合使用。

打开 Vue 项目并安装软件包：

npm install @cloudflare/ai-search-snippet

在组件文件（例如 src/App.vue）中导入软件包并添加组件：

<template>
	<search-bar-snippet :api-url="apiUrl" placeholder="Search..." />
</template>

<script setup>
import "@cloudflare/ai-search-snippet";

const apiUrl = "https://<INSTANCE_ID>.search.ai.cloudflare.com/";
</script>

测试前，配置 CORS 以允许本地 origin。然后运行开发服务器：
```
npm run dev
```

配置组件

每个组件都接受控制其行为的属性。常见属性包括：

属性	说明
`api-url`	必需。实例的公共端点 URL。
`placeholder`	输入框的占位文本。
`max-results`	请求的最大结果数。
`theme`	`light`、`dark` 或 `auto`（默认，跟随系统主题）。
`hide-branding`	隐藏 Cloudflare 品牌标识。
`translations`	覆盖面向用户的字符串，以本地化组件。

聊天组件（<chat-bubble-snippet> 和 <chat-page-snippet>）还接受 chat-query-rewrite，用于将后续消息重写为独立查询。

完整属性列表以及可生成 HTML、React 或 Vue 代码的实时编辑器，请使用片段 playground ↗。

自定义外观

使用以 --search-snippet- 为前缀的 CSS 自定义属性为组件设置样式。可在组件或父元素上设置：

search-bar-snippet {
	--search-snippet-primary-color: #f6821f;
	--search-snippet-border-radius: 12px;
}

playground ↗ 列出了所有可用变量，并实时预览你的更改。

为本地测试配置 CORS

本地测试时（例如 http://localhost:3000），需要在公共端点设置中允许本地 origin。

在 Cloudflare 仪表板中前往 AI Search。
Go to AI Search ↗
选择你的 AI Search 实例。
前往 Settings（设置） > Public Endpoint（公共端点）。
在 Authorized hosts（授权主机） 下，添加本地 URL（例如 http://localhost:3000），或添加 * 以在测试期间允许所有 origin。
选择 Save（保存）。