自定义标签

使用 Vue 组件自定义图表标签的样式和内容。

💡 快速了解

• 默认标签已经很美观，大多数情况下无需自定义
• 需要特殊样式时，创建一个 Vue 组件即可
• 支持传递任意自定义属性

默认标签

不做任何配置，标签已经很美观：

<template>
  <RayBar :option="chartOption" />
</template>

<script setup>
import { RayBar } from 'raychart'

const chartOption = {
  series: [{
    data: [120, 200, 150],
    label: {
      show: true,
      fontSize: 14,
      color: '#fff'
    }
  }],
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}
</script>

✨ 自动配置

默认标签已包含：

• ✅ 美观样式
• ✅ 阴影效果
• ✅ 响应式字体

创建自定义标签

1. 创建组件

创建一个 Vue 组件，接收 LabelData props：

<!-- CustomLabel.vue -->
<template>
  <div :style="labelStyle">
    {{ text }}
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import type { LabelData } from 'raychart'

const props = defineProps<LabelData>()

const labelStyle = computed(() => ({
  fontSize: `${props.style.fontSize || 14}px`,
  color: props.style.color || '#fff',
  backgroundColor: props.style.backgroundColor || 'rgba(0, 0, 0, 0.8)',
  padding: '6px 10px',
  borderRadius: '6px',
  pointerEvents: 'none' as const
}))
</script>

⚠️ 必须设置

pointerEvents: 'none' 是必须的，否则会阻挡鼠标事件。

2. 使用组件

通过 label-component prop 传入：

<template>
  <RayBar
    :option="chartOption"
    :label-component="CustomLabel"
  />
</template>

<script setup>
import { RayBar } from 'raychart'
import CustomLabel from './CustomLabel.vue'

const chartOption = {
  series: [{
    data: [120, 200, 150],
    label: { show: true }
  }],
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}
</script>

使用自定义属性

传递属性

在 label 配置中添加任意属性：

const chartOption = {
  series: [{
    data: [120, 200, 150],
    label: {
      show: true,
      fontSize: 14,
      color: '#fff',
      // 自定义属性
      badge: '🏆',
      showValue: true
    }
  }]
}

在组件中使用

<template>
  <div class="label">
    <span v-if="style.badge">{{ style.badge }}</span>
    <span>{{ text }}</span>
    <span v-if="style.showValue">{{ value }}</span>
  </div>
</template>

<script setup>
import type { LabelData } from 'raychart'

const props = defineProps<LabelData>()
// props.style.badge
// props.style.showValue
</script>

可用数据

标签组件可以访问这些数据：

属性	说明	示例
text	格式化后的文本	"120"
value	原始数据值	120
name	数据名称	"A"
seriesName	系列名称	"销售额"
dataIndex	数据索引	0
style	样式配置	{ fontSize: 14, ... }

📋 完整类型定义

interface LabelData {
  text: string
  value: any
  name?: string
  seriesName?: string
  dataIndex: number
  data: any
  style: {
    fontSize?: number
    color?: string
    backgroundColor?: string
    padding?: number
    borderRadius?: number
    fontWeight?: string | number
    fontFamily?: string
    [key: string]: any  // 自定义属性
  }
}

动态切换

可以动态切换标签组件：

<template>
  <div>
    <button @click="currentLabel = undefined">默认</button>
    <button @click="currentLabel = CustomLabel">自定义</button>
    
    <RayBar
      :option="chartOption"
      :label-component="currentLabel"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import CustomLabel from './CustomLabel.vue'

const currentLabel = ref()
</script>

完整示例

一个带徽章和数值的标签：

<!-- CustomLabel.vue -->
<template>
  <div class="custom-label" :style="labelStyle">
    <span v-if="style.badge" class="badge">{{ style.badge }}</span>
    <span>{{ text }}</span>
    <span v-if="style.showValue" class="value">{{ value }}</span>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import type { LabelData } from 'raychart'

const props = defineProps<LabelData>()

const labelStyle = computed(() => ({
  display: 'flex',
  alignItems: 'center',
  gap: '6px',
  fontSize: `${props.style.fontSize || 14}px`,
  color: props.style.color || '#fff',
  backgroundColor: props.style.backgroundColor || 'rgba(0, 0, 0, 0.8)',
  padding: '6px 10px',
  borderRadius: '6px',
  fontWeight: 'bold',
  boxShadow: '0 2px 8px rgba(0, 0, 0, 0.2)',
  pointerEvents: 'none' as const
}))
</script>

<style scoped>
.custom-label {
  animation: fadeIn 0.3s ease-in-out;
}

.badge {
  font-size: 1.1em;
}

.value {
  opacity: 0.9;
}

@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(-5px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
</style>

使用：

<template>
  <RayBar
    :option="chartOption"
    :label-component="CustomLabel"
  />
</template>

<script setup>
import { RayBar } from 'raychart'
import CustomLabel from './CustomLabel.vue'

const chartOption = {
  xAxis3D: {
    data: ['周一', '周二', '周三', '周四', '周五']
  },
  series: [{
    data: [120, 200, 150, 80, 170],
    label: {
      show: true,
      fontSize: 14,
      color: '#fff',
      position: 'top',
      // 自定义属性
      badge: '🏆',
      showValue: true
    }
  }]
}
</script>

常见问题

标签不显示？

检查这几点：

1. ✅ label.show 设置为 true
2. ✅ 组件设置了 pointerEvents: 'none'
3. ✅ 样式中有明确的颜色和背景色

如何调整位置？

通过 label 配置：

label: {
  show: true,
  position: 'top',   // top, bottom, left, right, inside, outside, center, insideTop 等
  distance: 0.5      // 距对象的偏移距离
}

性能问题？

每个数据点创建一个 Vue 实例，大数据量时：

1. 简化标签组件逻辑
2. 减少动画效果
3. 考虑只显示部分标签

详见 性能优化。

下一步

• 📊 图表配置 - 更多配置选项
• 💡 材质系统 - 自定义材质
• ⚡ 性能优化 - 大数据优化