T8叙述文本

# 叙事文本可视化技巧此技能提供了一个工作流程，用于使用 **T8 语法** 将数据转换为结构化叙述文本可视化 - 一种类似 Markdown 的声明性语言，用于使用语义实体注释创建数据叙述。 ## T8是什么 T8是AntV技术栈下专门针对基于洞察的叙事文本展示而设计的文本可视化解决方案。您无需手动构建 DOM 元素，而是编写简单的、人类可读的语法来描述您的数据叙述。 **主要特点：** * **LLM-Friendly** ：语法直观，可以通过人工智能模型轻松生成 * **声明性和可读性**：写出你想要的内容，而不是如何构建它 * **与框架无关**：可与 React、Vue 或 vanilla JavaScript 配合使用 * **标准化造型** ：默认专业外观 * **内置数据可视化**：迷你图表（饼图、折线图）是语法原生的 * **轻量级**：gzip 之前小于 20KB ## 工作流程要生成叙述性文本可视化，请按照下列步骤操作： ### 1\.了解要求分析用户的请求以确定： * 要分析的主题或数据 * 所需叙述的类型（报告、摘要、文章） * 需要强调的关键见解 * 任何特定的数据源或指标 ### 2\.生成 T8 语法内容遵循以下规范，使用 T8 语法创建叙述性文本。内容必须包括： * 正确的文档结构（标题、段落、列表） * 所有有意义的数据点的实体注释 * 实体的适当元数据（起源、评估等） ### 3\.生成前端代码创建 HTML、React 或 Vue 代码以根据用户首选框架呈现 T8 内容。 ### 4\.验证输出确保： *所有数据均来自真实来源 * 最小内容长度（800字或同等长度） * 贯穿全文的正确实体注释 * 清晰的结构和逻辑流程 ** ** ## T8 语法规范 T8 Syntax 是一种类似 Markdown 的语言，用于创建带有语义实体注释的叙述性文本。它使数据分析报告更具表现力和视觉吸引力。 ### 文档结构 #### 标题（6 级）使用标准 Markdown 标题语法： # 1 级标题（主标题） ## 2 级标题（部分） ### 3 级标题（小节） #### 4 级标题 ##### 5 级标题 ###### 6 级标题 **规则：** * 每个标题必须独占一行 * ‘#’符号后加一个空格 * 标题在渲染输出中创建视觉层次结构 #### 段落常规文本段落由空行分隔：这是第一段，有一些内容。这是第二段，以空行分隔。 **规则：** * 段落可以跨多行 * 使用空行来分隔不同的段落 * 段落内的文字自然流畅 #### 列表 T8 语法支持无序列表和有序列表。 **无序列表：** - 第一项 - 第二项 - 第三项 **有序列表：** 1.第一步 2.第二步 3.第三步 **规则：** * 每个列表项必须独占一行 * 在项目符号（`-`、`*`）或数字后添加一个空格 * 列表可以包含实体和文本格式 ### 文本格式 T8 语法支持使用 Markdown 语法的内联文本格式： **粗体文本：** `这是突出的**粗体文本**。` **斜体文本：** `这是*斜体文本*，用于强调。` **下划线文本：** `为了重要性，这是__下划线文本__。` **链接：** `访问[我们的网站](https://example.com) 了解更多信息。` **规则：** * 格式标记必须平衡（开始和结束） * 格式化可以与实体结合 * 链接使用“[text](URL)”语法，其中 URL 以“http://”、“https://”或“/”开头 ### 实体注释语法 T8 Syntax 的核心特征是**实体标注** \——用语义和元数据标记特定的数据点。 #### 基本实体语法 [显示文本](实体类型) * `displayText`: 向读者显示的文本 * `entityType`: 该实体的语义类型 **示例：** 本季度[销售收入](metric_name) 达到[150 万日元](metric_value)。 #### 具有元数据的实体 [displayText](entityType, key1=value1, key2=value2, key3="字符串值") **元数据规则：** * 多个元数据字段用逗号分隔 * 数字和布尔值：直接写入（例如，`origin=1500000`、`active=true`） * 字符串：用双引号括起来（例如`unit =“元”`，`region =“Asia”`） **示例：** 与去年相比，收入增长了 [15.3%]（ratio_value，origin=0.153，评估=“积极”）。 ### 实体类型参考使用这些实体类型来注释不同类型的数据：实体类型 |描述 |何时使用 |示例 ---|---|---|--- `度量名称` |指标或 KPI 的名称 |当提及您正在测量的内容时 | “收入”、“用户数”、“市场份额” `度量值` |主要指标值|报告的主要数字/值 | “150万日元”、“5万用户”、“250台” `其他指标值` |次要或支持指标值 |提供上下文的其他指标 | “平均订单价值：120 美元” `delta_value` |绝对变化/差异|当显示期间之间的数字变化时 | “+1,200 单位”、“-5 万美元”、“增加 500 单位” `比率值` |百分比变化/率 |当显示百分比变化时 | “+15.3%”、“-5.2%”、“增长 23%” `贡献率` |贡献百分比 |当显示某物贡献的百分比时 | “占45%”、“占总数的30%” `趋势描述` |趋势描述|描述变化的方向/模式 | “稳步上升”、“下降趋势”、“稳定” `暗淡值` |尺寸值/类别 |地理、分类或细分数据 | “北美”、“企业部门”、“第三季度” `时间描述` |时间段或时间戳 |当指定某事发生的时间时 | “2024 年第三季度”、“1 月至 3 月”、“2023 财年” `比例` |比例或比例|当表达整体的部分时 | “五分之三”、“60% 的客户” `等级` |排名或位置 |当指示列表中的顺序或位置时 | “排名第一”、“前三名”、“第五名” `差异` |比较差异|当突出显示两个项目之间的差异时 | “5 万美元的差异”、“200 个单位的差距” `异常` |不寻常或意想不到的价值 |当指出异常值或异常时 | “异常峰值”、“意外下降” `协会` |关系或相关性 |当描述指标之间的联系时| “强相关”、“相关”、“相关” `分布` |数据分布模式|当描述数据如何传播时 | “均匀分布”、“集中”、“分散” `季节性` |季节性模式或趋势|当描述重复出现的季节性模式时| “季节性高峰”、“节假日期间”、“Q4激增” ### 常见元数据字段添加这些可选字段以提供更丰富的数据上下文： #### `起源`（数字）显示文本后面的原始数值。 **示例：** * `[150 万日元](metric_value, origin=1500000)` * `[23.7%]（比率值，原点=0.237）` * `[5.2K 用户](metric_value, origin=5200)` * `[4 中的 3]（比例，原点=0.75）` **为什么使用它：** 实现数据可视化、排序和计算 #### `评估`（字符串）评估变化是积极的、消极的还是中性的。 **有效值：** `"正"`、`"负"`、`"等于"`、`"中性"` **示例：** * `[增加 15%]（ratio_value，评估=“积极”）` * `[下降 8%](ratio_value, 评估=“负”)` * `[保持平稳](trend_desc,评估=“等于”)` **为什么使用它：** 启用好/坏趋势的视觉指示器（颜色、图标） #### `单位`（字符串）值的测量单位。 **示例：** * `[¥1,500,000](metric_value, 单位=“元”, origin=1500000)` * `[150](metric_value, 单位=“单位”)` #### `细节`（任意）用于图表渲染的附加上下文或细分数据。对于某些实体类型是必需的。 **这些实体类型必需：** * `rank`: 代表排名数据的数字数组 * 示例：`[表现最佳](排名，详细信息=[5, 8, 12, 15, 20])` * `difference`：显示比较值的数字数组 * 示例: `[差距缩小](差异, 细节=[100, 80, 60, 40])` * `anomaly`：突出显示异常值的数字数组 * 示例：`[异常峰值](异常，详细信息=[10, 12, 11, 45, 13])` * `association`：相关数据的 {x, y} 对象数组 * 示例：`[强相关性](关联，详细信息=[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}])` * `distribution`：显示数据分布的数字数组 * 示例: `[分布不均匀](分布, 详细=[5, 15, 45, 25, 10])` * `seasonality`：具有数据数组和可选范围的对象 * 示例：`[第四季度峰值](季节性，详细信息={"data":[10,12,15,30],"range":[0,40]})` **其他类型可选：** * `[稳定增长](trend_desc,detail=[100, 120, 145, 180, 210])` ** ** ## 数据要求 **重要**：所有数据必须来自公开的真实来源： * 官方公告/财务报告 * 权威媒体（路透社、彭博社、TechCrunch等） * 行业研究机构（IDC、Canalys、Counterpoint Research等） * **切勿使用虚构的、人工智能猜测的或模拟的数据** * 使用具体数字（例如“1.46 亿单位”、“7058 单位”），而不是模糊的近似值 ** ** ## 完整的 T8 语法示例 #2024年智能手机市场分析 ## 市场概况 [2024](time_desc) 全球[智能手机出货量](metric_name) 达到 [12 亿部](metric_value, origin=1200000000)，同比[小幅下降 2.1%](ratio_value, origin=-0.021,assessment=1200000000)。 **高端细分市场**（超过 800 美元的设备）显示出*显着的*[弹性]（trend_desc，评估=“积极”），增长了 [5.8%]（ratio_value，origin=0.058，评估=“积极”）。 [平均售价](other_metric_value) 为 [$420](metric_value, origin=420, unit="USD")。 ## 主要发现 1. [亚太地区](dim_value) 仍然是__最大市场__ 2. [高级设备](dim_value) 显示**强劲增长** 3. 预算部分面临*逆风* ## 地区分布 ### 亚太地区 [亚太地区](dim_value) 仍然是最大的市场，出货量为 [6.8 亿台](metric_value, origin=680000000)，尽管这意味着较上一年[下降了 1.8 亿台](delta_value, origin=-180000000,assess=“负”)。主要市场： - [中国](dim_value)：[3.2 亿单位](metric_value, origin=320000000) - 下降 [8.5%](ratio_value, origin=-0.085,assess="need")，[排名第一](rank,detail=[320, 180, 90, 65, 45])，占全球的 [47%](contribute_ratio,区域销售的起源=0.47，评估=“积极”） - [印度](dim_value)：[180M 单位](metric_value，origin=180000000) - 上涨 [12.3%](ratio_value，origin=0.123，评估=“正”)，[排名第二](rank，detail=[320, 180, 90, 65, 45]) - [东南亚](dim_value)：[180M 单位](metric_value, origin=180000000) - [稳定](trend_desc,assessment="equal") 有关详细方法，请访问[我们的研究页面](https://example.com/methodology)。 ** ** ## 在 HTML、React 和 Vue 中使用 T8 ### 在 HTML 中使用（通过 CDN） <头> <元字符集=“UTF-8”> T8叙述文本 <正文>

