跳到主要内容

设计 Token

设计 Token 是主题机制的实现,可以通过一些原子化的 Token 配置集合便捷的配置样式。

例如,实现一套包含背景色和色板配置的主题:

render(dom, {
// ...
token: {
backgroundColor: '#fff',
color: ['red', 'green', 'blue']
}
});
参考

设计 Token 兼容 ECharts 主题,可参考主题编辑器的导出格式。

token

由于 UED Token 规范不能完全覆盖可视化组件的所有配置,所以 token 参数实际上可以包含两部分内容,即 UED Token 变量和配置项,且配置项优先级高于 UED Token 变量

UED Token 变量

设计师负责人为 @钱宇楠(qianyunan@myhexin.com),可找其参考设计规范中的 Token 集合和映射规则进行配置。

type UEDToken = {
/** 色板 */
'--color-visualization': string[];

/** 背景色 */
'--color-background-weak': string;

/** 分割线颜色 */
'--color-visualization-divider': string;
/** tooltip 背景色 / 光标线 */
'--color-visualization-tooltip': string;

/** 文本颜色 */
'--color-text-primary': string;
'--color-text-secondary': string;
'--color-text-tertiary': string;
'--color-text-quaternary': string;
'--color-text-inverse': string;
'--color-text-link': string;
'--color-text-inverse-primary': string;
'--color-text-inverse-secondary': string;
'--color-text-inverse-tertiary': string;
'--color-text-inverse-quaternary': string;

/** 基础灰阶 */
'--color-grey-01': string;
'--color-grey-02': string;
'--color-grey-03': string;
'--color-grey-04': string;
'--color-grey-05': string;

/** 字重 */
'--font-weight-regular': number;
'--font-weight-medium': number;
'--font-weight-bold': number;

/** 字体大小 */
'--font-size-super-large': number;
'--font-size-extra-large': number;
'--font-size-large': number;
'--font-size-base': number;
'--font-size-small': number;
'--font-size-extra-small': number;
'--font-size-super-small': number;
'--font-size-xxs': number;
'--font-size-xxxs': number;

/** 行高 */
'--line-height-super-large': number;
'--line-height-extra-large': number;
'--line-height-large': number;
'--line-height-base': number;
'--line-height-medium': number;
'--line-height-small': number;
'--line-height-extra-small': number;
'--line-height-super-small': number;
'--line-height-xxs': number;
};

配置项

type Token = {
/** 背景色 */
backgroundColor: string;
/** 字体 */
textStyle?: {
color?: string;
fontFamily?: string;
fontWeight?: number | string;
fontSize?: number;
lineHeight?: number;
};
/** 色板 */
color: string[];
/** 范式组件 */
dvStandardChart?: {
/** 主题 @see https://datav.iwencai.com/components/paradigm-chart/docs/apis/theme */
theme?: string;
/** 基础配置 @see https://echarts.apache.org/zh/option.html#title */
baseOption?: StandardChartOption;
};
/** 时间轴组件 */
dvTimeline?: {
theme?: (typeof TIMELINE_THEME)[keyof typeof TIMELINE_THEME];
/** 容器 dom 的 css 样式 */
domCSSText?: string;
/** 时间轴配置 @see https://datav.iwencai.com/components/paradigm-chart/docs/more/paradigm-timeline-docs/apis/option#config */
config?: TimelineOption;
};
};

Legend 组件主题配置项说明

legend 的主题配置应放在 token.dvStandardChart.baseOption.legend 下,支持如下字段:

一级字段

字段类型说明可选值/示例
dvLayoutstring图例布局方式'all' | 'scroll' | 'pagination'
backgroundColorstring图例背景色'#fff'、'transparent'等
textStyleobject文本样式配置(见下表)见下表
dvPaginationobject分页器样式配置(见下表)见下表
dvIconobject图例 icon 样式配置(见下表)见下表
dvLegendGapnumber图例项之间的间距(像素)12、20等

textStyle 字段

