VISALL 要点文本 (Text) 使用文档

简介

要点文本组件是VISALL数据可视化库中用于展示文本内容的图表类型，适用于显示结构化的文本内容，如标题和详细内容的组合。该组件能够灵活处理多条文本数据，支持自定义高度和宽度，并提供点击交互功能。

基本用法

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

// 创建要点文本图表
const chart = render(container, {
  layers: [
    {
      type: 'text',
      dataIndex: 0,
      encoding: {
        text: 'content', // 文本内容字段名
        title: 'title'   // 标题字段名
      }
    }
  ],
  data: [
    {
      values: [
        { title: '标题一', content: '这是第一条内容' },
        { title: '标题二', content: '这是第二条内容' },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.text	string	-	文本内容映射字段，必须提供一个字符串类型字段
encoding.title	string	-	标题映射字段，必须提供一个字符串类型字段
dataIndex	number	0	指定使用的数据集索引
maxHeight	number	520	文本容器的最大高度（像素）
width	number	570	文本容器的宽度（像素）
customEvent	function	-	自定义交互事件处理函数

数据要求

text字段要求为字符串类型
title字段要求为字符串类型
数据数量不限
提供准确的字段名映射

高级用法

1. 自定义容器尺寸

可以通过设置maxHeight和width参数来自定义文本容器的尺寸：

{
  type: 'text',
  encoding: {
    text: 'content',
    title: 'title'
  },
  maxHeight: 600,
  width: 800
}

2. 事件交互处理

通过customEvent参数可以自定义文本点击等交互事件的处理：

{
  type: 'text',
  encoding: {
    text: 'content',
    title: 'title'
  },
  customEvent: (event) => {
    const { type, data } = event;
    console.log('事件类型:', type);
    console.log('事件数据:', data);
    // 执行自定义操作
  }
}

潜规则与注意事项

主题样式自动继承：
- 文本组件会自动应用全局主题配置中的文本样式。
- 样式通过token?.dvText获取和应用。
数据转换机制：
- 组件内部会对原始数据进行转换，提取text和title字段。
- 转换通过transformData数组实现，保留了原始数据的顺序。
容器尺寸控制：
- maxHeight参数用于控制文本容器的最大高度，超出部分会显示滚动条。
- width参数用于控制文本容器的宽度，影响文本的换行和布局。
事件处理：
- 组件内部注册了'change:selected'事件，用于响应文本选择交互。
- 如果提供了customEvent函数，事件数据会通过此函数传递给外部。

实现原理

要点文本组件内部使用了ui.Text类进行渲染，主要包括以下步骤：

数据转换：将原始数据转换为指定格式
创建文本实例：使用ui.Text类创建文本渲染实例
注册事件：绑定交互事件处理函数
清理资源：在组件销毁时清空DOM并释放资源

类型兼容性问题

使用本组件时，需要注意以下类型兼容性问题：

text和title字段必须是字符串类型
customEvent函数需要接收特定格式的事件对象
确保数据对象包含指定的字段名

示例

基础要点文本

{
  type: 'text',
  encoding: {
    text: 'description',
    title: 'headline'
  }
}

自定义尺寸的要点文本

{
  type: 'text',
  encoding: {
    text: 'content',
    title: 'title'
  },
  maxHeight: 400,
  width: 600
}

带事件处理的要点文本

{
  type: 'text',
  encoding: {
    text: 'content',
    title: 'title'
  },
  customEvent: (event) => {
    if (event.type === 'change:selected') {
      // 处理选择事件
      console.log('选中项:', event.data);
    }
  }
}

常见问题解决

文本显示不全
- 检查maxHeight设置是否足够
- 检查容器宽度是否合适
事件未触发
- 确认customEvent函数格式是否正确
- 检查事件类型是否匹配
样式不符合预期
- 检查主题配置中的dvText设置
- 确认数据格式是否正确

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 自定义容器尺寸​

2. 事件交互处理​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础要点文本​

自定义尺寸的要点文本​

带事件处理的要点文本​

常见问题解决​

简介