数据洞察社区组件 (dscc) 库参考

API 简介

dscc(数据洞察社区组件)是一个可用于为数据洞察构建社区组件的库。我们在 GitHub 上提供了源代码。

dscc 公开了三个函数:getWidth()getHeight()subscribeToData()

getWidth()

名称 参数 返回值的类型 说明
getWidth() number 返回 iframe 的宽度(以像素为单位)

使用 getWidth()

// to get the width of the iframe
    var width = dscc.getWidth();
    

getHeight()

名称 参数 返回值的类型 说明
getHeight() int 返回 iframe 的高度(以像素为单位)

使用 getHeight()

// to get the height of the iframe
    var height = dscc.getHeight();
    

sendInteraction()

sendInteraction() 函数用于向数据洞察发送一条消息,其中包含要用来创建过滤器的数据。

参数:

名称 类型 说明
actionID string 与配置中的 actionId 对应的字符串
interaction enum(InteractionType) 告知数据洞察相应互动的相关信息
data object(InteractionData) 为互动提供所需的数据

InteractionType

目前,唯一有效的 InteractionTypeFILTER

名称 类型 说明
dscc.InteractionType.FILTER Enum 描述 FILTER 互动

使用 sendInteraction


    // the actionID can either be hardcoded or parsed from the returned data
    var actionId = "interactionConfigId";

    // dscc provides enums for the interaction types
    var FILTER = dscc.InteractionType.FILTER;

    var fieldID = "qt_m9dtntutsb";
    var dataValue = "Asia";

    // sendInteraction expects data that tells you the concepts and the values of
    // those concepts to use in constructing a filter.
    var interactionData = {
      "concepts": [fieldId],
      "values": [[dataValue]]
    }

    dscc.sendInteraction(actionId, FILTER, interactionData);
    

interactionData

var interactionData = {
      "concepts": array(fieldId),
      "values": array(array(dataValue))
    }
    
字段 类型 说明
concepts Array fieldIds 组成的数组
values Array<Array> 由数据值组成的嵌套数组。每个子数组都应是 concepts 数组的长度。子数组中的每个值都对应一个维度值。

interactionData 示例:

var interactionData = {
      "concepts": ["dim1Id", "dim2Id"],
      "values": [
        ["dim1Val1", "dim2Val1"],
        ["dim1Val2", "dim2Val2"]
        ]
    }
    

dscc.sendInteraction 与上面的 interactionData 配合使用等效于以下 SQL 语句:

SELECT data WHERE
      (dim1 == dim1Val1 AND dim2 == dim2Val1)
      OR
      (dim1 == dim1Val2 AND dim2 == dim2Val2);
    

clearInteraction()

clearInteraction() 函数会向数据洞察发送一条消息,以清除该可视化图表之前设置的过滤器。

参数:

名称 类型 说明
actionID string 与配置中的 actionId 对应的字符串
interaction enum(InteractionType) 告知数据洞察相应互动的相关信息

使用 clearInteraction()


    // the actionID can either be hardcoded or parsed from the returned data
    var actionId = "interactionConfigId";

    // dscc provides enums for the interaction types
    var FILTER = dscc.InteractionType.FILTER;

    dscc.clearInteraction(actionId, FILTER);
    

subscribeToData(callback, options)

subscribeToData() 函数用于订阅来自数据洞察的消息。

参数:

名称 类型 说明
callback(data) function 一个函数,用于获取 subscribeToData 返回的数据。
options object 用于指定所需的数据返回格式

options 对象大致如下所示:

{
      transform: dscc.tableTransform | dscc.objectTransform
    }
    

返回值:

类型 说明
function 退订 callback,不再接收来自数据洞察的消息

使用 subscribeToData()

// define and use a callback
    var unsubscribe = dscc.subscribeToData(function(data){
      // console.log the returned data
      console.log(data);
    }, {transform: dscc.tableTransform});

    // to unsubscribe

    unsubscribe();

    

data

这是传递给向 dscc.subscribeToData 进行了注册的 callback 的对象。以下是在 dscc.objectFormatdscc.tableFormat 之间共用的字段。

{
      fields: object(fieldsByConfigId),
      style: object(styleById),
      interactions: object(interactionsById),
      theme: object(themeStyle),
      tables: object(tablesById)
    }
    