字段类型说明示例
fontSizenumber文本字号(px)14
lineHeightnumber文本行高(px)14
fontFamilystring字体族'PingFangSC'
fontWeightstring/number字重'bold'
colorstring文本颜色'#A1A1B3'
dvDisabledTextColorstring未激活项文本颜色'#4F4F5E'

dvPagination 字段

字段类型说明示例(可为 base64/svg url)
colorstring分页器文本颜色'#A1A1B3'
fontSizenumber分页器文本字号(px)12
lineHeightnumber分页器文本行高(px)16
fontFamilystring分页器字体'PingFangSC'
fontWeightstring/number分页器字重'bold'
imagestring下一页/上一页按钮图标'url(...)'
imageHoverstring按钮悬浮图标'url(...)'
imageDisabledstring按钮禁用图标'url(...)'

dvIcon 字段

字段类型说明示例
gapnumbericon 与文本间距(px)6
lineobject线型 icon 尺寸{width:12,height:3}
rectobject矩形 icon 尺寸{width:12}
roundobject圆形 icon 半径{r:12}

完整配置示例

legend: {
dvLayout: 'pagination',
backgroundColor: 'transparent',
textStyle: {
fontSize: 14,
lineHeight: 14,
fontFamily: 'PingFangSC',
fontWeight: 'bold',
color: '#A1A1B3',
dvDisabledTextColor: '#4F4F5E'
},
dvPagination: {
color: '#A1A1B3',
fontSize: 12,
lineHeight: 16,
fontFamily: 'PingFangSC',
fontWeight: 400,
image: 'url(...)',
imageHover: 'url(...)',
imageDisabled: 'url(...)'
},
dvIcon: {
gap: 6,
line: { width: 12, height: 3 },
rect: { width: 12 },
round: { r: 12 }
},
dvLegendGap: 20
}

注意: 只需配置上述字段,其他字段不会生效。legend 配置应放在 token.dvStandardChart.baseOption.legend 路径下。

dvInsight 主题配置

token 中,dvStandardChart.baseOption.dvInsight 路径专门用于定义数据洞察(Insight)所有可视化元素的默认样式。这使得所有图表的洞察效果在视觉上保持统一,并方便地进行全局主题切换。

其核心思想是样式与逻辑分离

  • 图表 spec.dvInsight: 定义应用何种洞察以及其关联的具体数据
  • 主题 token.dvInsight: 定义这些洞察的视觉呈现,如颜色、线条、透明度等。

配置结构

token 中的 dvInsight 是一个对象数组,采用分层样式结构:

  1. 通用样式 (Common Style) 数组的第一个对象用于定义全局通用样式,它没有 type 字段。所有类型的洞察都会默认继承此对象中定义的样式。

  2. 特定类型覆盖 (Type-Specific Override) 从数组的第二个对象开始,每个对象通过指定 type 字段(如 "type": "Trend")来为特定类型的洞察定义专属样式。这些样式会覆盖通用样式。

样式优先级: 特定类型样式 > 通用样式

可配置的样式模块

模块名说明适用洞察类型
blurSeries定义其他系列被“弱化”时的样式,通常是设置一个较低的 opacity所有(用于高亮或对比场景)
line定义由洞察生成的标记线 (markLine) 的基础样式。Line, Trend, CompareLine, ComparePoint
referenceLine定义用于连接两个数据点参考线样式,通常带有箭头。ComparePoint, CompareLine
axisReferenceLine定义用于连接数据点和坐标轴参考线样式,通常是虚线。Point
area定义由洞察生成的标记区域 (markArea) 的样式。Interval, IntervalX
textSummary一个复合对象,用于定义通过 dvMarker 渲染的富文本标注的复杂样式(如背景、引线)。Point, Trend 等需要显示复杂文本信息的洞察
textStyle定义由洞察生成的简单文本 (markPoint.label) 的样式。Text

完整示例