<脚本> // T8 可用作全局变量 const { 文本 } = window.T8; // 初始化T8实例 const text = new Text(document.getElementById('容器')); // 使用 T8 语法渲染叙述性文本常量叙述文本 = ` # 销售报告本季度，[预订量](metric_name) 高于平常。它们是 [¥348k](metric_value, origin=348.12)。与上季度同期相比，[预订量](metric_name) 增加了 [¥180.3k](delta_value,assessment=“positive”)。 `; text.theme('light').render(narrativeText); **安装：** npm 安装@antv/t8 # 或纱线添加@antv/t8 ### 在 React 中使用从 '@antv/t8' 导入 { Text }；从 'react' 导入 { useEffect, useRef }; 函数 T8Component() { const containerRef = useRef(null); 使用效果（（）=> { if (!containerRef.current) 返回； // 初始化T8实例 const text = new Text(containerRef.current); // 使用 T8 语法渲染叙述性文本常量叙述文本 = ` # 销售报告本季度，[预订量](metric_name) 高于平常。它们是 [¥348k](metric_value, origin=348.12)。与上季度同期相比，[预订量](metric_name) 增加了 [¥180.3k](delta_value,assessment=“positive”)。 `; text.theme('light').render(narrativeText); // 卸载时清理返回（）=> { 文本.unmount(); }; }, []); 返回

