VISALL 概要文本 (Summary Text) 使用文档

简介

概要文本组件是VISALL数据可视化库中的文本类图表，用于展示单一数据点的文本或数值信息。该组件能够自动识别文本类型（普通文本或数值），并根据不同类型应用相应的样式与格式化规则，适用于大屏展示、数据看板等场景中的关键指标展示。

基本用法

import { render } from 'path/to/bundle.esm.min.js';

// 创建概要文本
const chart = render(container, {
  layers: [
    {
      type: 'summaryText',
      dataIndex: 0,
      encoding: {
        x: '指标值' // 要展示的字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 指标值: '销售额达成率96.5%' }, // 普通文本
        // 或
        { 指标值: 96.5 } // 数值（将自动格式化并添加样式）
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	要展示的字段名，必须提供一个字符串或数值类型字段
dataIndex	number	0	指定使用的数据集索引

数据要求

• 数据必须是对象数组格式
• 数组长度必须为1（只显示单一数据点）
• 字段名必须与encoding中指定的字段名匹配
• 字段值可以是字符串或数值

高级用法

1. 展示带单位的数值

当需要展示带单位的数值时，可以通过数据元信息设置单位：

{
  type: 'summaryText',
  encoding: {
    x: '销售额'
  },
  data: [
    {
      metadata: {
        销售额: {
          unit: '万元'
        }
      },
      values: [
        { 销售额: 1234.56 }
      ]
    }
  ]
}

2. 展示多行文本内容

当需要展示多行文本内容时，可以使用文本字符串：

{
  type: 'summaryText',
  encoding: {
    x: '描述'
  },
  data: [
    {
      values: [
        { 描述: '这是一段较长的文本描述\n可以包含多行内容\n适合展示概要信息' }
      ]
    }
  ]
}

潜规则与注意事项

1. 文本类型自动识别：

   • 组件会自动识别字段值是普通文本还是数值。
   • 使用Number.isNaN(+text)进行判断，如果不是NaN则认为是数值类型。
   • 不同类型会应用不同的样式与格式化规则。

2. 数值格式化：

   • 数值类型会自动进行格式化，支持单位显示。
   • 格式化通过hook.formatDataNumberValue实现，支持自动单位换算。
   • 数值展示使用较大字号，单位展示使用较小字号。

3. 字体设置：

   • 普通文本使用系统默认字体，由presetOption.textStyle.fontFamily定义。
   • 数值文本使用特定字体THSJinRongTi-Regular，固定在代码中。

4. 自适应布局：

   • 数值文本会根据容器宽度自动调整字体大小。
   • 字号计算公式：Math.max(chartViewRect.width / 240, 1) * baseSize
   • 数值文本使用flex布局，确保单位正确对齐。

5. 普通文本滚动：

   • 普通文本超出容器时会显示滚动条。
   • 通过添加styles['hover-scrollbar']类实现。

实现原理

概要文本组件内部实现较为简单，主要步骤包括：

1. 获取数据中的第一个数据点的目标字段值
2. 判断字段值是文本还是数值
3. 根据类型选择不同的渲染方式：
   • 文本类型：直接显示，支持滚动
   • 数值类型：格式化后显示，带单位且有特定样式

示例

展示普通文本

{
  type: 'summaryText',
  encoding: {
    x: '描述'
  },
  data: [
    {
      values: [
        { 描述: '本季度销售业绩良好，同比增长15%' }
      ]
    }
  ]
}

展示数值

{
  type: 'summaryText',
  encoding: {
    x: '同比增长'
  },
  data: [
    {
      metadata: {
        同比增长: {
          unit: '%'
        }
      },
      values: [
        { 同比增长: 15.8 }
      ]
    }
  ]
}

常见问题解决

1. 文本不显示

   • 检查数据是否正确提供
   • 确认数据数组长度为1
   • 验证字段名是否与encoding.x匹配

2. 数值格式化不符合预期

   • 检查数据元信息中的单位设置
   • 确认数值能够正确被转换（非NaN）

3. 字体显示异常

   • 确认系统是否安装了所需字体
   • 对于数值展示，可能需要确保THSJinRongTi-Regular字体可用