【譯】Tim Rose 的kibana外掛教程-欄位格式化外掛

atxiaoxian發表於2019-05-04
ROS

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 。

下一步

欄位格式化可以更復雜多樣。給使用者提供了自定義欄位的格式的功能。如果你想要建立一個更復雜的欄位格式化外掛，我建議你參考一下kibana現有的格式化外掛。他們當中的一些包含了帶有設定的很複雜的實現和（例如 Color 或者 Date 式化外掛）。

如果你有任何問題，歡迎在評論區提出，聯絡我或者在elasticsearch的官方論壇上提出

相關文章