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	对该字段的说明
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 对象提供用户选择的样式值和配置中定义的默认值。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"
      ]
    }
  }
}