Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

自定义可视化 API 2.0 参考文档

调用 looker.plugins.visualizations.add 函数是进入 Visualization API 的入口点。此函数接受一个可视化对象，该对象完全定义了您的自定义可视化图表。

以下是一个可视化图表示例：

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

环境

由于 Visualization API 是纯 JavaScript，因此您可以使用任何 JavaScript 库来可视化您的数据。

您的 JavaScript 代码将在沙盒 iframe 中运行，与您的 Looker 实例分开。不过，自定义可视化图表的作者有责任确保他们编写的代码是安全的。

与所有 Web 开发一样，支持不同的 Web 浏览器（Chrome、Edge、Firefox）有时可能会出现问题。Visualization API 适用于 Looker 支持的所有浏览器，但您有责任确保浏览器支持您的自定义代码。例如，使用 ES6（例如 let 或 ()=>）在大多数浏览器中都可以正常运行，但在 IE11 中或使用 PhantomJS 呈现 PDF 时可能会导致失败。

安装

您可以通过使用“管理”>“平台”>“可视化图表”表单定义清单来安装自定义可视化图表。清单包含一个唯一的字符串 ID、一个人类可读的标签、可视化图表的 URI，以及指向您需要的任何依赖项（例如 d3、jQuery、下划线）的链接。

自定义可视化图表应作为 HTTPS 内容在 Looker 外部提供。如果您要从第一个版本的自定义可视化图表 API 进行迁移，则您的 looker/plugins/visualizations 目录中可能包含文件。此位置仍然可以访问，并且可以提供指向可视化图表的相对路径，但我们建议您将内容迁移到其他位置。由于 /plugins 目录不在共享文件系统中，因此集群环境将无法在所有节点上访问您的可视化图表文件。

可视化对象

可视化对象使用以下必需属性、可选属性和添加的属性。

必需属性

create 函数

此函数在您的可视化图表首次绘制在页面上时调用一次。它用于设置您希望可视化图表始终可用的任何内容。您可以加载库，也可以创建一组您稍后将使用的元素和控件。

详细了解 create 函数 →
updateAsync / update 函数

每当可视化图表的状态可能需要更改时，都会调用此函数。它始终在 create 之后调用，并且可能会被多次调用，因此应尽可能快。

调用此函数的原因有很多，但通常是在要可视化的查询发生更改、配置选项发生更改或可视化图表大小发生更改时。

此函数具有同步版本和异步版本：emdash；您只需指定一个。（同时定义两者是错误的。）由于 iframe 的性质，异步方法对于 PDF 呈现更可靠。

详细了解这些 update 函数 →

可选属性

options 对象

一个对象，详细说明了用户可以在可视化图表上设置的选项。

详细了解如何公开配置界面 →
destroy 函数尚未在 API V2 中实现

在可视化图表从页面中移除之前调用的函数。使用此函数清理任何事件监听器或其他状态。例如，如果用户关闭窗口，则可能永远不会调用此函数。

添加的属性

在可视化图表传递给 looker.plugins.visualizations.add 后，Looker 会自动将以下属性添加到您的对象。您可以在 create、update、updateAsync 和 destroy 函数的上下文中通过使用 this 来引用它们。

addError 函数

可视化图表代码可能会调用此函数，以告知界面显示出错提示而不是可视化图表。它接受一个 error 对象。

添加错误后，该错误将保持可见，直到调用 clearErrors。

示例：
```
this.addError({
    title: "Two Dimensions Required",
    message: "This really great visualization requires two dimensions."
});
```
clearErrors 函数

可视化图表代码可能会调用此函数，以清除使用 addError 添加的任何错误。

示例：
```
this.clearErrors();
```
trigger 函数

可以调用此函数来触发可视化图表之外的事件。

详细了解事件 →

示例：
```
this.trigger("limit", [20]);
```

`create` 函数

create 函数将传递两个参数：element 和 config。

create: function(element, config){
  // Your update code here.
},

参数

element DOMElementDOMElement

一个 DOM 元素，表示用于呈现可视化图表的容器。
config 对象

一个对象，表示用户为此图表设置的任何配置选项的值。

示例：{my_configuration_option: "User Value"}

`updateAsync` 和 `update` 函数

更新可视化图表的首选方法是 updateAsync 方法。此方法允许可视化图表执行异步操作，例如加载文件或发送 Web 请求。

此版本的函数有一个额外的参数，即在呈现完成后要调用的回调：

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

在可视化图表呈现完毕后提醒 Looker，可让 Looker 优化 PDF 呈现，并确保正确捕获可视化图表的图片。

一些较旧的可视化图表使用 update 函数。此函数仍然有效，但不是首选方法，因为使用此函数意味着在可视化图表完全呈现后，Looker 不会收到提醒。update 函数将传递五个参数：

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

参数

data 数组

一个行数组，表示查询中的当前数据。可能为 null。

每一行都是一个对象，其键表示字段名称，值表示“单元格”对象。以下是有关处理单元格对象的详细信息。
element DOMElementDOMElement

