渲染链接和链接预览
将角色发送的链接转换为可点击链接、媒体卡片和 Open Graph 站点卡片,可在 Convai 小组件中或你自己的聊天界面中使用。
将角色发送的链接渲染为可点击链接,并显示图片、视频和文档卡片,而不是按字面文本显示 [Doc](https://…) markdown。使用此页面可开启链接、通过以下方式添加 Open Graph 网站卡片: linkPreviewResolver,或在你自己构建的聊天 UI 中安全地渲染链接。
前提条件
已安装 Convai Web SDK,并且有可连接的客户端。参见 Web SDK 快速入门.
开启链接
设置 preserveLinksInOutput: true 在客户端配置中。 ConvaiWidget 和 createConvaiWidget 无需额外配置即可渲染这些链接。
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';
export default function App() {
const client = useConvaiClient({
apiKey: 'YOUR_API_KEY',
characterId: 'YOUR_CHARACTER_ID',
preserveLinksInOutput: true,
});
return <ConvaiWidget convaiClient={client} />;
}import { ConvaiClient } from '@convai/web-sdk/core';
import { createConvaiWidget } from '@convai/web-widget/vanilla';
const client = new ConvaiClient({
apiKey: 'YOUR_API_KEY',
characterId: 'YOUR_CHARACTER_ID',
preserveLinksInOutput: true,
});
createConvaiWidget(document.body, { convaiClient: client });该标志只在会话连接时读取一次。要更改它,请重新连接;不重新连接的 UI 开关不会影响当前会话。
该标志会以
preserve_links_in_output发送,并在未设置时省略,因此会使用服务器默认值。如果你在服务器上为/connect请求构建connectWithConnectionData(),请在那里添加该字段。如果你自己渲染
chatMessages,请预期在内容中出现 markdown 链接,一旦该标志开启。语音不受影响;URL 不会被朗读。SSE 传输不会发送该标志,Interaction API 也没有按请求对应的等价项:通过 SSE 的链接遵循部署中的
PRESERVE_LINKS_IN_LLM_OUTPUT设置,该设置默认关闭。在 SSE 客户端上设置preserveLinksInOutput没有效果。要在 SSE 聊天中显示链接,请让你的 Convai 联系人针对你的部署启用该设置。
每个链接的渲染方式
两个 widgets 的链接渲染方式相同。预览只会出现在角色气泡中。用户自己的气泡会保持链接可点击,并带有相同的悬停标题,但绝不会嵌入媒体,因此粘贴的 URL 不会把远程媒体拉入转录内容。
网页
带下划线的链接。较长的裸 URL 会被缩短以便显示;悬停时显示完整 URL。
新标签页
—
图片(png jpg gif webp avif)
先显示加载骨架,再显示图片和一个 主机 · 文件 说明文字。
会打开灯箱。按 Esc、点击背景层或 × 可将其关闭; 打开原始内容 会在新标签页中打开。
预览不可用 — 主机 · 文件 在出错后或加载 12 秒无结果后。 http: 在 https: 页面上的图片绝不会被请求。
视频(mp4 webm mov ogg)
带原生控件的卡片。
播放、全屏
与图片相同。
文档(pdf doc docx xls xlsx csv ppt pptx txt md zip)
带扩展名方块、文件名以及 主机 · 在新标签页中打开.
新标签页
不会获取任何内容,因此不会失败。
mailto:, tel:, sms:
带图标和地址的胶囊。悬停会说明会发生什么。
交由操作系统处理
按浏览器设计,缺少处理程序时会静默处理。
ftp:
带有 FTP 徽标的链接。悬停会警告,大多数浏览器已不再打开这些链接。
新标签页
浏览器会静默拒绝。
javascript:, data: 及其他协议
以点状文本显示的标签,绝不会是链接。
无
—
一条消息最多显示 6 张卡片。更多媒体或文档链接会渲染为普通链接。
骨架是一个半透明块,基于 currentColor生成,因此它会匹配 widget 所在的背景。在 prefers-reduced-motion.
下会禁用其闪烁效果和灯箱入场动画
createConvaiWidget 在原生 widget 中为卡片设置样式 part 属性,你可以在宿主页中进行样式设置:
链接
message-link, message-link-badge, message-link-blocked, message-contact
媒体卡片
message-media-card, message-media, message-media-zoom, message-media-skeleton, message-media-caption, message-media-unavailable
文档卡片
message-file-card, message-file-icon, message-file-name, message-file-meta
图片灯箱
lightbox, lightbox-backdrop, lightbox-image, lightbox-caption, lightbox-close, lightbox-open
网站卡片
message-site-card, message-site-favicon, message-site-name, message-site-title, message-site-description, message-site-image
为网页添加网站卡片
一个普通网页链接可以显示页面自己的卡片:favicon、站点名称、标题、描述和图片,这些都来自其 Open Graph 和 Twitter 标签。浏览器无法获取其他源的页面,因此你需要提供一个解析器,让它向你的后端请求这些元数据。
MarkdownRenderer 将同一个函数作为其 resolveLinkPreview 属性传入。
解析器返回
{ url, title?, description?, image?, siteName?, favicon? }或null。只有结果包含title或image.时才会绘制卡片。解析器运行时不会显示任何内容,失败或返回
null时也不会显示任何内容。链接本身不受影响。结果会在页面加载期间按 URL 缓存,因此同一个 URL 被引用两次只会产生一次请求。
网站卡片只出现在角色气泡中,并计入 6 张卡片的限制。媒体和文档链接保留自己的卡片,且不会展开。
image和favicon仅在它们是绝对http(s)URL 时才会使用。其他所有字段都作为文本渲染,绝不会作为标记。
你的解析器端点会代表用户抓取页面。需要会话;在 DNS 解析后拒绝私有地址和回环地址;重新检查每一次重定向;限制时间和响应大小;并且绝不转发 cookies。
在你自己的聊天 UI 中渲染链接
如果你使用 useConvaiClient 或 ConvaiClient 进行连接,但自己绘制消息列表,角色文本会以纯字符串的形式传给你。请使用 SDK 的气泡渲染器或其分词器来渲染它。
在 React 中使用气泡渲染器
MarkdownRenderer 是 React widget 绘制的组件,因此你无需额外代码即可获得卡片、骨架和协议白名单。请传入 media={false} 到用户自己的气泡中,以保留链接但移除嵌入内容。
基于分词器构建渲染器
parseInlineMarkdown 会把一行文本转换为你可以映射到自己标记中的节点。它导出自 @convai/web-sdk/core, @convai/web-sdk/vanilla 和 @convai/web-sdk/react.
一个尚未流式传入其结束
)的链接会保持为文本,因此气泡在响应过程中不会在不同形态之间闪烁。compactUrl会缩短一个用于显示的长裸 URL,例如a.example.com/…/file.mp4,而不会改变 href。绝不要把其结果用作 href。linkKindForUrl和describeUrl会给你与 widgets 相同的分类和主机 · 文件说明文字,resolveLinkPreviewCached则会在你自己绘制网站卡片时提供 widgets 共享的解析器缓存。
协议白名单
仅 http, https, ftp, ftps, mailto, tel 和 sms 会变成链接。其他所有内容,包括 javascript: 和 data:,会变成一个 blocked 节点,而 widgets 会将其渲染为文本。
API 参考
preserveLinksInOutput
布尔值
客户端选项。通过 /connect 作为 preserve_links_in_output发送。服务器默认关闭。连接时只读取一次。
linkPreviewResolver
LinkPreviewResolver
ConvaiWidget 属性和 createConvaiWidget 选项。用于普通网页链接的 Open Graph 查询;若不需要网站卡片则省略。
MarkdownRenderer
React.FC<{ text: string; media?: boolean; resolveLinkPreview?: LinkPreviewResolver }>
React widget 的气泡渲染器。 media 默认为 true;在 false 用户自己的气泡中传入。
resolveLinkPreview
LinkPreviewResolver
MarkdownRenderer 用于与 linkPreviewResolver.
LinkPreviewResolver
(url: string, signal: AbortSignal) => Promise<LinkPreviewMeta | null>
相同查找的属性。
LinkPreviewMeta
{ url, title?, description?, image?, siteName?, favicon? }
解析器返回的内容。
resolveLinkPreviewCached
(resolver, url) => Promise<LinkPreviewMeta | null>
渲染器共享的按 URL 缓存。
parseInlineMarkdown
(line: string) => InlineNode[]
把一行文本转换为 文本, strong, em, link, image 和 blocked 节点。
InlineNode
联合类型
{ kind: 'link', href, label, media }, { kind: 'image', src, alt }, { kind: 'blocked', href, label },以及 文本, strong 和 em.
isSafeHref
(url: string) => boolean
true 当 URL 的协议在白名单中且可用作 href 时。
mediaKindForUrl
(url: string) => 'image' | 'video' | null
按文件扩展名对 URL 进行分类; null 表示不可预览。
linkKindForUrl
(url: string) => LinkKind
安全 URL 的展示类别: 网页, image, 视频, 文档, 电子邮件, 电话, sms 或 ftp.
LinkKind
联合类型
这些值 linkKindForUrl 上都以相同方式工作。
describeUrl
(url: string) => string
主机 · 文件,用于说明文字。
compactUrl
(url: string, max?: number) => string
仅用于显示的长 URL 缩短。
最后更新于
这有帮助吗?