图表渲染器

本文档仅提供2.0API版本的相关功能说明，对于1.0API版本的功能，请参考旧版文档。

图表渲染器用于为自定义图表、 图表插件实现图表渲染逻辑。

{
  //可选，此渲染器的依赖库（JavaScript、CSS），将会在渲染器的render()函数执行前自动加载，
  //支持格式：依赖库名称（其name值）、依赖库对象、名称/对象数组、函数（可以返回名称、对象、数组）
  depend: "..."、{ ... }、[ ... ]、function(){ return ...; }
  
  //必填，渲染图表，执行无数据的初始绘制操作，
  //如果返回Promise对象，表明是异步函数，在兑现时表示渲染完成。
  //此函数在图表生命周期内仅会被调用一次，具体参考chart.render()函数
  //chart 图表对象
  render: function(chart){ ... },
  
  //必填，更新图表，使用chartResult中包含的数据执行更新绘制操作，
  //如果返回Promise对象，表明是异步函数，在兑现时表示更新完成。
  //此函数在图表生命周期内可能会被调用多次，具体参考chart.update()函数
  //chart 图表对象
  //chartResult 要更新的图表结果
  update: function(chart, chartResult){ ... },
  
  //必填，销毁图表，销毁在上述render()、update()函数中创建的资源
  //此函数在图表生命周期内仅会被调用一次，具体参考chart.destroy()函数
  //chart 图表对象
  destroy: function(chart){ ... },
  
  //可选，调整图表尺寸，希望图表支持dg-chart-auto-resize时应该定义
  //chart 图表对象
  resize: function(chart){ ... },
  
  //可选，绑定图表事件处理函数，希望图表支持dg-chart-link、dg-chart-on-*时应该定义
  //chart 图表对象
  //type 事件类型，比如："click"、"mouseover"
  //handler 事件处理函数，格式为：function(...){ ... }，其参数格式由具体渲染器规定
  on: function(chart, type, handler){ ... },
  
  //可选，解绑图表事件处理函数
  //chart 图表对象
  //type 解绑事件类型
  //handler 解绑事件处理函数
  off: function(chart, type, handler){ ... },
  
  //可选，名/值附加信息
  additions: { ... }、function(){ return { ... };  }
}

依赖库用于定义图表渲染器依赖的JavaScript、CSS库， 这些库会在图表渲染器的render()函数执行前被自动加载， 使得在其render()、update()、destroy()函数中可以直接使用这些依赖库。

依赖库结构如下所示：

{
  //必填，库名称，应尽量使用库本身定义的全局名称
  name: "...",
  //可选，库别名，仅用于下面loaded()函数的默认判断规则
  alias: "..."、[ "...", ... ],
  //可选，兼容接受版本，为空表示接受任意版本，详见接受版本格式章节
  //接受版本应尽量设为更大的范围，以减少同名依赖库的多版本同时需要时的加载冲突问题
  acceptVersion: "...",
  //可选，可提供的库源版本号，为空表示不提供，应符合语义化版本规范："X.Y.Z"、"X.Y.Z-BUILD"
  version: "...",
  //可选，可提供的库源信息，为空表示不提供
  source:
  //库源URL，详见库源URL格式章节
  "..."、
  //库源对象
  {
    //必填，库源URL，详见库源URL格式章节
    url: "...",
    //可选，库源类型，会根据库源URL自动识别*.js、*.css
    type: "js"、"css"
  }、
  //由上述两种格式组成的数组，靠前的将先加载
  [ ... ]、
  //库源函数，返回上述任一格式即可
  function(){ return ...; },
  //可选，此库的依赖库信息，将先于此库加载，不设置表示无依赖
  depend:
  //此库的依赖库名称（其name值）
  "..."、
  //此库的依赖库名称及接受版本
  //name 同上述name格式
  //acceptVersion 同上述acceptVersion格式
  { name: "...", acceptVersion: "..." }、
   //由上述两种格式组成的数组
  [ ... ],
  //可选，检查当前环境是否已经加载了此库，而无需再加载，返回值：true 是；false 否。
  //默认规则：如果name或者alias值对应的全局变量已定义，则返回true，否则返回false
  loaded: function(){ return true、false; }
}

示例：

• "somelib"、{ name: "somelib" }
  表示不提供实际依赖库，需要运行环境加载任意版本的somelib库
• { name: "somelib", acceptVersion: "^1.0" }
  表示不提供实际依赖库，需要运行环境加载匹配"^1.0"版本的somelib库
• { name: "somelib", version: "0.9", source: ... }
  表示提供0.9版本的依赖库，且兼容接受运行环境加载任意版本的somelib库
• { name: "somelib", version: "0.9", source: ..., acceptVersion: "^1.0" }
  表示提供0.9版本的依赖库，且兼容接受运行环境加载匹配"^1.0"版本的somelib库