一个 DOM 元素，表示用于呈现可视化图表的容器。
config 对象

一个对象，表示用户为此图表设置的任何配置选项的值。

示例：{my_configuration_option: "User Value"}
queryResponse 对象

一个对象，表示有关当前查询的元数据，例如有关字段的元数据。可能为 null。
details 对象

有关当前呈现上下文的详细信息。包含有关图表呈现原因以及发生更改的信息。通常，此信息仅在高级情况下使用。

对于使用新信息中心体验的 Looker 信息中心内的交叉过滤条件，允许的属性包括 crossfilterEnabled 和 crossfilters。

print 属性可以与 done 函数结合使用，以改进自定义可视化图表的 PDF 呈现，尤其是包含动画的自定义可视化图表。例如：
```
if (details.print) {
        done();
}
```
done 函数

一个回调，用于指示可视化图表已完全呈现。如果您的可视化图表需要执行异步调用或需要呈现为 PDF，则调用此函数尤为重要。

呈现数据

Looker 在 LookML 中提供了一组丰富的数据格式设置工具，可用于自定义数据点的外观和行为。这些工具包括字段级 LookML 设置，例如自定义值格式、HTML、钻取链接和数据操作。

单元格具有 value 属性，这是在所有情况下都存在的唯一属性。此属性是一种 JavaScript 类型，与单元格所属的字段的类型相匹配。但是，直接将 value 属性插入 HTML 或 SVG 并不安全，因为没有执行 HTML 转义，并且某些字段值是复杂的 JavaScript 对象或数组，它们将以不理想或令人困惑的方式呈现。

为了确保所有可视化图表都以一致且安全的方式呈现这些项，我们提供了许多实用函数，用于将传递给图表的单元格元数据（在 data 中）转换为不同用途的不同表示形式。在某些情况下，单元格元数据可能会压缩或省略某些字段，而这些辅助函数可让您提供一致的体验。

所有这些辅助函数都可在全局 LookerCharts.Utils 对象上使用。

LookerCharts.Utils.textForCell(cell)

此函数接受一个单元格，并返回适合显示的单元格的字符串表示形式。它始终是一个字符串 - 此函数永远不会返回 null 或任何其他类型。
LookerCharts.Utils.htmlForCell(cell)

此函数接受一个单元格，并返回包含 HTML 的字符串。它始终是一个字符串 - 此函数永远不会返回 null 或任何其他类型。

此函数的输出经过正确转义，适合直接插入到元素的 HTML 中。当输出 HTML 适合数据时，它还会在点击时正确显示钻取菜单。
LookerCharts.Utils.filterableValueForCell(cell)

此函数接受一个单元格，并返回一个 Looker 高级过滤器语法字符串，该字符串与此单元格的值匹配。

LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

此函数接受行、数据透视表或事件，用于检查是否为可视化图表启用了交叉过滤。以下示例展示了如何向元素添加事件监听器，该监听器用于检查事件发生时是否启用了交叉过滤：

d3.select("#myElement")
.on("click", function (d) {
    if (details.crossfilterEnabled) {
            LookerCharts.Utils.toggleCrossfilter({
                row: d.row,
                event: d3.event,
            });
    } else {
      // ... handle click when cross-filtering is not enabled
    }
});

LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

此函数接受行或数据透视表，用于检查是否在自定义可视化图表中选择了该行或数据透视表。如果为 NONE，则该函数会为 CrossfilterSelection {NONE, SELECTED, UNSELECTED} 返回枚举 0；如果为 SELECTED，则返回 1；如果为 UNSELECTED，则返回 2。

以下示例有条件地将填充颜色应用于正在交叉过滤的行，如果未为该行启用交叉过滤，则应用默认颜色：
```
d3.select("#myElement")
.attr("fill", function (d) {
    const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
    if (details.crossfilterEnabled && crossfilter === 1) {
            return d.color
    } else {
            return "#DEE1E5" //Hex used for unselected elements in native visualizations
...
```
LookerCharts.Utils.openDrillMenu(options)

如果需要，htmlForCell 的输出将自动显示钻取菜单，但这可能不适合某些类型的呈现。（例如，SVG 无法呈现 HTML，但您可能希望捕获点击事件以开始钻取。）

options 对象具有以下参数：
- links 必需数组
  
  从单元格的 links 属性返回的对象数组。如果您想一次显示多个单元格的链接，可以先将这些数组连接在一起。对于自定义链接，请提供以下形式的对象数组：
```
{ label: string, type: 'drill', type_label: string, url: url }
```
- event HTML DOM 事件
  
  导致钻取事件的点击（或其他）事件。Looker 将使用此事件来确定钻取菜单的放置位置。如果您没有此事件，请尝试传递一个包含 pageX 和 pageY 坐标的对象。
