数据格式

图表组件

每种图表共用同一套字段;具体使用 x、y、d 和 r 中的哪几个,以及每个字段接受何种类型的列,取决于图表类型——下文各小节分别介绍每一种受支持的图表类型,并配有基于同一个小型示例数据集渲染的实时示例。

• datasetId - 该图表所读取的数据集——必须与某个数据集的名称一致。
• chartType - area, bar, cell, dot, hexbin or line。
• title - 可选的图表标题。
• dataFunction - 应用于 d 的聚合方式:count (default), sum, average, min, max, median or stddev。使用 count 时,d 应保持未设置。
• x - X 维度对应的列(所有图表类型都必填)。
• y - Y 维度对应的列(仅适用于 cell、dot 和 hexbin,且这三种类型必填)。
• d - 聚合到图表数值/颜色维度中的列。
• r - 半径维度对应的列(仅适用于 dot,且为必填)。
• seasonX / seasonY - 将时间列按周期性时段分组:year, quarter, month, week, dayofyear, day, dayofweek, hour, minute or second。

维度列会依据其声明的类型被划分为分类型、时间型或连续型——详见下文的数据集 JSON 部分。当 dataFunction 为 count 时,d 维度应保持未设置——计数(count)不需要数值列。其他任何聚合方式(sum, average, min, max, median or stddev)都需要该列。

图表类型所需的维度必须填写:cell、dot 和 hexbin 缺少 y 就无法绘制,dot 缺少 r 同样无法绘制。缺少其中任何一项的请求都会被拒绝,因此如果数据集中没有合适的列,请改选不需要该维度的图表类型——area、bar 和 line 只需 x,hexbin 则无需半径列即可呈现两个维度。

柱状图

折线图

面积图

热力图

散点图

六边形分箱图

其他组件

表格 (dash_table)

文本 (dash_text)

图片 (dash_image)

间隔 (dash_spacer)

堆叠容器 (dash_stacker_hor, dash_stacker_ver)

数据集 JSON

数据集是一个单一的 JSON 对象,包含名称、带类型的列以及行数据:

{
  "name": "Orders",
  "headers": ["region", "category", "amount", "quantity"],
  "types": ["VARCHAR", "VARCHAR", "FLOAT", "INTEGER"],
  "entries": [
    ["North", "Electronics", 120.50, 2],
    ["South", "Clothing",     89.95, 1],
    ["North", "Furniture",   432.00, 5],
    ["South", "Electronics",  74.50, 1]
  ]
}

• name - 数据集名称;图表和表格通过各自的 datasetId 字段引用它。
• headers - 各列的名称,顺序与 entries 中每行的顺序一致。
• types - 每个表头对应一个列类型——具体分类见下文。
• entries - 行数据,每一行是一个按表头顺序排列的值数组。

您可以选择使用 row_start、row_end、col_start 和 col_end 来指定要导入的 entries 子范围(从零开始计数,首尾均包含)——这在只需从更大的表格中追加新行时非常有用。这四个字段默认均为完整范围:

{
  "name": "Orders",
  "headers": ["region", "amount"],
  "types": ["VARCHAR", "FLOAT"],
  "entries": [ ["North", 120.50], ["South", 89.95], ["North", 432.00], ["South", 74.50] ],
  "row_start": 0,
  "row_end": 1,
  "col_start": 0,
  "col_end": 1
}

每种列类型都被划分为分类型、时间型或连续型,这决定了它可以用于哪些图表维度——详见上文的图表组件部分:

• 分类型 - BIT, BITSTRING, BOOLEAN, BOOL, LOGICAL, BLOB, BYTEA, BINARY, VARBINARY, UUID, VARCHAR, CHAR, BPCHAR, TEXT, STRING
• 时间型 - DATE, TIME, TIMESTAMP, DATETIME, TIMESTAMP WITH TIME ZONE, TIMESTAMPTZ
• 连续型 - 其他所有类型,例如 INTEGER, FLOAT, DOUBLE, BIGINT, DECIMAL

图表中的列引用(x、y、d、r)必须与表头名称完全一致,并区分大小写。

样式与主题覆盖

仪表板级别的颜色只需在 config.style.widget 中设置一次,便会应用于所有未单独覆盖这些设置的组件:

• color - 默认文字颜色。
• backgroundColor - 仪表板的默认背景色。
• primaryColor - 前景/激活系列颜色,用于标题以及交叉筛选后高亮的数据系列。
• primaryColorSubtle - cell、dot 和 hexbin 图表所使用的颜色渐变的低值端。
• secondaryColor - 背景/未筛选系列颜色。

任何组件都可以直接在其 JSON 节点上覆盖自身的样式——backgroundColor、color、padding、borderRadius、borderWidth、borderColor 和 shadow。下面的示例覆盖了某个图表自身的颜色与圆角,而仪表板的其余部分仍沿用共享主题:

{
  "type": "dash_chart",
  "datasetId": "Orders",
  "chartType": "hexbin",
  "x": "amount",
  "y": "quantity",
  "backgroundColor": "#F5F0FF",
  "borderRadius": "12px",
  "borderWidth": "1px",
  "borderColor": "#6E2BDC",
  "shadow": true
}

完整示例

一个小型仪表板示例,包含一个标题、并排的两个图表以及一个表格,全部读取自同一个数据集:

{
  "config": {
    "type": "dashboard",
    "style": {
      "widget": {
        "color": "#000000",
        "backgroundColor": "#FFFFFF",
        "primaryColor": "#6E2BDC",
        "primaryColorSubtle": "#E2D5F8",
        "secondaryColor": "#CCCCCC"
      }
    }
  },
  "data": {
    "type": "dash",
    "children": [
      { "type": "dash_text", "text": "Orders Overview", "fontSize": "2vw", "justifyContent": "0" },
      {
        "type": "dash_stacker_hor",
        "children": [
          { "type": "dash_chart", "datasetId": "Orders", "chartType": "bar",  "x": "region", "dataFunction": "count" },
          { "type": "dash_chart", "datasetId": "Orders", "chartType": "cell", "x": "region", "y": "category", "dataFunction": "count" }
        ]
      },
      { "type": "dash_table", "datasetId": "Orders" }
    ]
  }
}