// 位于 token.dvStandardChart.baseOption.dvInsight
dvInsight: [
// =======================================================
// 1. 通用配置 (无 type 字段)
// 所有洞察类型都会继承这里的样式
// =======================================================
{
// 文本标注的默认样式
textSummary: {
rectStyle: { style: { fill: '#FFFFFF', opacity: 0.8 } },
textStyle: { style: { fill: '#000' } }
},
// 标记线的默认样式
line: {
lineStyle: { width: 1, color: '#F2920D' },
label: { color: '#F2920D' }
},
// 参考线的默认样式 (如对比线)
referenceLine: {
symbol: 'image://...', // 默认使用 SVG 箭头
lineStyle: { color: '#FFF' }
},
// 弱化效果的默认样式
blurSeries: {
itemStyle: { opacity: 0.2 },
lineStyle: { opacity: 0.2 }
}
},

// =======================================================
// 2. 特定类型覆盖 (有 type 字段)
// 这里的样式会覆盖通用配置
// =======================================================
{
"type": "Trend",
// 将 "Trend" 洞察的标记线颜色覆盖为 #fff
"line": {
"lineStyle": { "color": "#fff" },
"label": { "color": "#fff" }
}
},
{
"type": "Text",
// 将 "Text" 洞察的文本颜色覆盖为 #FFF
"textStyle": {
"color": "#FFF"
}
}
]

Series 主题配置

dvInsight 类似,token 中的 dvStandardChart.baseOption.series 路径允许您为**不同类型的系列(series)**定义全局的默认样式。这使得在主题层面统一特定图表类型(如所有柱状图、所有折线图)的视觉表现成为可能,而无需在每个图表实例中重复配置。

配置结构与原理

series 的配置是一个对象数组。数组中的每个对象都通过 type 字段来指定其应用的目标系列类型。当 VISALL 渲染图表时,它会:

  1. 检查图表中每个 seriestype
  2. tokenseries 数组中查找具有相同 type 的配置对象。
  3. token 中定义的样式深度合并到图表实例的 series 配置中。

这提供了一种强大的、基于类型的样式模板机制。

自定义配置项

除了支持所有 ECharts 原生的 series 配置外,VISALL 还扩展了一些自定义的 dv* 属性,以提供更强的功能:

  • dvTextColors:

    • 适用类型: wordCloud
    • 作用: 为词云图提供一组特定的文本颜色,渲染器会从这个数组中为词语循环取色。
  • dvReferenceLine:

    • 适用类型: bar
    • 作用: 一个对象,用于控制在柱状图上绘制参考线。{ show: true, color: '#...' }
  • dvData:

    • 适用类型: 通用
    • 作用: 一个数据处理函数 (data) => void。该函数在图表渲染前执行,允许您在主题层面直接修改系列图的数据,例如动态调整标签颜色或节点样式。这是一个强大的主题级数据转换钩子。

完整示例

以下示例展示了如何为 line, bar, pie, wordCloud, sankey 等多种图表类型设置默认样式和自定义行为。

// 位于 token.dvStandardChart.baseOption.series
series: [
// 为所有折线图(line)设置默认样式
{
type: 'line',
symbolSize: 8, // 标记点大小
lineStyle: {
width: 1.5 // 线条宽度
},
itemStyle: {
opacity: 0 // 默认隐藏标记点,悬浮时再显示
}
},
// 为所有柱状图(bar)设置默认样式
{
type: 'bar',
barMaxWidth: 14, // 柱子最大宽度
label: {
color: '#FFF' // 标签文字颜色
},
// 自定义属性:显示参考线
dvReferenceLine: {
show: true,
color: '#828FA1'
}
},
// 为词云图提供专用的文本颜色列表
{
type: 'wordCloud',
dvTextColors: [
'#FAFBFC',
'#E9EDF6',
'#E0E4EA',
'#828FA1'
]
},
// 为桑基图(sankey)提供一个数据后处理钩子
{
type: 'sankey',
// 在渲染前修改每个数据项的标签颜色
dvData: data => {
data.forEach(item => {
item.label.rich.a.color = '#dadada';
item.label.rich.b.color = '#dadada';
});
}
},
// 为饼图(pie)设置默认样式
{
type: 'pie',
label: {
color: '#FFF'
},
labelLine: {
length: 5 // 标签引导线长度
}
}
]

