HQChart K线图配色与样式参数完全指南：内置风格切换、全局资源修改与动态刷新

• 前端
• 图表库
• 金融科技

HQChart 是一套面向 H5、微信小程序等场景的行情图表库，其 K 线、分时图的全部配色与样式都收敛在一份全局样式配置对象g_JSChartResource中，通过JSChart.GetResource()/JSChart.SetStyle()等静态接口即可读取、替换与刷新。本文基于仓库文档 K线图配色和样式参数详解 并对照 webhqchart 与 webhqchart.demo/jscommon 源码，系统讲解白色/黑色两套内置风格的使用、样式配置字段的完整含义，以及不刷新页面即可切换主题的实战方案。

一、样式体系与加载机制

HQChart 的所有 K 线样式配置统一加载到全局变量g_JSChartResource中，背景色则由承载 K 线的 div 直接控制——插件画布背景是透明的，因此修改背景只需要改外层 div 的 CSS 背景色，而不必进入图表配置。

从 umychart.js 源码可以看到样式相关的四个静态入口：

• JSChart.SetStyle(option)：把传入的样式配置整体写入g_JSChartResource；
• JSChart.GetResource()：返回当前全局样式配置对象，可直接对其字段做局部修改；
• JSChart.SetCSSStyle(styleID)：把风格 ID 写入<html>的hqchart_style属性，驱动插件内置的 CSS 变量切换；
• JSChart.Init()：实例化图表，源码注释明确要求“设置配色必须在JSChart.Init()之前”，即先配好样式再创建实例。

配合图形实例的ReloadResource({ Draw, Update })方法，可在运行时把新样式真正重绘到画布上。

二、核心样式函数

2.1 获取全局样式配置 GetResource

// 静态函数 JSChart.GetResource=function() // 获取全局样式配置

返回的g_JSChartResource是一个可变对象，内置颜色不满足需求时，可直接修改其中的UpBarColor、DownBarColor、TooltipBGColor等字段后再重绘，无需重建整个配置。

2.2 获取内置样式配置 GetStyleConfig

HQChart 内置两套风格：白色风格与黑色风格。

// 静态函数 HQChartStyle.GetStyleConfig=function(styleid)

• styleid风格 ID（定义于 umychart.style.js 的STYLE_TYPE_ID）：
  • 0白色风格STYLE_TYPE_ID.WHITE_ID；
  • 1黑色风格STYLE_TYPE_ID.BLACK_ID；
  • 其他值返回null。

源码实现（umychart.style.js）中，黑色风格由专门的GetBlackStyle()构建，白色风格则直接new JSChartResource()使用默认值。需要说明的是：调用该函数得到的是全新的配置对象副本，后续SetStyle写入的是这个副本，不会污染内置模板。

2.3 修改全局样式配置 SetStyle

// 静态函数 JSChart.SetStyle=function(config) // 设置全局样式配置

• config：样式配置信息，通常来自HQChartStyle.GetStyleConfig()的返回值，也可以是自定义对象。

源码中SetStyle会把传入的 option 交给g_JSChartResource.SetStyle(option)合并应用，之后图形实例通过ReloadResource触发重绘。

2.4 图形实例动态刷新样式 ReloadResource

ReloadResource=function( option )

• option: { Draw: true, Update: true }
  • Draw：是否清除缓存后重绘图形；
  • Update：是否不清除缓存重绘图形（增量更新）。

在 webhqchart.demo/jscommon/umychart.js 中，ReloadResource会把调用转发给内部的JSChartContainer.ReloadResource(option)。切换风格时通常传{ Draw: true, Update: false }，即强制全量重绘。

2.5 修改全局 CSS 样式变量 SetCSSStyle

// 静态函数 JSChart.SetCSSStyle(styleID);

• styleID：风格 ID（同STYLE_TYPE_ID）。

其实现为document.documentElement.setAttribute('hqchart_style', styleID)（见 umychart.js），通过切换根节点上的hqchart_style属性，联动样式表中基于[hqchart_style]属性选择器定义的 CSS 变量（字体、图标、对话框等 DOM 元素的颜色），与 Canvas 上的 K 线配色相互独立、互不干扰。

三、修改样式实战示例

3.1 内置风格切换（原生 JS）

// 风格设置必须在 SetOption 之前。 // 原生引用不需要加前缀 HQChart.Chart. var blackStyle = HQChartStyle.GetStyleConfig(STYLE_TYPE_ID.BLACK_ID); // 读取黑色风格配置 JSChart.SetStyle(blackStyle); var resource = JSChart.GetResource(); // 获取当前的全局样式配置 // 如果内置的颜色不满足需求，可以自己修改 resource 样式配置

3.2 内置风格切换（vue2 + npm）

import HQChart from 'hqchart' import 'hqchart/src/jscommon/umychart.resource/font/drawtool/iconfont.css'; // HQChart 插件内部使用的 iconfont 图标 import 'hqchart/src/jscommon/umychart.resource/css/tools.css' // HQChart 插件内置样式 // 风格设置必须在 SetOption 之前。 // npm 导入插件后，需要加前缀 HQChart.Chart. var blackStyle = HQChart.Chart.HQChartStyle.GetStyleConfig(HQChart.Chart.STYLE_TYPE_ID.BLACK_ID); // 读取黑色风格配置 HQChart.Chart.JSChart.SetStyle(blackStyle); var resource = HQChart.Chart.JSChart.GetResource(); // 获取当前的全局样式配置 // 如果内置的颜色不满足需求，可以自己修改 resource 样式配置

