For the complete documentation index, see llms.txt. This page is also available as Markdown.

渲染链接和链接预览

将角色发送的链接转换为可点击链接、媒体卡片和 Open Graph 站点卡片,可在 Convai 小组件中或你自己的聊天界面中使用。

将角色发送的链接渲染为可点击链接,并显示图片、视频和文档卡片,而不是按字面文本显示 [Doc](https://…) markdown。使用此页面可开启链接、通过以下方式添加 Open Graph 网站卡片: linkPreviewResolver,或在你自己构建的聊天 UI 中安全地渲染链接。

前提条件

开启链接

设置 preserveLinksInOutput: true 在客户端配置中。 ConvaiWidget 和 createConvaiWidget 无需额外配置即可渲染这些链接。

src/App.tsx
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} />;
}
src/main.ts
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 缩短。

最后更新于

这有帮助吗?