dvHXKLine 主题配置

dvHXKLinetoken 中一个高度集成的配置模块,专门用于深度定制行情 K 线图及其衍生组件。由于行情图的复杂性,它的配置项非常丰富,并且拥有自己独立的命名空间和配置结构。

配置结构

dvHXKLine 模块内部包含多个对象,分别对应不同类型的 K 线图以及它们的共享模块:

  1. 特定 K 线图配置:

    • hxKLine: 标准 K 线图
    • hxKLineAndBar: K 线图与成交量图(柱状图)
    • hxKLineAndDynamicLine: K 线图与动态指标线
    • hxKLineAndMultiIndicatorLine: K 线图与多条动态指标线
    • hxKLineAndTag: K 线图与标签

    这些对象内部都有一个 option 字段,其结构遵循底层行情图组件库的私有 schema,用于定义该类型 K 线图的核心行为和样式(如 yAxis, candle, indicator 等),详细可以参考HXKLine 文档

  2. 共享模块配置:

    • tooltip: 配置所有 K 线图的提示框样式。
    • dataZoom: 配置所有 K 线图的数据漫游组件(缩放条)样式。
    • constants: 一个非常重要的常量集合,它为整个 dvHXKLine 组件家族定义了一套独立的“微型设计 Token”,包括各种涨跌颜色、字体、线条颜色等(详情可以参考HXKLine 常量配置,或者咨询@穆泓宋)。

重点配置项说明

  • [kLineType].option: 这是针对特定 K 线图类型的核心配置,其内容会直接传递给底层的行情图渲染引擎。您可以在这里配置坐标轴 (xAxis, yAxis)、K 线实体 (candle)、技术指标 (indicator) 等。

    hxKLine: {
    option: {
    yAxis: { inside: false, tickText: { family: 'Microsoft YaHei' } },
    candle: { priceMark: { show: false } }
    }
    }
  • [kLineType].rect:

    • 适用类型: hxKLineAndTag
    • 作用: 当 K 线图附带标签时,此对象用于定义标签矩形的边框、背景色,以及在不同交互状态(hover, active)下的样式。
    hxKLineAndTag: {
    rect: {
    borderColor: '#545E71',
    backgroundColor: 'rgba(84, 94, 113, 0.16)',
    hoverBackgroundColor: 'rgba(99, 111, 255, 0.08)',
    activeBorderColor: '#636FFF',
    }
    }
  • dataZoom: 配置 K 线图底部的数据缩放滚动条。可以自定义背景色、填充色、手柄图标等(参考ECharts配置文档)。

    dataZoom: {
    backgroundColor: '#60656C',
    fillerColor: 'rgba(15,98,254,0.2)',
    handleIcon: 'image://data:image/svg+xml;base64,PHN2...'
    }
  • constants: 这是 dvHXKLine基础调色板和尺寸规范。它定义了一系列以 DEFAULT_ 开头的常量,如 DEFAULT_COLOR_UP (上涨红)、DEFAULT_COLOR_DOWN (下跌绿)、DEFAULT_GRID_LINE_COLOR (网格线颜色)、DEFAULT_FONT_FAMILY (默认字体) 等。K 线图组件内部会优先使用这些常量作为默认值。通过修改 constants,可以实现对 K 线图整体视觉风格的快速、全局性调整。

    constants: {
    DEFAULT_COLOR_UP: '#FF2436',
    DEFAULT_COLOR_DOWN: '#07AB4B',
    DEFAULT_GRID_LINE_COLOR: 'rgba(255, 255, 255, 0.06)',
    DEFAULT_FONT_FAMILY: '-apple-system,BlinkMacSystemFont,sans-serif'
    }

UI 组件主题配置

除了 ECharts 相关的图表,VISALL 还包含一系列基于原生 DOM 构建的、独立的 UI 组件,如文本卡片(dvText)、时间轴(dvTimeLine)和多维表格(dvTable)。这些组件的主题同样可以通过 token 进行配置。

配置原理