示例：
```
for (var row of data) {
    var cell = row[queryResponse.fields.dimensions[0].name];
    var cellElement = myBuildElementFunction(cell);
    cellElement.onclick = function(event) {
        LookerCharts.Utils.openDrillMenu({
            links: cell.links,
            event: event
        });
    };
    // ... more visualization stuff...
}
```

呈现配置界面

options 参数是一个对象，其中的键是选项名称的任意标识符，值是描述选项相关信息的对象。

示例如下：

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

选项对象参数

option 对象具有以下基本参数、显示专用属性和组织选项。

基本参数

type 字符串

选项的数据类型。

允许的值： string（默认）、number、boolean、array
label 字符串

将向用户显示的选项的人类可读标签。
default

选项的默认值。如果未指定，则选项的值为 null。这应该是与 type 相同类型的值。
display 字符串

某些 type 值可以在界面中以不同的方式呈现。
- 当 type 为 string 时：
  
  允许的值： text（默认）、select、radio
- 当 type 为 number 时：
  
  允许的值： number（默认）、range
- 当 type 为 array 时：
  
  允许的值： text（默认）、color、colors
placeholder 字符串

对于支持它的 display 值，提供示例值或说明，以便为用户提供有关输入内容的提示。

显示专用属性

values 对象数组

当 display 为 radio 或 select 时，一个包含将在界面中列出的标签和值的数组。

数组中的每个项都应是一个包含单个键值对的对象，该键值对表示选项的标签和值。标签仅在界面中呈现；在呈现时间，您只会收到值。

示例：
```
values: [
    {"Center": "c"},
    {"Left": "l"},
    {"Right": "r"}
]
```
如果 display 为 radio，则还可以为每个选项提供 description：
```
values: [
    {"Cool": "c"},
    {"Uncool": {
            value: "unc",
            description: "Only choose this if the data is very uncool."
        }
    }
]
```
max number

当 display 为 range 时，允许范围滑块选择的最大数量。
min number

当 display 为 range 时，允许范围滑块选择的最小数量。
step number

当 display 为 range 时，范围滑块的每个刻度表示的数量。

组织选项

section 字符串

对于具有许多选项的图表，用于指示选项应显示在哪个部分的标签。界面将按选项的 section 值对选项进行分组。如果只有一个部分，则不会显示部分界面。

如果您使用 section，则应为每个选项设置它。
order number

一个数字，表示选项在界面中呈现的顺序。如果指定了此数字，则选项将按此顺序排序。
display_size 字符串

一个大小类，表示选项在界面中的宽度。例如，如果您想并排显示“最小值”和“最大值”选项，可以将它们的显示大小都设置为 half。

允许的值： normal（默认）、half、third

事件

事件可以由图表触发（通常是为了响应用户互动），这些事件可以更新可视化图表或查询的属性。

可以通过对可视化对象调用 trigger 函数来触发这些事件。第一个参数始终是事件名称，第二个参数是实参数组。

this.trigger("limit", [20]);

可用事件

updateConfig

更新图表的当前配置设置。

实参：一个包含要更新的配置键的对象。未指定的键不会更改。

示例：
```
var vis = this;
$(element).find(".axis").click(function(){
    vis.trigger("updateConfig", [{axis_hidden: true}]);
});
```

limit

更新底层查询的限制：

实参：一个整数，表示查询的新限制。

var vis = this;
$(element).find(".show-all").click(function(){
    vis.trigger("limit", [500]);
});

filter

更新底层查询中过滤条件的值：

var vis = this;
$(element).find(".show-all-tommys").click(function(){
    vis.trigger("filter", [{
        field: "users.name", // the name of the field to filter
        value: "%tommy%", // the "advanced syntax" for the filter
        run: true, // whether to re-run the query with the new filter
    }]);
});

loadingStart

将可视化图表标记为正在加载。大多数情况下，这并不必要，但如果您的可视化图表从远程位置加载对象或执行长时间的计算，您可以使用此方法继续显示加载指示器。

在触发 loadingEnd 之前，它将显示为正在加载。
loadingEnd

将可视化图表标记为不再加载。
printSize（Looker 26.0 及更高版本）

允许可视化图表在将信息中心呈现为 PDF 时利用“展开表以显示所有行”选项。使用此事件可让应用了解呈现的内容的高度，并可以相应地展开信息中心图块，以便所有信息都可见以供打印。
```
  this.trigger('printSize', {
    heightExpanded: FULL_HEIGHT_IN_PIXELS
  });
```

registerOptions（Looker 5.24 及更高版本）

允许可视化图表在注册后注册其他选项：

  update: function(data, element, config, queryResponse, details){
    options = {}
    // Create an option for each measure in your query
    queryResponse.fields.measure_like.forEach(function(field) {
      id = "color_" + field.name
      options[id] =
      {
    label: field.label_short + " Color",
    default: "#8B7DA8",
    section: "Style",
    type: "string",
    display: "color"
      }
    })
    this.trigger('registerOptions', options) // register options with parent page to update visConfig
    ...
  }
});

自定义可视化 API 2.0 参考文档 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

环境

安装