字段 类型 说明
fields object(fieldsByConfigId) 一个包含字段(按 configId 编入索引)的对象
style object(styleById) 一个包含样式对象(按 configId 编入索引)的对象
interactions object(interactionsById) 一个包含互动对象的对象
theme themeStyle 一个 themeStyle 对象,包含报告的主题背景样式信息
tables object(tablesById) 一个包含 tableObjects 的对象

fieldsByConfigId

{
       configId: array(field)
    }
    

fieldsByConfigId 对象包含由字段对象(按可视化图表配置中指定的“id”编入索引)组成的数组。配置中指定的每个 dataField 在此对象中均有一个对应的条目。

字段 类型 说明
configId Array<field> 由与 dataField 关联的字段组成的数组

field

{
      id: fieldId,
      name: string,
      description: string,
      type: fieldType,
      concept: enum(conceptType)
    }
    

field 对象提供用户在属性面板中选择的字段的相关信息。

字段 类型 说明
id string 数据洞察为该字段生成的 ID
name string 直观易懂的字段名称
description string 对该字段的说明
type enum(fieldType) 该字段的 semanticType
concept enum(conceptType) 该字段的 conceptType

styleById

{
       configId: styleValue
    }
    

styleById 对象提供样式信息(按可视化图表配置中指定的“id”编入索引)。

字段 类型 说明
configId styleValue 一个对象,包含样式值和配置中指定的默认样式值

styleValue

{
      value: string | object | bool | number,
      defaultValue: string | object | bool | number
    }
    

styleValue 对象同时提供用户选择的样式值和配置中指定的默认值。valuedefaultValue 的类型取决于样式元素。

字段 类型 说明
value string OR object OR bool OR number 根据用户在属性面板中所做的选择返回的样式元素值
defaultValue string OR object OR bool OR number 可视化图表配置中指定的样式元素的默认值

interactionsById

{

    }
    

interactionsById 对象提供互动数据(按 interactionId 可视化图表配置编入索引)。

索引 类型 说明
configId interaction 一个对象,包含与互动相关的数据

interactionField

{
      value: object(interactionValue),
      supportedActions: array(InteractionType)
    }
    

interactionField 对象包含由配置中指定的 supportedActions 组成的数组,以及用户针对该互动选择的值。

字段 类型 说明
value string OR object OR bool OR number 根据用户在属性面板中所做的选择返回的样式元素值
supportedActions Array<InteractionType> 该互动支持的操作,具体在配置中指定

interactionValue

interactionValue 对象提供用户针对该互动类型选择的值。如果 data 键存在,InteractionData 对象反映过滤器的当前状态。如果 data 键不存在,则表示可视化图表当前未配置为过滤器。

{
      type: enum(InteractionType)
      data: object(interactionData) | None
    }
    
字段 类型 说明
type enum(InteractionType) 用户选择的 InteractionType
data object(InteractionData) 与过滤器的当前状态相关的数据。如果过滤器当前被清除,则此键不存在。

theme

{
      fillColor: {
        color: string,
        opacity: number
      },
      fontColor: {
        color: string,
        opacity: number
      },
      accentFillColor: {
        color: string,
        opacity: number
      },
      accentFontColor: {
        color: string,
        opacity: number
      },
      fontFamily: string,
      accentFontFamily: string,
      increaseColor: {
        color: string,
        opacity: number
      },
      decreaseColor: {
        color: string,
        opacity: number
      },
      gridColor: {
        color: string,
        opacity: number
      },
      seriesColor: [
        {
          color: string,
          opacity: number
        }
      ]
    }
    

themeStyle 对象用于向可视化图表传递报告主题背景信息。

字段 类型 说明
fillColor object 一个格式为 {color: string, opacity: number} 的对象
fontColor object 一个格式为 {color: string, opacity: number} 的对象
accentFillColor object 一个格式为 {color: string, opacity: number} 的对象
accentFontColor object 一个格式为 {color: string, opacity: number} 的对象
fontFamily string 一个描述字体系列的字符串
accentFontFamily string 一个描述强调字体系列的字符串
increaseColor object 一个格式为 {color: string, opacity: number} 的对象
decreaseColor object 一个格式为 {color: string, opacity: number} 的对象
gridColor object 一个格式为 {color: string, opacity: number} 的对象
seriesColor Array<object> 一个数组,由格式为 {color: string, opacity: number} 的对象组成

