FluidMarkdown

我们致力于在人工智能驱动的业务应用中，实现大型语言模型生成的Markdown内容在客户端上的流式渲染。

概述

本库专为原生Android、iOS和HarmonyOS开发者设计。基于开源的CommonMark解析库构建，支持核心Markdown语法及部分HTML标签，并在UI组件中逐步渲染这些内容。它将Markdown样式暴露为结构化模型，便于自定义并集成到您的特定应用环境中。为了加快集成速度，您可以参考示例代码，根据输入文本预览渲染效果。

特性

• 支持Markdown语法：标题、段落、有序列表、无序列表、表格、代码块、数学公式、行内代码块、引用、分隔线、脚注、链接和图片。
• 支持HTML标签：<s> <sup> <sub> <mark> <a> <span> <cite> <del> <font> <img> <u> 等。
• 流式渲染与一次性完整渲染模式。
• Markdown语法的渲染样式可自定义。
• 通过自定义参数调整流式渲染速度。
• 对可点击元素的支持事件，包括点击处理、可见性回调及渲染状态更新等。
• 在AMHTMLTransformer类中新增了一些扩展HTML标签，如<iconlink> <icon>。

安装

该项目的源代码是开源的。有关如何下载和运行该项目的信息，请参阅文件INSTALL。

目录结构

iOS

• AntMarkdown —— 基于CommonMark的标准Markdown解析与渲染模块。
• FluidMarkdown —— 用于流式输出的组件。

Android

• fluid-markdown —— 用于流式输出的组件。
• markwon-xxx —— 基于开源markwon库的语法解析和样式渲染实现。

HarmonyOS

• markdown —— 该文件夹包含Markdown组件的所有源代码，例如语法解析、布局渲染、主题配置、运行时服务等。
• playground —— 一个演示程序，用于展示Markdown组件的功能列表。

your/project/markdown/src/main/ets
├── engine					//	[文件夹] 引擎管理运行时的所有服务和插件。
├── index.ets       //  [文件]   默认导出。
├── markdown.ets		//	[文件]   符合@ComponentV2规范的Markdown组件。
├── render					//	[文件夹] 基于StyledString机制的渲染相关逻辑。
├── service					//	[文件夹] 运行时服务模块，如语法解析、代码高亮等。
├── theme						//	[文件夹] 基于StyledString机制的样式和主题相关逻辑。
└── util						//	[文件夹] 内置工具API。

使用方法

iOS

• 原生API：AMXMarkdownWidget.h 是公开API的汇总头文件。以下是流式渲染组件的一般调用流程：
  1. 创建一个TextView实例。
  2. 生成默认样式并设置自定义样式（如果需要）。
  3. 开始流式渲染Markdown内容。
  4. 在渲染过程中动态追加数据。
  5. 根据TextView中内容大小的变化调整列表滚动。
  6. 渲染完成后处理完成事件。

AMXMarkdownTextView* contentTextView = [[AMXMarkdownTextView alloc] initWithFrame_ant_mark:CGRectMake(0, 0, screenWidht - 20 * 2, 1)];

// 获取默认样式配置
AMXMarkdownStyleConfig* config = [AMXMarkdownStyleConfig defaultConfig];

// 以代码块样式为例进行修改
config.codeBlockConfig.backgroundColor = [UIColor greenColor];

// 设置具有唯一ID的样式
[[AMXRenderService shared] setMarkdownStyleWithId:config styleId:@"demo"];

// 开始打印
[self.contentTextView startStreamingWithContent:@"testing data"];

// 打印过程中追加内容
[self.contentTextView addStreamContent:@"**append test data**"];

// 需要时停止打印
[self.contentTextView stop];

