@chronoai/toolkit/data-render

将任意对象、数组或原始值递归渲染为带内联样式的嵌套 HTML 列表。提供独立工具函数和 Feature 封装两种用法。

需要将 HTML 渲染到页面？配合 @chronoai/toolkit/dom 使用。 需要先从 AI 输出解析出结构化数据？先用 @chronoai/toolkit/output-parser。

安装

已包含在 @chronoai/toolkit 中，无需单独安装。

import {
  renderToHtml,
  DataRenderFeature,
} from '@chronoai/toolkit/data-render';

为什么需要这个 toolkit？

AI 解析出的结构化数据（如 JSON 对象、列表）通常需要在页面上以人类可读的方式展示。手写递归渲染逻辑繁琐，且容易遗漏 HTML 转义或边界情况。

data-render 内置了对象、数组、原始类型、null、空值等所有情况的处理，同时自动完成 XSS 防注入的 HTML 转义，支持嵌套结构任意深度。搭配 DataRenderFeature 时，数据更新会通过 reactionFrame 自动触发重渲染，无需手写观察者逻辑。

快速开始

工具函数用法（不依赖引擎）

import { renderToHtml } from '@chronoai/toolkit/data-render';

const html = renderToHtml({ name: 'Alice', tags: ['admin', 'editor'] });

渲染结果（简化展示）：

<ul>
  <li><span>name</span>: <span>Alice</span></li>
  <li><span>tags</span>:
    <ol>
      <li><span>admin</span></li>
      <li><span>editor</span></li>
    </ol>
  </li>
</ul>

Feature 用法（引擎集成）

agent.use(DataRenderFeature, {
  source: 'ai-parsed',
  // target 默认为 'ai-parsed-html'
});

当 ai-parsed 时间轴写入新值时，ai-parsed-html 时间轴自动更新为对应的 HTML 字符串。

渲染规则

所有字符串值均经过 HTML 转义（&、<、>、"、'），防止 XSS 注入。

渲染选项

const html = renderToHtml(data, {
  arrayAs: 'ul',   // 数组使用 <ul>，默认 'ol'
  maxDepth: 5,     // 最大递归深度，默认 10
});

完整链路示例

从 AI 原始输出到结构化数据再到页面渲染的完整管道：

import { OutputParserFeature, stripFences, xmlTag, looseJson } from '@chronoai/toolkit/output-parser';
import { DataRenderFeature } from '@chronoai/toolkit/data-render';
import { DomMountFeature } from '@chronoai/toolkit/dom';

// 1. 解析：从 AI 响应中提取并解析 JSON
agent.use(OutputParserFeature, {
  source: 'ai-response',
  timeline: 'ai-parsed',
  pipeline: [
    stripFences(),
    looseJson(),
  ],
});

// 2. 渲染：将解析出的对象转换为 HTML 列表
agent.use(DataRenderFeature, {
  source: 'ai-parsed',         // 监听解析结果
  target: 'ai-rendered-html',  // 写入 HTML 字符串
  options: { arrayAs: 'ul' },
});

// 3. 挂载：将 HTML 渲染到页面
agent.use(DomMountFeature, {
  mounts: [
    { source: 'ai-rendered-html', target: '#output' },
  ],
});

类型导出

时间轴

外部时间轴

内部时间轴

配置参数

agent.use(DataRenderFeature, config) 的 config 支持以下参数：