tablesById

{
      "DEFAULT": object(tableObject),
      "COMPARISON": object(tableObject) | undefined
    }
    

tableObject 用于为每一行提供标题和数据信息。“DEFAULT”将始终返回数据;只有当用户为数据配置了比较行时,才会填充“COMPARISON”。

dscc.tableFormatdscc.objectFormat 之间的唯一区别在于 tableObject 的格式。

字段 类型 说明
"DEFAULT" object(tableObject) OR Array<objectRow> 与用户添加到可视化图表的数据相关联的 tableObject
"COMPARISON" object(tableObject) OR Array<objectRow> 日期比较数据相关联的 tableObject(如果适用)

tableFormat 参考

tableObject

{
      headers: array(object),
      rows: array(array)
    }
    
字段 类型 说明
headers Array 一个由字段对象组成的数组。这些字段对象还具有与配置中的 ID 相对应的 configId 属性。
rows Array<Array> 一个由数组组成的数组:其中的每个数组都是一行数据

tableFormat 数据示例

下面是将 dscc.subscribeToData() 与选项 dscc.tableFormat 配合使用时返回的 data 示例。

{
      "tables": {
        "DEFAULT": {
          "headers": [{
            "id": "qt_ky8sltutsb",
            "name": "dimension",
            "type": "TEXT",
            "concept": "DIMENSION",
            "configId": "configId1"
          }, {
            "id": "qt_b5bvmtutsb",
            "name": "second dim",
            "type": "TEXT",
            "concept": "DIMENSION"
            "configId": "configId1"
          }, {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC",
            "configId": "configId2"
          }],
          "rows": [
            ["Week 4", "lm", 55]
          ]
        },
        "COMPARISON": {
          "headers": [{
            "id": "qt_ky8sltutsb",
            "name": "dimension",
            "type": "TEXT",
            "concept": "DIMENSION",
            "configId": "configId1"
          }, {
            "id": "qt_b5bvmtutsb",
            "name": "second dim",
            "type": "TEXT",
            "concept": "DIMENSION"
            "configId": "configId1"
          }, {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC",
            "configId": "configId2"
          }],
          "rows": [
            ["Week 5", "no", 123]
          ]
        }
      },
      "fields": {
        "configId1": [
          {
            "id": "qt_ky8sltutsb",
            "name": "week",
            "type": "TEXT",
            "concept": "DIMENSION"
          },
          {
            "id": "qt_b5bvmtutsb",
            "name": "textId",
            "type": "TEXT",
            "concept": "DIMENSION"
          }
        ],
        "configId2": [
          {
            "id": "qt_m9dtntutsb",
            "name": "orders",
            "type": "NUMBER",
            "concept": "METRIC"
          }
        ]
      },
      "style": {
        "nodeColor": {
          "value": {
            "color": "#000000"
          }
        }
      },
      "theme": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }
    

objectFormat 参考

objectRow

{
      configId1: array(string | bool | number),
      configId2: array(string | bool | number)
    }
    
字段 类型 说明
configId array 由与特定配置 ID 相关联的值组成的数组

objectFormat 数据示例

下面是将 dscc.subscribeToData() 与选项 dscc.objectFormat 配合使用时返回的 data 示例。

{
      "tables": {
        "COMPARISON": [
          {
            "configId1": ["Week 5", "cd"],
            "configId2": [123]
          }
        ],
        "DEFAULT": [
          {
            "configId1": ["Week 1", "ab"],
            "configId2": [24]
          }
        ]
      },
      "fields": {
        "configId1": [
          {
            "id": "qt_h6oibrb6wb",
            "name": "time of day",
            "type": "TEXT",
            "concept": "DIMENSION"
          },
          {
            "id": "qt_i6oibrb6wb",
            "name": "day",
            "type": "TEXT",
            "concept": "DIMENSION"
          }
        ],
        "configId2": [
          {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC"
          }
        ]
      },
      "style": {
        "nodeColor": {
          "value": {
            "color": "#000000"
          }
        }
      },
      "theme": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }