Looker Studio 社区组件 (dscc) 库参考文档

API 简介

dscc（Looker Studio 社区组件）是一个库，用于为 Looker Studio 构建社区组件。我们在 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() 函数会向 Looker Studio 发送一条消息，其中包含过滤条件的数据。

参数：

名称 类型 说明
actionID string 与配置中的 actionId 对应的字符串
interaction enum(InteractionType) 告知 Looker Studio 交互情况
data object(InteractionData) 为互动提供必需数据

InteractionType

目前，唯一有效的 InteractionType 是 FILTER。

名称 类型 说明
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() 函数会向 Looker Studio 发送消息，以清除此可视化图表之前设置的过滤条件。

参数：

名称 类型 说明
actionID string 与配置中的 actionId 对应的字符串
interaction enum(InteractionType) 告知 Looker Studio 交互信息

使用 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() 函数会订阅来自 Looker Studio 的消息。

参数：

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

options 对象大致如下所示：

{
  transform: dscc.tableTransform | dscc.objectTransform
}

返回值：

类型 说明
function 为 callback 退订来自 Looker Studio 的后续消息

使用 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.objectFormat 和 dscc.tableFormat 之间共享的字段。

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

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 Looker Studio 为字段生成的 ID
name string 直观易懂的字段名称
description string 对该字段的说明
类型 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 对象提供用户选择的样式值和配置中定义的默认值。value 和 defaultValue 的类型取决于样式元素。

字段 类型 说明
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) 与过滤器的当前状态相关联的数据。如果过滤器当前被清除，则此键不存在。

主题

{
  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.tableFormat 和 dscc.objectFormat 之间的唯一区别在于 tableObject 的格式。

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

dateRangesById

{
  "DEFAULT": object(dateRange),
  "COMPARISON": object(dateRange)
}

dateRangesById 对象提供有关默认和比较日期范围的信息。如果没有日期范围，该对象将为空。只有用户配置了相应的日期范围时，系统才会填充 DEFAULT 和 COMPARISON。日期范围中的数据与 tablesById 中定义的默认数据和比较数据相关。

字段 类型 说明
"DEFAULT" object(dateRange) 与默认日期范围相关联的 dateRange（如果适用）。
“COMPARISON” object(dateRange) 与比较日期范围相关联的 dateRange（如果适用）。

dateRange

{
  start: string,
  end: string
}

dateRange 对象提供有关默认或比较日期范围的开始日期和结束日期的信息。

字段 类型 说明
start string 日期范围的开始日期，采用 YYYYMMDD 格式。
end string 日期范围的结束日期，采用 YYYYMMDD 格式。

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": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "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": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "interactions": {
    "onClick": {
      "value": {
        "type": "FILTER",
        "data": {
          "concepts": [
            "qt_h6oibrb6wb",
            "qt_i6oibrb6wb"
          ],
          "values": [
            [
              "Afternoon",
              "Sunday"
            ],
            [
              "Afternoon",
              "Thursday"
            ],
            [
              "Morning",
              "Tuesday"
            ]
          ]
        }
      },
      "supportedActions": [
        "FILTER"
      ]
    }
  }
}