; } 导出默认T8Component； ### 在 Vue 3 中使用 <模板>

<脚本设置lang =“ts”> 从 '@antv/t8' 导入 { Text }；从 'vue' 导入 { ref, onMounted, onBeforeUnmount }; const containerRef = ref(); 让 textInstance: Text |空=空；已安装（（）=> { if (!containerRef.value) 返回； // 初始化T8实例 textInstance = new Text(containerRef.value); // 使用 T8 语法渲染叙述性文本常量叙述文本 = ` # 销售报告本季度，[预订量](metric_name) 高于平常。它们是 [¥348k](metric_value, origin=348.12)。与上季度同期相比，[预订量](metric_name) 增加了 [¥180.3k](delta_value,assessment=“positive”)。 `; textInstance.theme('light').render(narrativeText); }); onBeforeUnmount(() => { if (textInstance) { textInstance.unmount(); } }); ### 在 Vue 2 中使用 <模板>

<脚本> 从 '@antv/t8' 导入 { Text }；导出默认值{ 名称：'T8组件'，数据（）{ 返回{ 文本实例：空， }; }, 安装（）{ // 初始化T8实例 this.textInstance = new Text(this.$refs.container); // 使用 T8 语法渲染叙述性文本常量叙述文本 = ` # 销售报告本季度，[预订量](metric_name) 高于平常。它们是 [¥348k](metric_value, origin=348.12)。与上季度同期相比，[预订量](metric_name) 增加了 [¥180.3k](delta_value,assessment=“positive”)。 `; this.textInstance.theme('light').render(narrativeText); }, 之前销毁（）{ if (this.textInstance) { this.textInstance.unmount(); } }, }; ** ** ## 写作指南和最佳实践 ### 内容要求 1. **最小长度：** 不少于800字（根据数据复杂程度调整） 2. **结构：** 层次清晰，各部分之间具有逻辑流程 3. **分析：** 不要只列出数字 - 解释它们的意义和背景 4. **语气：**自然、流畅、客观、专业 5. **实体用法：** 注释所有有意义的数据点 - 指标、值、趋势、时间、变化、百分比 ### 实体注释最佳实践 1. **全面：** 标记所有定量数据，而不仅仅是主要数字 2. **使用适当的类型：** 选择最能描述语义的实体类型 3. **添加元数据：** 包括 `origin`、`assessment` 和其他适用的相关字段 4. **自然流动：** 实体应该无缝地融入可读的散文中 ### 注释什么 ✅ **请注释：** * 所有数值（收入、计数、测量值） * 所有百分比（变化、贡献、比例） * 指标名称和 KPI * 时间段 * 地理区域和类别 * 趋势描述 * 比较与变化 ❌ **不要注释：** * 没有具体数据含义的通用文本 * 连接短语和过渡 * 不代表可测量概念的上下文 ** ** ## 输出格式为用户生成 T8 语法内容时： 1.直接输出T8 Syntax内容，不包裹代码块 2. 根据用户偏好提供前端代码（HTML/React/Vue） 3. 确保所有实体都使用适当的元数据进行了正确注释 4. 验证内容是否满足最小长度和质量要求渲染的输出提供： * 丰富的数据实体语义标记 * 交互式实体突出显示 * 清晰的视觉层次 * 专业的报告风格格式 * 适用于所有设备的响应式设计 ** ** ## 参考链接 * T8 GitHub 存储库： * T8 文档： * T8 语法参考：

叙事文本可视化

包含技能