@interface StreamPreviewViewController ()<AMXMarkdownTextViewDelegate>
-(void)initUI
{
    // 设置代理
    self.contentTextView.textViewDelegate = self;
}
// 尺寸变化代理
-(void)onSizeChange:(CGSize)size
{
    // 调整AMXMarkdownTextView和容器视图的尺寸
    [self.contentTextView setFrame:CGRectMake(0, 0, self.contentTextView.frame.size.width, size.height)];
    [self.containerView setContentSize:size];
    CGPoint bottomOffset = CGPointMake(0, self.containerView.contentSize.height - self.containerView.bounds.size.height);
    if (bottomOffset.y > 0) {
        // 滚动容器视图到底部
        [self.containerView setContentOffset:bottomOffset animated:NO];
    }
}

• 示例说明
  1. StreamPreviewViewController 类是一个用于预览流式输出的示例页面。
  2. AIChatViewController 类展示了FluidMarkdown在模拟AI对话场景中的使用。请注意，对话数据是静态定义的，仅用于渲染演示目的。

Android

1. 全局范围内只需调用一次AFMInitializer.init(context, backgroundTaskHandler, imageHandler, logHandler)进行初始化。除context外，其他参数均可为空。
2. 创建PrinterMarkDownTextView来显示Markdown内容。
3. 创建MarkdownStyles来设置渲染样式。
4. 调用PrinterMarkDownTextView.init() 绑定MarkdownStyles和ElementClickEventCallback。此步骤必须执行，且MarkdownStyles不能为null。
5. 设置Markdown内容或直接调用startPrinting(content)开始打印。

AFMInitializer.init(context, null, null, null);
// 创建PrinterMarkDownTextView
PrinterMarkDownTextView markdownTextView = findViewById(R.id.markdown_view);