3.3 不刷新页面切换样式（原生 JS）

ChangeStyle(styleID) { var style = HQChartStyle.GetStyleConfig(styleID); // 读取目标风格配置 JSChart.SetCSSStyle(styleID); // 切换 CSS 变量风格 JSChart.SetStyle(style); // 写入 Canvas 配色 var resource = JSChart.GetResource(); // 获取当前的全局样式配置 // 如果内置的颜色不满足需求，可以自己修改 resource 样式配置 chart.ReloadResource({ Draw: true, Update: false }); // K线图实例重绘 }

3.4 不刷新页面切换样式（vue2）

ChangeStyle(styleID) { var style = HQChart.Chart.HQChartStyle.GetStyleConfig(styleID); // 读取目标风格配置 HQChart.Chart.JSChart.SetCSSStyle(styleID); HQChart.Chart.JSChart.SetStyle(style); var resource = HQChart.Chart.JSChart.GetResource(); // 获取当前的全局样式配置 // 如果内置的颜色不满足需求，可以自己修改 resource 样式配置 chart.ReloadResource({ Draw: true, Update: false }); // K线图实例重绘 }

这四段示例覆盖了原生引用与 npm 模块化引用两种场景，其中ChangeStyle是"白天/黑夜"主题切换的完整闭环：先切 CSS 变量，再换 Canvas 配色，最后强制全量重绘。

四、样式配置信息详解

4.1 基础样式字段

黑色风格各字段的默认取值可以直接对照 umychart.style.js 中的GetBlackStyle()实现，它同时演示了标准的配置结构：除上表字段外还包含BGColor、SelectRectBGColor、Minute、PopMinuteChart、PopKLineChart等分时图与弹窗配置。注意源码注释提示：手机上字体大小需要乘以分辨率比（GetDevicePixelRatio()，即window.devicePixelRatio || 1）。

4.2 指标栏工具栏参数详解 KLineToolbar

这组开关用于控制指标栏上各功能按钮的显隐，是精简界面、面向不同终端（PC 横屏/手机竖屏）定制 UI 的重要入口。

4.3 数据下载提示信息配置 SplashScreen

该配置对应数据加载期间的启动提示层，配合实例方法EnableSplashScreen(enable, option)（见 webhqchart.demo/jscommon/umychart.js）可控制其显示与样式。

4.4 K 线 'HLC Area' 图形参数详解 HLCArea

'HLC Area' 是同时绘制最高/最低/收盘三条折线并以面积填充的图形类型，涨跌面积默认使用半透明红绿以区分多空区间。

4.5 K 线 'HLC Bar' 图形参数详解 HLCBar

'HLC Bar' 以柱子形式呈现高、低、收三个价位，字段较少，通常只调节颜色与线宽即可。

五、源码级延伸：样式如何生效

为便于排查自定义配色不生效的问题，这里梳理关键调用链：

1. 静态接口定义于 webhqchart/umychart.js：SetStyle写入g_JSChartResource，SetCSSStyle设置根节点属性hqchart_style，GetResource返回全局配置引用；
2. 风格模板构建于 webhqchart.demo/jscommon/umychart.style.js：STYLE_TYPE_ID定义两种风格 ID，GetBlackStyle()产出黑色风格完整对象，HQChartStyle.GetStyleConfig()负责按 ID 分发；
3. 实例刷新通过 webhqchart.demo/jscommon/umychart.js 的ReloadResource转发到内部容器执行重绘。

三个环节的配合关系是：先 SetStyle 改配置，再 ReloadResource 触发重绘；DOM 相关样式走 SetCSSStyle，Canvas 配色走 SetStyle。二者缺一不可，否则会出现"画布颜色已变但按钮/文字仍沿用旧主题"的割裂现象。

六、注意事项

• 风格设置（SetStyle/SetCSSStyle）必须在JSChart.Init()与SetOption之前完成，否则实例创建时已捕获旧样式；
• 原生引用与 npm 导入的命名空间不同：原生使用HQChartStyle/JSChart，npm 导入需加HQChart.Chart.前缀；
• 内置风格不能满足需求时，推荐在GetStyleConfig返回的对象副本上做局部字段覆盖（如只改UpBarColor、DownBarColor），再SetStyle写入，避免手工从零拼装整套配置；
• 手机端注意字号与线宽需按devicePixelRatio放大，源码中黑色风格即采用2*GetDevicePixelRatio()、14*GetDevicePixelRatio() px这类写法；
• 本文配置字段与接口以 HQChart-skill/references/K线图配色和样式参数详解.md 及 webhqchart.demo/jscommon/umychart.style.js 当前仓库版本为准，完整可运行的 K 线示例可参考 webhqchart.demo/samples/chart_kline.html。

• 前端
• 图表库
• 金融科技