格式	说明
"X.Y.Z"	仅接受X.Y.Z版本。 示例："1.2"、"2.1.6"
"^X.Y.Z"	接受大于等于X.Y.Z且小于(X+1).0的版本。 示例："^1.2"，表示接受大于等于1.2.0且小于2.0的版本
"~X.Y.Z"	接受大于等于X.Y.Z且小于X.(Y+1).0的版本。 示例："~1.2"，表示接受大于等于1.2.0且小于1.3.0的版本
">X.Y.Z"	接受大于X.Y.Z的版本。 示例：">1.2"
">=X.Y.Z"	接受大于或等于X.Y.Z的版本。 示例：">=1.2"
"<X.Y.Z"	接受小于X.Y.Z的版本。 示例："<1.2"
"<=X.Y.Z"	接受小于或等于X.Y.Z的版本。 示例："<=1.2"
">A.B.C <X.Y.Z" ">=A.B.C <X.Y.Z" ">A.B.C <=X.Y.Z" ">=A.B.C <=X.Y.Z"	接受大于/大于等于A.B.C且小于/小于等于X.Y.Z的版本。 示例： ">1.2 <3.0"、">=1.2 <3.0"、">1.2 <=3.0"、">=1.2 <=3.0"
"ACCEPT-1 || ACCEPT-N"	接受ACCEPT-1或者ACCEPT-N的版本， 其中ACCEPT-1、ACCEPT-N可以是上述任意格式。 示例："^1.2 || ^3.1.2 || >=5.0"、"<2.0 || >=4.0 <8.0"

对于在图表插件的renderer.js中定义的图表渲染器， 库源URL支持如下格式：

• 以/开头
  表示相对于应用根路径的URL，示例：/dv/global/lib/xxx.js
• 以http://、https://开头
  表示绝对URL，示例：http://192.168.1.1:50401/dv/global/lib/xxx.js
• 其它
  表示此图表插件内的资源文件， 示例：assets/lib/component.js、assets/lib/style.css

对于在看板页面自定义图表中定义的图表渲染器， 库源URL应是相对于当前看板页面的路径。
示例：static/lib/xxx.js、../static/lib/xxx.js。

依赖库的加载遵循如下规则：

• 相同名称的依赖库仅会加载一次、且是加载当前页面范围内所有图表渲染器依赖库acceptVersion交集中一个
• 如果某个图表渲染器的依赖库导致上述acceptVersion交集为空，这个渲染器的依赖库的acceptVersion需求将被忽略
• 如果当前页面中已加载过某个依赖库，无论版本高低，都不会再加载
• 依赖库不会重试加载，无论本次加载是否成功，都不会再尝试加载

系统默认提供了一些依赖库，可以在图表渲染器的depend中设置后，在其render()、update()函数中通过全局变量名引用，如下表所示：

名称	版本	全局变量名	渲染器引用示例
echarts	6.1.0	echarts	{ depend: { name: "echarts", acceptVersion: ">=5.0" }, ... }
jQuery	3.7.1	jQuery	{ depend: { name: "jQuery", acceptVersion: ">=2.0" }, ... }

不要在acceptVersion中使用上述内置依赖库的"6.1.0"、"3.7.1"精确版本格式， 因为它们可能在会系统后续版本中升级为更高的兼容版本。

在图表渲染器的additions中定义defaultLinkEventType附加信息可以修改图表联动的默认触发事件（默认为"click"事件）。
比如，将默认图表联动事件改为【鼠标划过】事件：

{
  ...,
  additions:
  {
    defaultLinkEventType: "mouseover"
  }
}

1. 构建初始渲染选项

参考 chart.name()、 chart.configValues()、 chart.options()、 chart.inflateOptions()、 chart.pluginConfigForm() 等函数。

2. 执行初始渲染

3. 保存内部状态

参考 chart.internal()、 chart.liveValue() 等函数。

由chartResult（图表结果）参数构建图表展示数据，更新图表组件，参考 chart.dataSetBindMain()、 chart.dataSetBindsMain()、 chart.dataSetBindsFetched()、 chart.dataSetAlias()、 chart.dataSetFields()、 chart.isDataSetSigned()、 chart.isDataSetFieldSigned()、 chart.dataSetFieldOfSign()、 chart.dataSetFieldsOfSign()、 chart.dataSetFieldAlias()、 chart.result*() 等函数。

调用底层组件直接绑定事件处理函数， 或者先构建事件处理函数代理，使用chart.registerEventHandlerDelegate()函数注册， 再调用底层组件绑定事件处理函数代理。

调用底层组件直接解绑事件处理函数， 或者使用chart.removeEventHandlerDelegate()函数移除事件处理函数代理， 再调用底层组件解绑事件处理函数代理。