Vega-Lite图表如何添加支持长文本的彩色说明文本框

核心思路是放弃用原生图例承载折线说明的方案，新增独立的自定义标记层绘制带颜色标识的长文本注释，完全绕开原生图例的文本长度、命名规则限制。

具体操作步骤 #

• 第一步：隐藏两条折线的原生图例条目
  给两个折线图层的color编码添加legend: null配置，保留散点图原有图例的同时，避免折线的短文本条目出现在默认图例中。
• 第二步：新增自定义注释图层
  在原有layer数组末尾追加独立的注释层，用静态数据存储两条折线的对应颜色、长描述文本、摆放位置，通过「彩色短横线+长文本」的组合实现和参考效果一致的说明框，文本长度无任何限制，支持换行、自定义样式。
• 第三步：微调样式匹配需求
  可根据设计要求调整注释位置、文本大小、是否添加白底边框、色条长度等参数。

核心修改代码示例 #

1. 折线层配置修改（两个line层都要改） #

// benchmark折线层修改后
{
  data: {name: 'benchmark'},
  mark: {type: 'line'},
  encoding: {
    x: {field: 'constructionYear', type: 'temporal', timeUnit: 'year', axis: {title: null}},
    y: {field: 'consumption_perm2', type: 'quantitative', axis: {title: null}},
    // 新增legend: null，隐藏该层在原生图例的条目
    color: {field: 'typ', type: 'nominal', scale: customScale, legend: null},
  }
},
// demand折线层做相同修改
{
  data: {name: 'demand'},
  mark: {type: 'line'},
  encoding: {
    x: {field: 'constructionYear', type: 'temporal', timeUnit: 'year', axis: {title: null}},
    y: {field: 'consumption_perm2', type: 'quantitative', axis: {title: null}},
    color: {field: 'typ', type: 'nominal', scale: customScale, legend: null},
  },
}

2. 新增自定义注释层（放在layer数组最后） #

{
  data: {
    values: [
      {
        xPos: 1970, // 注释x轴位置，根据需求调整
        yPos: 320, // 注释y轴位置，根据需求调整
        lineColor: "#e63946", // 替换为benchmark折线的实际对应颜色
        desc: "基准能耗线：对应德国节能法规EnEV规定的不同年代建筑能耗基准值，数值为同年代同类建筑的平均能耗水平"
      },
      {
        xPos: 1970,
        yPos: 295, // 和上一条注释错开位置，避免重叠
        lineColor: "#1d3557", // 替换为demand折线的实际对应颜色
        desc: "理论需求线：对应建筑按照设计参数计算的理论能耗需求值，未考虑实际使用中的行为能耗、设备损耗等影响因素"
      }
    ]
  },
  layer: [
    // 绘制文本前的彩色标识短横线
    {
      mark: {type: "rule", strokeWidth: 2, xOffset: -35},
      encoding: {
        x: {field: "xPos", type: "temporal", timeUnit: "year", scale: {"domain": [1880,2022]}, axis: null},
        x2: {datum: 1973}, // 控制短横线长度
        y: {field: "yPos", type: "quantitative", scale: {"domain": [0, 350]}, axis: null},
        color: {field: "lineColor", scale: null}
      }
    },
    // 绘制长文本说明，可配置白底边框
    {
      mark: {
        type: "text", 
        align: "left", 
        fontSize: 12,
        fill: "white", // 文本框底色
        stroke: "#ccc", // 文本框边框色
        strokeWidth: 1,
        padding: 6, // 文本内边距
        radius: 3, // 文本框圆角
        lineHeight: 18
      },
      encoding: {
        x: {field: "xPos", type: "temporal", timeUnit: "year", scale: {"domain": [1880,2022]}, axis: null},
        y: {field: "yPos", type: "quantitative", scale: {"domain": [0, 350]}, axis: null},
        text: {field: "desc"},
        color: {field: "lineColor", scale: null}
      }
    }
  ]
}

可调参数说明 #

• 注释位置：修改xPos、yPos数值即可移动注释块，比如要放在左上角可将xPos设为1885、yPos设为340。
• 文本样式：可通过fontSize、fontWeight、padding等参数调整文本大小、文本框边距。
• 换行支持：需要多行文本时直接在desc字符串中插入\n即可自动换行，无长度限制。
• 色条样式：修改strokeWidth、x2的datum值、xOffset数值可调整彩色标识线的粗细、长度、和文本的间距。

内容的提问来源于stack exchange，提问作者Eilema