这些组件的主题机制基于 CSS 自定义属性 (CSS Custom Properties)

  1. token 中,为相应的组件模块(如 dvTable)提供一个对象。
  2. 该对象的所有 key 都应为以 --theme- 开头的字符串,这对应一个 CSS 变量名。
  3. 组件在初始化时,会遍历这些 key-value 对,并通过 domElement.style.setProperty(key, value) 将它们注入到组件的根元素的 style 属性上。
  4. 组件自身的样式表(SCSS)通过 var(--theme-some-property) 的方式来使用这些变量,从而实现动态的主题切换。

dvText

用于配置 @visall/text 组件。

Token Key说明
--theme-background组件的整体背景色
--theme-text-color主要文本颜色
--theme-title-color标题文本颜色
--theme-text-background-normal文本块在普通状态下的背景色
--theme-text-background-hover文本块在悬浮状态下的背景色
--theme-text-background-select文本块在选中状态下的背景色

dvTimeLine

用于配置 @visall/timeline 组件。

Token Key说明
--theme-background组件的整体背景色
--theme-border边框颜色
--theme-line-border时间轴线的颜色
--theme-label标签文本颜色
--theme-label-background标签背景色
--theme-time时间节点的文本颜色
--theme-text事件内容的文本颜色
--theme-link事件内容中的链接颜色
--theme-text-hover事件内容在悬浮状态下的背景色
--theme-text-select事件内容在选中状态下的背景色
--theme-button-color控制按钮的颜色

dvTable

用于配置 @visall/table 组件。这是一个复杂的组件,因此 token 数量较多。

Token Key说明
--theme-border表格单元格的常规边框色
--theme-border-select选中状态下的边框色
--theme-header-background表头的背景色
--theme-header-text表头的文本颜色
--theme-normal-background内容单元格的背景色
--theme-normal-text内容单元格的文本颜色
--theme-header-hover表头在悬浮状态下的背景色
--theme-normal-hover内容单元格在悬浮状态下的背景色
--theme-header-select表头在选中状态下的背景色
--theme-icon-container图标容器的背景(可为渐变色)
--theme-icon-container-hover悬浮时图标容器的背景
--theme-icon-container-selected选中时图标容器的背景
--theme-expand-icon-background展开/收起图标的背景
--theme-sort-icon-container-hover排序图标在悬浮时的背景
--theme-tree-icon-hover树形表格图标在悬浮时的背景
--theme-icon-up“升序”图标的 url()
--theme-icon-up-enable“升序”图标在激活状态下的 url()
--theme-icon-down“降序”图标的 url()
--theme-icon-down-enable“降序”图标在激活状态下的 url()
--theme-expand-icon-text展开/收起图标旁的文本颜色
--theme-expand-icon-down“展开”图标的 url()

dvDropdown

用于配置位于 src/ui/dropdown 的下拉菜单组件。

Token Key说明
--theme-text文本颜色
--theme-text-hover悬浮状态的文本颜色
--theme-background背景色
--theme-background-hover悬浮状态的背景色
--theme-background-select选中状态的背景色
--theme-border边框颜色
--theme-kline-textK线图场景下的文本颜色
--theme-kline-text-hoverK线图场景下悬浮的文本颜色
--theme-dropdown下拉箭头图标的 url()
--theme-default-dropdown默认下拉箭头图标的 url()

dvPagination

用于配置位于 src/ui/pagination 的分页器组件。

Token Key说明
--theme-button“上一页/下一页”按钮的图标 url()
--theme-more“更多”按钮的图标 url()
--theme-fast“快速跳转”按钮的图标 url()
--theme-button-disabled禁用状态按钮的图标 url()
--theme-background-color-disabled禁用状态的背景色
--theme-background-color默认背景色
--theme-border-color边框颜色
--theme-background-color-selected选中页码的背景色
--theme-font-color-selected选中页码的文本颜色
--theme-border-color-selected选中页码的边框颜色
--theme-background-color-hover悬浮状态的背景色
--theme-font-color-hover悬浮状态的文本颜色
--theme-font-color默认文本颜色

dvButtonGroup