// 创建MarkdownStyles，或者也可以使用新的MarkdownStyles()创建自定义样式
MarkdownStyles styles = MarkdownStyles.getDefaultStyles();
// 设置样式示例
styles.linkStyle().icon("https://you_image_url");
styles.setTitleStyle(0, TitleStyle.create(1.5f).icon(https://you_image_url));// 设置一级标题样式

// 绑定MarkdownStyles和ElementClickEventCallback。
markdownTextView.init(styles, elementClickEventCallback);
// 设置Markdown内容或调用startPrinting(content)开始打印。
markdownTextView.setMarkdownText(markdown);

• 示例说明
  • MainActivity - Markdown正常模式示例。
  • PrinterActivity - 流式打印示例。
  • ListActivity - 流式打印列表示例。

HarmonyOS

合并 Markdown

• 在页面的 build() 方法中导入并组合 Markdown 组件。
• 通过 @Param content 参数绑定 Markdown 格式的文本内容。
• 在 Markdown 组件内部处理各种回调事件，以增强业务交互流程，例如 @Event onMarkdownAreaChange、@Event onMarkdownNodeClick 等。

import { Markdown, EMarkdownMode } from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  @Param content: string;
  private scroller: Scroller = new Scroller();

  build() {
      Scroll(this.scroller) {
        Markdown({
          content: this.content,
          mode: EMarkdownMode.Normal,
          onMarkdownAreaChange: () => {},
          onMarkdownNodeClick: data => {},
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
      .scrollable(ScrollDirection.Vertical)
      .margin(12)
  }
}

流式输出

• 通过将 @Param 的 mode 参数设置为 EMarkdownMode.Typing 来启用流式输出模式。
• 创建一个 MarkdownController 实例，并将其绑定到 @Param controller 参数上，以管理流式输出过程，例如 update()、pause()、resume() 等。
• 注意：MarkdownController 的控制方法，如 update()，只能在 @Event onMarkdownTypingReady 回调事件中可靠地执行。
• 注意：在流式输出模式下，@Param content 参数将被忽略。

import { 
  Markdown, EMarkdownMode, MarkdownController, ETypingMode,
} from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  private scroller: Scroller = new Scroller();
  private markdownController: MarkdownController = new MarkdownController();

  build() {
      Scroll(this.scroller) {
        Markdown({
          controller: this.markdownController,
          mode: EMarkdownMode.Typing,
          onMarkdownTypingReady: () => {
            this.markdownController.typing.update('Hello FluidMarkdown', ETypingMode.Begin);
          },
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
      .scrollable(ScrollDirection.Vertical)
      .margin(12)
  }
}

主题配置

• 创建一个新的 Engine 实例，并将其绑定到 @Param engine 参数上。
• 通过 Engine 内的 theme service 设置主题样式相关的 ITheme 属性。

import { Markdown, EMarkdownMode, BaseEngine } from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  @Param content: string;
  private scroller: Scroller = new Scroller();
  private engine: BaseEngine = new BaseEngine();

  aboutToAppear() {
    this.engine.theme!.theme!.document!.font!.fontColor = Color.Red;
  }
  
  build() {
      Scroll(this.scroller) {
        Markdown({
          engine: this.engine,
          content: this.content,
          mode: EMarkdownMode.Normal,
          onMarkdownAreaChange: () => {},
          onMarkdownNodeClick: data => {},
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
      .scrollable(ScrollDirection.Vertical)
      .margin(12)
  }
}

演示应用

构建并运行演示应用来体验 FluidMarkdown——尽情享受吧！

已知问题

• 表格中的可点击元素显示为纯文本，无法进行交互。
• 不支持表格单元格内的嵌套 HTML 标签。
• Android 平台上的表格可能会溢出其容器，且不支持水平滚动。
• HarmonyOS 平台上 LaTex 功能仍在开发中，暂不可用。
• 所需的最低 HarmonyOS API 版本为 15 或更高。

贡献

FluidMarkdown 团队欢迎个人或团队的贡献。更多信息请参阅文件 CONTRIBUTING。

许可证

所有源代码均采用 Apache 2.0 许可证授权。详情请参阅 LICENSE。

我们感谢以下开源项目：

• noties/Markwon
  • 许可证：Apache-2.0
• indragiek/CocoaMarkdown
  • 许可证：MIT 许可证
• commonmark/commonmark-spec
  • 许可证：MIT 许可证
• https://github.com/max-lfeng/iosMath/
  • 许可证：MIT 许可证
• https://github.com/mattt/Ono/
  • 许可证：MIT 许可证
• markdown-it
  • 许可证：MIT 许可证
• highlight.js
  • 许可证：BSD 3-Clause 许可证
• csstree
  • 许可证：MIT 许可证
• htmlparser2
  • 许可证：MIT 许可证

致谢与参考文献

• 所有为 Ant Markdown 组件贡献代码的开发者
• 感谢以下开源项目：
  • noties/Markwon
  • indragiek/CocoaMarkdown
  • commonmark/commonmark-spec
  • https://github.com/max-lfeng/iosMath/
  • https://github.com/mattt/Ono/
  • markdown-it
  • highlight.js
  • csstree
  • htmlparser2

FluidMarkdown 快速上手指南

FluidMarkdown 是一款专为 Android、iOS 和 HarmonyOS 开发者设计的开源库，旨在支持大语言模型（LLM）生成的 Markdown 内容在客户端进行流式渲染。它基于 CommonMark 解析库，支持核心 Markdown 语法及部分 HTML 标签，并提供高度可定制的样式和事件回调。

环境准备

系统要求

• iOS: 支持原生 iOS 开发环境。
• Android: 支持原生 Android 开发环境。
• HarmonyOS: API Version 15 或更高版本。

前置依赖

本项目源码开放，具体依赖管理请参考各平台的标准构建工具配置。底层依赖包括：

• CommonMark (解析核心)
• Markwon (Android 端基础)
• CocoaMarkdown / iosMath (iOS 端基础)

安装步骤

由于项目结构针对多平台划分，请根据目标平台克隆源码并集成：

git clone https://github.com/antgroup/FluidMarkdown.git
cd FluidMarkdown

注：详细的项目下载与运行指引请参阅项目根目录下的 INSTALL.md 文件。

目录结构参考

• iOS: AntMarkdown (解析模块), FluidMarkdown (流式组件)
• Android: fluid-markdown (流式组件), markwon-xxx (解析与样式实现)
• HarmonyOS: markdown (核心源码), playground (演示 Demo)

基本使用

1. iOS 使用示例

通过 AMXMarkdownTextView 实现流式输出。

// 1. 创建 TextView 实例
AMXMarkdownTextView* contentTextView = [[AMXMarkdownTextView alloc] initWithFrame_ant_mark:CGRectMake(0, 0, screenWidht - 20 * 2, 1)];

// 2. 获取默认样式配置并可自定义
AMXMarkdownStyleConfig* config = [AMXMarkdownStyleConfig defaultConfig];
config.codeBlockConfig.backgroundColor = [UIColor greenColor];
[[AMXRenderService shared] setMarkdownStyleWithId:config styleId:@"demo"];

// 3. 开始流式打印
[self.contentTextView startStreamingWithContent:@"testing data"];

// 4. 动态追加内容
[self.contentTextView addStreamContent:@"**append test data**"];

// 5. 结束时停止
[self.contentTextView stop];

处理内容大小变化（自动滚动到底部）：

-(void)onSizeChange:(CGSize)size
{
    // 调整视图高度
    [self.contentTextView setFrame:CGRectMake(0, 0, self.contentTextView.frame.size.width, size.height)];
    [self.containerView setContentSize:size];
    
    // 滚动到底部
    CGPoint bottomOffset = CGPointMake(0, self.containerView.contentSize.height - self.containerView.bounds.size.height);
    if (bottomOffset.y > 0) {
        [self.containerView setContentOffset:bottomOffset animated:NO];
    }
}

2. Android 使用示例

需先全局初始化，然后绑定样式并开始打印。

// 1. 全局初始化 (除 context 外其他参数可为 null)
AFMInitializer.init(context, null, null, null);

// 2. 创建视图
PrinterMarkDownTextView markdownTextView = findViewById(R.id.markdown_view);

// 3. 创建并配置样式
MarkdownStyles styles = MarkdownStyles.getDefaultStyles();
styles.linkStyle().icon("https://you_image_url");
styles.setTitleStyle(0, TitleStyle.create(1.5f).icon("https://you_image_url"));

// 4. 绑定样式和事件回调 (必须调用)
markdownTextView.init(styles, elementClickEventCallback);

// 5. 设置内容或直接开始流式打印
markdownTextView.setMarkdownText(markdown);
// 或者使用流式模式: markdownTextView.startPrinting(content);

3. HarmonyOS 使用示例

基于 ArkTS 和 @ComponentV2 规范。

普通模式渲染

import { Markdown, EMarkdownMode } from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  @Param content: string;
  private scroller: Scroller = new Scroller();

  build() {
      Scroll(this.scroller) {
        Markdown({
          content: this.content,
          mode: EMarkdownMode.Normal,
          onMarkdownAreaChange: () => {},
          onMarkdownNodeClick: data => {},
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
      .scrollable(ScrollDirection.Vertical)
      .margin(12)
  }
}

流式输出模式 (Typing Mode)

import { 
  Markdown, EMarkdownMode, MarkdownController, ETypingMode,
} from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  private scroller: Scroller = new Scroller();
  private markdownController: MarkdownController = new MarkdownController();

  build() {
      Scroll(this.scroller) {
        Markdown({
          controller: this.markdownController,
          mode: EMarkdownMode.Typing, // 开启流式模式
          onMarkdownTypingReady: () => {
            // 在此回调中执行更新操作
            this.markdownController.typing.update('Hello FluidMarkdown', ETypingMode.Begin);
          },
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
      .scrollable(ScrollDirection.Vertical)
      .margin(12)
  }
}

自定义主题

import { Markdown, EMarkdownMode, BaseEngine } from 'fluid-markdown';

@ComponentV2
export struct MyComponent {
  @Param content: string;
  private engine: BaseEngine = new BaseEngine();

  aboutToAppear() {
    // 通过 engine 修改主题样式
    this.engine.theme!.theme!.document!.font!.fontColor = Color.Red;
  }
  
  build() {
      Scroll(this.scroller) {
        Markdown({
          engine: this.engine,
          content: this.content,
          mode: EMarkdownMode.Normal,
        })
          .margin(12)
      }
      .width('100%')
      .height('100%')
  }
}