鸿蒙5莓创横向折线与柱状图tooltips属性详解

大家好，欢迎回来鸿蒙5莓创图表组件的专场，我们这一期来讲解McLineBarChart组合图中非常重要的tooltip（提示框）属性的详细用法。

一、tooltip基础介绍

tooltip是图表中非常重要的交互元素，当用户悬停在数据点上时，会显示该点的详细信息。莓创图表的tooltip功能丰富，支持高度自定义，下面我们逐一讲解每个属性的用法。

二、tooltip属性详解

1. show属性

作用：控制是否显示提示层 类型：Boolean 默认值：true 可选值：true（显示）、false（隐藏） 场景：当需要完全禁用提示功能时设置为false

@State tooltipOption: Options = new Options({
  tooltip: {
    show: false // 完全禁用提示框
  },
  // 其他配置...
})

2. padding属性

作用：设置提示框内部边距 类型：Number 默认值：10 场景：当提示框内容较多需要更多空间时增加此值

@State tooltipOption: Options = new Options({
  tooltip: {
    padding: 15 // 增加内边距
  },
  // 其他配置...
})

3. backgroundColor属性

作用：设置提示框背景颜色 类型：String 默认值：'rgba(0,0,0,0.7)' 场景：需要自定义提示框背景色以适应不同主题

@State tooltipOption: Options = new Options({
  tooltip: {
    backgroundColor: 'rgba(255,255,255,0.9)' // 白色半透明背景
  },
  // 其他配置...
})

4. borderWidth属性

作用：设置提示框边框宽度 类型：Number 默认值：0 场景：需要突出提示框边界时使用

@State tooltipOption: Options = new Options({
  tooltip: {
    borderWidth: 2 // 2像素边框
  },
  // 其他配置...
})

5. borderColor属性

作用：设置提示框边框颜色 类型：String 默认值：'rgba(0,0,0,0.7)' 场景：配合borderWidth使用，自定义边框颜色

@State tooltipOption: Options = new Options({
  tooltip: {
    borderWidth: 1,
    borderColor: '#296DFF' // 蓝色边框
  },
  // 其他配置...
})

6. axisPointer属性（指示线配置）

axisPointer是tooltip中非常重要的子属性，用于配置指示线的样式和行为。

6.1 type属性

作用：设置指示线类型 类型：String 默认值：'line' 可选值：'line'（直线指示器）、'shadow'（阴影指示器） 场景：需要不同视觉效果的指示器

@State tooltipOption: Options = new Options({
  tooltip: {
    axisPointer: {
      type: 'shadow' // 使用阴影指示器
    }
  },
  // 其他配置...
})

6.2 lineStyle属性

作用：设置直线指示器的样式

子属性：

• width：线宽，默认1
• type：线型，默认'solid'（可选：'solid'、'dashed'、'dotted'）
• color：线颜色，默认'#DDE2EB'

@State tooltipOption: Options = new Options({
  tooltip: {
    axisPointer: {
      type: 'line',
      lineStyle: {
        width: 2,
        type: 'dashed',
        color: '#FF0000'
      }
    }
  },
  // 其他配置...
})

6.3 shadowStyle属性

作用：设置阴影指示器的样式

子属性：

• color：阴影颜色，默认'rgba(150,150,150,0.2)'
• borderWidth：边框宽度，默认0
• borderColor：边框颜色，默认'rgba(150,150,150,0.2)'

@State tooltipOption: Options = new Options({
  tooltip: {
    axisPointer: {
      type: 'shadow',
      shadowStyle: {
        color: 'rgba(0,0,255,0.2)',
        borderWidth: 1,
        borderColor: 'rgba(0,0,255,0.5)'
      }
    }
  },
  // 其他配置...
})

7. textStyle属性（文本样式）

作用：设置提示框内文本的样式

子属性：

• color：文字颜色，默认'#fff'
• fontWeight：字体粗细，默认'normal'（可选：'normal'、'bold'等）
• fontFamily：字体，默认'sans-serif'
• fontSize：字体大小，默认14

@State tooltipOption: Options = new Options({
  tooltip: {
    textStyle: {
      color: '#333',
      fontWeight: 'bold',
      fontFamily: 'Arial',
      fontSize: 16
    }
  },
  // 其他配置...
})

8. animationCurve属性

作用：设置提示框动画曲线 类型：String 默认值：'easeOutCubic' 可选值：CSS支持的动画曲线 场景：需要自定义提示框出现/消失的动画效果

@State tooltipOption: Options = new Options({
  tooltip: {
    animationCurve: 'easeInOutBack' // 弹性动画
  },
  // 其他配置...
})

9. animationFrame属性

作用：设置提示框动画时间（毫秒） 类型：Number 默认值：0（无动画） 场景：需要控制提示框动画速度

@State tooltipOption: Options = new Options({
  tooltip: {
    animationFrame: 300 // 300毫秒动画
  },
  // 其他配置...
})

三、综合应用案例

下面是一个完整的tooltip配置案例，展示了如何综合使用多个属性：

import { McLineBarChart, Options } from '@mcui/mccharts'

@Entry
@Component
struct Index {
  @State tooltipOption: Options = new Options({
    title: {
      show: true,
      text: '综合tooltip配置示例'
    },
    xAxis: {
      data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
    },
    yAxis: {
      name: '数值'
    },
    tooltip: {
      show: true,
      padding: 12,
      backgroundColor: 'rgba(255,255,255,0.95)',
      borderWidth: 1,
      borderColor: '#296DFF',
      axisPointer: {
        type: 'shadow',
        shadowStyle: {
          color: 'rgba(41,109,255,0.1)',
          borderWidth: 0
        }
      },
      textStyle: {
        color: '#333',
        fontWeight: 'bold',
        fontSize: 14
      },
      animationCurve: 'easeOutQuart',
      animationFrame: 200
    },
    series: [
      {
        name: '销量',
        data: [1500, 1700, 1400, 2000, 1400, 1700, 1500],
        type: 'bar'
      },
      {
        name: '访问量',
        data: [1000, 1200, 900, 1500, 900, 1200, 1000],
        type: 'line'
      }
    ]
  })

  build() {
    Row() {
      McLineBarChart({ options: this.tooltipOption })
    }
    .height('50%')
  }
}

四、实际应用场景

场景1：深色主题适配

在深色主题应用中，我们需要调整tooltip的配色：

tooltip: {
  backgroundColor: 'rgba(30,30,30,0.9)',
  borderColor: '#555',
  textStyle: {
    color: '#EEE'
  },
  axisPointer: {
    lineStyle: {
      color: '#666'
    }
  }
}

场景2：高对比度模式

为视力障碍用户提供高对比度提示：

tooltip: {
  backgroundColor: '#FFF',
  borderWidth: 2,
  borderColor: '#000',
  textStyle: {
    color: '#000',
    fontSize: 16,
    fontWeight: 'bold'
  }
}

场景3：移动端优化

在移动设备上增大提示框和字体：

tooltip: {
  padding: 15,
  textStyle: {
    fontSize: 16
  },
  axisPointer: {
    lineStyle: {
      width: 2
    }
  }
}

好，这期讲到这里就结束了，希望大家通过这篇文章能够全面掌握莓创图表组合图中tooltip属性的使用方法。合理配置tooltip可以大大提升图表的交互体验和数据展示效果。如果在实际使用中遇到任何问题，欢迎在评论区留言讨论。下期我们将讲解图表的其他高级功能，敬请期待！