用于配置位于 src/ui/buttonGroup 的按钮组组件。

Token Key说明
--theme-container-background-color按钮组容器的背景色
--theme-color按钮文本/图标的颜色
--theme-color-hover悬浮时按钮的颜色
--theme-background-color-selected选中时按钮的背景色
--theme-color-selected选中时按钮的颜色
--theme-background-color单个按钮的默认背景色

dvScrollButtonGroup

用于配置位于 src/ui/scrollButtonGroup 的可滚动按钮组组件。

Token Key说明
--theme-background-color按钮背景色
--theme-color按钮文本颜色
--theme-background-color-hover悬浮时按钮的背景色
--theme-color-hover悬浮时按钮的文本颜色
--theme-color-selected选中时按钮的文本颜色
--theme-background-color-selected选中时按钮的背景色

示例

{
// ... 其他 token 配置
dvText: {
'--theme-background': '#10182E',
'--theme-text-color': '#FFD993',
'--theme-title-color': '#C4CAD5'
},
dvPagination: {
'--theme-background-color': '#181E25',
'--theme-border-color': '#60656C',
'--theme-font-color': '#FFFFFF',
'--theme-background-color-selected': '#2C375D',
'--theme-font-color-selected': '#7E8DFF'
},
dvButtonGroup: {
'--theme-color': '#C8CBD0',
'--theme-background-color-selected': '#24282E',
'--theme-color-selected': '#7E8DFF',
},
dvDropdown: {
'--theme-text': '#FAFBFC',
'--theme-background': '#181E25',
'--theme-background-select': '#272E50',
'--theme-border': '#60656C',
}
// ...
}

图表特定主题配置

除了上述通用配置外,token 中还包含一些直接与特定图表类型或渲染器绑定的配置项。

dvTreemapLevelStyle

用于深度定制可下钻矩形树图 (drillableTreeMap) 的层级样式。

Token Key说明
labelOpenIcon“上卷”图标的 url()
labelCloseIcon“下钻”图标的 url()
labelColor层级标签的全局文字颜色
level_2, level_3, ...特定层级的样式配置对象。key 必须为 level_ + 层级数
[level_n].itemStyleBorderColor第 n 层矩形块的边框颜色
[level_n].upperLabelBackgroundColor第 n 层“面包屑”标签的背景色
[level_n].upperLabelBackgroundColorE第 n 层“面包屑”标签在悬浮或高亮 (Emphasis) 状态下的背景色

dvMarkerLine

用于配置由 markerLine 图层渲染的自定义标记线的样式。

Token Key说明
titleColor标记点上标题文本的颜色
descColor标记点上描述文本的颜色
scatterBorderColor标记点(散点)的边框颜色
markerBackground标记点的背景色(通常带有透明度)
markerCircleColor标记点内部小圆点的颜色

dvRadar

用于配置雷达图 (radar) 的坐标系样式。其内部结构与 ECharts 的 radar 配置项完全一致。

Token Key说明
axisLine坐标轴轴线相关设置
splitLine坐标轴在 grid 区域中的分隔线。
axisName坐标轴名称的文字样式
splitArea坐标轴在 grid 区域中的分隔区域,默认是关闭的。

示例

{
// ... 其他 token 配置
dvTreemapLevelStyle: {
labelOpenIcon: 'data:image/svg+xml;...',
labelCloseIcon: 'data:image/svg+xml;...',
labelColor: '#fff',
level_2: {
itemStyleBorderColor: 'rgba(42, 53, 78, 1)',
upperLabelBackgroundColor: 'rgba(42, 53, 78, 1)'
},
level_3: {
upperLabelBackgroundColor: 'rgba(84, 94, 113, 1)'
}
},
dvMarkerLine: {
titleColor: '#fff',
descColor: '#C4CAD5',
markerBackground: 'rgba(0, 0, 0, 0.5)'
},
dvRadar: {
axisLine: {
lineStyle: { color: '#2A354E' }
},
splitLine: {
lineStyle: { color: '#2A354E' }
},
axisName: { color: '#F2F5FA' }
}
// ...
}