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 對應的字串
互動	`enum(InteractionType)`	向 Looker Studio Studio 說明互動
資料	`object(InteractionData)`	提供互動所需的資料

`InteractionType`

目前唯一有效的 InteractionType 是 FILTER。

名稱	類型	說明
dscc.InteractionType.FILTER	列舉	說明 `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))
}

欄位	類型	說明
概念	`Array`	`fieldIds` 陣列
values	`Array<Array>`	資料值的巢狀陣列。每個子陣列的長度應與 `concepts` 陣列相同。子陣列中的每個值都對應至維度值。

範例 interactionData：

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

使用上述 interactionData 時，dscc.sendInteraction 等同於下列 SQL 陳述式：

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

clearInteraction()

clearInteraction() 函式會將訊息傳送至 Looker Studio，清除這個視覺化效果先前設定的篩選器。

參數：

名稱	類型	說明
actionID	`string`	與設定中的 actionId 相對應的字串
互動	`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` 傳回的資料。
選項	`object`	定義所需的資料傳回格式

選項物件如下所示：

{
  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`

這是傳遞至 callback 的物件，並已向 dscc.subscribeToData 註冊。以下是 dscc.objectFormat 和 dscc.tableFormat 共用的欄位。

{
  fields: object(fieldsByConfigId),
  style: object(styleById),
  interactions: object(interactionsById),
  theme: object(themeStyle),
  tables: object(tablesById),
  dateRanges: object(dateRangesById)
}

欄位	類型	說明
欄位	`object(fieldsByConfigId)`	物件，包含依 configId 建立索引的欄位
style	`object(styleById)`	物件，其中包含依 configId 建立索引的樣式物件
互動次數	`object(interactionsById)`	包含互動物件的物件
主題	`themeStyle`	themeStyle 物件，內含報表的主題樣式資訊
資料表	`object(tablesById)`	包含 tableObjects 的物件
dateRanges	`object(dateRangesById)`	包含 dateRanges 的物件

fieldsByConfigId

{
   configId: array(field)
}

fieldsByConfigId 物件包含以視覺化設定中定義的「id」為索引的欄位物件陣列。這個物件中，每個設定檔定義的 dataField 都會對應一個項目。

欄位	類型	說明
configId	`Array<field>`	與 dataField 相關聯的欄位陣列

欄位

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

field 物件提供使用者在屬性面板中選取的欄位相關資訊。

欄位	類型	說明
id	`string`	系統為欄位產生的 Looker Studio ID
名稱	`string`	使用者可判讀的欄位名稱
說明	`string`	欄位說明
類型	`enum(fieldType)`	欄位的 semanticType
概念	`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
}

欄位	類型	說明
類型	`enum(InteractionType)`	使用者選取的 InteractionType
資料	`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)
}

欄位	類型	說明
標頭	`Array`	欄位物件的陣列。這些欄位物件另外還有 `configId` 屬性，對應於設定中的 ID。
列	`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	陣列	與特定設定 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"
      ]
    }
  }
}

Looker Studio 社群元件 (dscc) 程式庫參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

API 總覽

getWidth()

使用getWidth()

getHeight()

使用getHeight()