FlowToken 🌊

用于 LLM 文本流式传输的流畅动画库

FlowToken 是一个 React 组件库，旨在提升大型语言模型（LLM）文本流式传输的视觉呈现效果。该库提供了多种动画效果，使文本以平滑、动态的方式呈现，从而为用户提供更具吸引力的交互体验。

演示

在此尝试演示：演示链接

特性

FlowToken 包含以下主要特性：

• 可定制的动画：提供淡入、模糊进入、下拉进入、从左侧滑入、打字机效果、逐词拉起、翻转文本、渐进式间距等多种动画。
• 流畅的文本流式传输：支持控制文本出现的速度和方式，以适应不同文本生成速度的变化。
• 响应式且轻量级：针对性能进行了优化，并兼容所有现代浏览器。

安装

使用 npm 安装 FlowToken：

npm install flowtoken

或使用 yarn：

yarn add flowtoken

使用方法

Markdown 支持

要使用 Markdown，需导入 AnimatedMarkdown 组件。

import React from 'react';

import { AnimatedMarkdown } from 'flowtoken';
// 导入 flowtoken 的 CSS 样式以便使用动画
import 'flowtoken/dist/styles.css';

const App = () => {
  return (
    <AnimatedMarkdown
      content="## Hello, world!"
      animation="fadeIn"
      animationDuration="0.5s"
      animationTimingFunction="ease-in-out"
    />
  );
};

export default App;

Vercel AI SDK 实际应用

'use client'

import { useChat } from 'ai/react'
import { AnimatedMarkdown } from 'flowtoken';
import 'flowtoken/dist/styles.css';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat()

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}: <AnimatedMarkdown content={m.content}
            animation="dropIn"
            animationDuration="0.5s"
            animationTimingFunction="ease-in-out"
            />
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <label>
          说点什么...
          <input
            value={input}
            onChange={handleInputChange}
          />
        </label>
      </form>
    </div>
  )
}

自定义组件

可以通过向 AnimatedMarkdown 组件传递 customComponents 属性来使用自定义组件，其中键为 XML 标签（例如 MyComponent），用于匹配，值则是要渲染的组件。只需让您的 LLM 输出自定义组件的语法，它就会以您自定义的组件形式呈现出来。

const customComponents = {
  'customcomponent': ({ animateText, node, children, ...props }: any) => {
    return (
      <>
        {animateText(<div {...props}>{children}</div>)}
      </>
    )
  },
}
...
<AnimatedMarkdown content="Hello, world! <customcomponent>这是一个自定义组件</customcomponent>" customComponents={customComponents} />

示例

这是一个自定义组件的示例。

AnimatedMarkdown 属性

• content（字符串）：要显示的文本。
• sep（"word" | "char"）：如何分割并动画化内容。默认值为 "word"。
• animation（字符串 | null）：要应用的 CSS 动画名称（例如 fadeIn、dropIn）。设置为 null 可禁用已完成消息的动画。
• animationDuration（字符串）：动画的 CSS 持续时间（例如 0.6s）。
• animationTimingFunction（字符串）：动画的 CSS 时间函数（例如 ease、ease-in-out）。
• codeStyle（对象）：用于代码块的语法高亮样式对象。
• customComponents（Record<string, React.ComponentType>）： 正则表达式模式或自定义标签名到 React 组件的映射。可用于渲染 LLM 输出的任意语法。
• imgHeight（字符串）：渲染图像的默认高度（例如 200px）。

动画效果

FlowToken 支持多种 CSS 动画：

• fadeIn
• blurIn
• typewriter
• slideInFromLeft
• fadeAndScale
• rotateIn
• bounceIn
• elastic
• highlight
• blurAndSharpen
• dropIn
• slideUp
• wave

对于自定义动画，可在 CSS 中定义关键帧，将其包裹在类中，然后将动画名称传递给 animation 属性。

/* custom-styles.css */

@keyframes custom-animation {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

.custom-animation {
  animation: custom-animation 1s ease-in-out;
}

import 'custom-styles.css';
...
<AnimatedMarkdown content="Hello, world!" animation="custom-animation" />

注意事项

为降低内存占用，可在任何已完成的消息上将 animation 参数设置为 null 来禁用动画。

如果将 Tailwind 与生成的 Markdown 一起使用，请确保配置 Tailwind Typography：https://github.com/tailwindlabs/tailwindcss-typography

并在 FlowToken 的 Markdown 容器中添加 prose lg:prose-md prose-pre:p-0 prose-pre:m-0 prose-pre:bg-transparent。

贡献

欢迎贡献！请随时提交 Pull Request 或打开 Issue，以提出功能建议或报告 Bug。

许可证

FlowToken 采用 MIT 许可证。

FlowToken 快速上手指南

FlowToken 是一个专为大语言模型（LLM）文本流设计的 React 动画库，能让 AI 生成的文字以平滑、动态的特效呈现，显著提升用户体验。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 建议版本 16.0 或更高。
• 框架: 适用于 React 项目（支持 Next.js, Vite, Create React App 等）。
• 依赖管理: npm 或 yarn。
• 样式支持: 若需渲染 Markdown 样式，建议配置 Tailwind CSS Typography 插件（可选，但推荐）。

安装步骤

使用 npm 或 yarn 将 flowtoken 添加到你的项目中。

使用 npm:

npm install flowtoken

使用 yarn:

yarn add flowtoken

提示：国内开发者若遇到下载缓慢问题，可配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

基本使用

1. 引入组件与样式

在使用组件前，务必同时导入组件和对应的 CSS 样式文件，否则动画效果无法生效。

import { AnimatedMarkdown } from 'flowtoken';
import 'flowtoken/dist/styles.css';

2. 最简单的示例

以下是一个基础用法，展示带有淡入动画的文本：

const App = () => {
  return (
    <AnimatedMarkdown
      content="## Hello, world!"
      animation="fadeIn"
      animationDuration="0.5s"
      animationTimingFunction="ease-in-out"
    />
  );
};

export default App;

3. 结合 Vercel AI SDK (实战场景)

如果你正在构建 AI 聊天应用，可以结合 useChat 钩子实时渲染流式数据：

'use client'

import { useChat } from 'ai/react'
import { AnimatedMarkdown } from 'flowtoken';
import 'flowtoken/dist/styles.css';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat()

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}: <AnimatedMarkdown content={m.content}
            animation="dropIn"
            animationDuration="0.5s"
            animationTimingFunction="ease-in-out"
            />
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <label>
          Say something...
          <input
            value={input}
            onChange={handleInputChange}
          />
        </label>
      </form>
    </div>
  )
}

核心参数说明

• content: 需要显示的文本内容（支持 Markdown）。
• animation: 动画名称（如 fadeIn, typewriter, blurIn 等），设为 null 可禁用动画。
• animationDuration: 动画持续时间（如 0.5s）。
• sep: 动画粒度，可选 "word" (按词) 或 "char" (按字符)，默认为 "word"。

FlowToken 内置了多种动画效果，包括 fadeIn, blurIn, typewriter, slideInFromLeft, dropIn 等，也可通过自定义 CSS Keyframes 扩展专属动画。