【译】Tim Rose 的kibana插件教程-字段格式化插件-CSDN博客

kibana官方没有插件的开发教程，Tim Rose的教程写的十分详尽，也是官方推荐的。由于这个系列的教程是英文版的，且基于kibana4，近日需要做kibana的开发，硬啃下这些教程之后，虽然这些教程比较古老，很多代码不能用了，但是开发思想还是通用的。记录下来，留下个爪。由于本人水平有限，错漏的地方欢迎大家指出。

原文链接：www.timroes.de/writing-kib…

原文标题Writing Kibana 4 Plugins – Field Formatters

你需要先读基础篇，才能开始本章节的学习。

在前面章节的教程中，我们专注于自定义可视化插件的编写。除了可视化插件，kibana还有其他的扩展点，其中一个就是字段格式化插件，任意一个索引pattern都可以被设置为使用该字段格式化插件来格式化任意一个字段，当显示该字段的时候，该字段格式化插件就可以将他显示为任意格式，而不仅仅是直白的数据。

kibana也自带了一些字段格式化器（比如把数字显示为颜色），本章节的教程，会指导你怎么样写一个字段格式化插件。我们会创建一个 Trend 格式化插件。他会在数字或者百分数字段的后面显示一个上箭头或者下箭头，根据数据是正或者负。这个字段格式化器可以被用在那些代表一个趋势的字段上面。和之前一样，插件的代码可以在GitHub上面找到：

timroes/tr-k4p-fieldformatters

注册一个新的字段格式化插件

注册一个字段格式化器，跟注册一个可视化插件是一样的。在插件中添加一个新的数组到index.js的uiExports下：

// Rest of file stripped (see GitHub for full file)
uiExports: {
  fieldFormats: ['plugins/tr-k4p-fieldformatters/trend']
}
复制代码

这就注册了trend.js到插件的public文件夹下

bug注意 在当前的kibana（ Kibana 4.4.1）发布版本中，fieldFormats数组还没有被正确使用，替代的办法是，需要把你的字段格式化插件放在visTypes数组下。由于trend.js只需要被合适的注册，所以index.js出现在哪个数组并不重要。在issue #6040 查看他的解决进度。

创建字段格式化插件

我们需要在插件public文件加下创建trend.js（跟可视化插件是一样的）。内容如下：

function TrendProvider(Private) {

  var _ = require('lodash');
  var FieldFormat = Private(require('ui/index_patterns/_field_format/FieldFormat'));

  _.class(Trend).inherits(FieldFormat);
  function Trend(params) {
    Trend.Super.call(this, params);
  }

  Trend.id = 'tr-trend';
  Trend.title = 'Trend';
  Trend.fieldType = [
    'number',
    'percentage'
  ];

  Trend.prototype._convert = function(value) {
    // TO BE DONE
  };

  return Trend;
}

require('ui/registry/field_formats').register(TrendProvider);
复制代码

文件包含了一个简单的provider函数，用来创建formatter类。在我们的案例中，我们叫他TrendProvider。这个函数在最后一行的地方被注册到了字段格式化注册处。

在provider函数的内部，我们做了以下工作：

从ui/index_patterns/_field_format/FieldFormat继承了FieldFormat类，就是上面用lodash克隆的那几行。

给Trend类设置了一些属性，用来设置我们的字段格式化插件：

id，字段格式化插件的唯一标记，应当尽可能唯一，因为kibana是通过这个字段来引用这个插件的，所以用一个带有前缀的id是百利无一害的，推荐使用个人或者公司的名称做id前缀。
title，是在kibana为字段设置字段格式化插件的时候，显示的名称。
fieldType ，是一个数组，指明这个插件能格式化什么类型的字段。在kibana设置字段格式化插件的地方，如果该插件能格式化这个字段类型，那么就会被显示出来。这个数组合法的值有：number, boolean, date, ip, attachment, geo_point, geo_shape, string, murmur3 (Murmur3 插件哈希), unknown (unknown 字段类型).

实际进行类型转换的是在_convert函数，我们很快就会到这一步了。

最后，provider需要把刚刚创建的字段格式化类返回。

格式化字段值

实际的字段格式化工作是在_convert函数中完成的，这个函数的第一个参数是这个字段的值，把你想显示的东西从函数中返回即可。在我们Trend格式化插件的场景中，我们做以下的格式化工作：

Trend.prototype._convert = function(value) {
  return (value > 0) ? value + ' ↑' : value + ' ↓';
};
复制代码

为了方便，我们没有考虑0的情况，只是根据值的正负，简单的添加了上箭头或者下箭头。

如果你的插件现在被正确加载了，你可以去任意一个kibana的索引设置中，设置一个数字或者百分数，那你就可以看见你的Trend字段格式化插件出现在你的格式化可选项当中，如果你选了这个格式化插件作为这个字段的格式化插件，那任何时候这个字段显示的时候，就可以在值的后面看见上箭头或者下箭头了。

无论函数返回什么都会被当做文本显示，html片段是不被允许的。但是这是不够的，有些场景中需要渲染html，例如图片格式化插件，或者颜色格式化插件等，为了能够渲染html，我们可以用一个对象来替代刚才的函数，这个对象有两个属性，html和text:

Trend.prototype._convert = {
  text: function(value) {
    // Return a textual representation of the value
  },
  html: function(value) {
    // The return value of this function can contain HTML, which will be rendered.
  }
};
复制代码

text函数和上面的直接把_convert声明成一个函数是一样的，html函数的返回值可以包含html片段，会被正确地渲染。

html函数在kibana能够渲染html的地方会被调用，（例如发现栏，可视化插件，等几乎任何地方），text函数在几个html不能被正确渲染的地方调用（比如在仪表盘上使用filter的时候，filter bar上显示的值就是文本）。

html函数的第二个参数是这个字段本身，这个参数可以用来获取一些这个字段本身的一些信息，当你在格式化的时候。例如field.type可以获得这个字段原来的类型（当你支持多种类型的时候）。值得注意的是，这个值可能会是null或者undefined，当kibana不能正确的获取他的字段类型的时候，例如在显示一个聚合数据的时候。这第二个参数对text函数来说是不可用的。

查看完整的例子，参考GitHub上的trend.js 。