highchartsのAPIを拡張する

はじめに

以前の記事でhighchartsの紹介＆技術メモの記事を書きました。
今回は、highchartsで実装されているAPIを拡張するやり方を紹介したいと思います。

というのも、拡張するには、highchartsのソースを確認する必要があったため、
自分の備忘録兼他の方へ参考になればと思い、この記事を書くことに至りました。

ちなみに今回のAPIというのは、APIリファレンスのツリーに表示されている、
以下のようなAPIのことを指します。

• series
• tooltip
• xAxis
• yAxis
  etc...

公式サイトの見解

公式サイトで記述されている機能拡張のことざっくり説明すると以下になります。

• APIリファレンスに公開しているAPIを拡張できますよ。
• ただし、一部のAPIは公開していないので、highcharts.src.jsを参照してね。

APIリファレンスで公開していないAPIは直接ソースを調べろってことか。。。
有償ライブラリなら、そういうところも一般公開して欲しかったなあ。。。
それとも、非営利目的（無償）で使用している人向けに少しサポートを控えめにしているのか。。。

拡張の方法

拡張の方法は、公式サイトで記述されている機能拡張の一番下に記述されています。
（EXAMPLE EXTENSIONと太字で記載されている部分です。）

公式サイトでは、ツールチップの機能を拡張した実例を記載しています。
実例のコードを説明用に日本語に置き換えたコードが以下となります。

(function (H) {
  H.wrap(H.プロパティ名.prototype, 'API名', function(元の関数){
    元の関数.apply(this);
  });
}(Highcharts));

機能名

TooltipやXAxisなどといったプロパティの名前を記載します。
どこを参照するかというと、APIリファレンスの左ツリーです。

Highcharts.chart({のを下にだら〜と書き綴ってあるプロパティ名のことです。
画像上では、小文字始まりですが、大文字始まりに書き換えれば大体OKです。

• series　→　Series
• tooltip　→　Tooltip
• xAxis　→　XAxis
• yAxis　→　YAxis

てな感じです。

API名

機能名に紐づき、拡張したいAPI名を記述します。
今回は、公式サイトの機能拡張デモ時に使用されているTooltip.hideを
highcharts.src.jsから見つける、ということをやってみましょう。

highcharts.src.jsはこのURLから、
以下のHIGHCHARTS n.n.nをクリックすることで
ダウンロードすることができます。（会員登録不要、無償です。）

ダウンロードしたら、ソースを開き、以下の手順でソース内を検索してみてください。

1. H.Tooltip.prototypeで検索
2. H.Tooltip.prototypeブロック内からhide:で検索

すると、拡張目当てであるAPIにたどり着くことができます。
たどり着いたAPIはこんな感じです。

/**
 * Hide the tooltip
 */
hide: function(delay) {
    var tooltip = this;
    // disallow duplicate timers (#1728, #1766)
    clearTimeout(this.hideTimer);
    delay = pick(delay, this.options.hideDelay, 500);
    if (!this.isHidden) {
        this.hideTimer = syncTimeout(function() {
            tooltip.getLabel()[delay ? 'fadeOut' : 'hide']();
            tooltip.isHidden = true;
        }, delay);
    }
},

今回はもともとhideというAPI名を知っていたからこのような検索方法でたどり着くことができましたが、
本来は「〜したい」という目的があり、そこから拡張対象であるAPI名を探す、という手順になるかと思います。

その場合は、先ほど試した1,2の手順の1「H.Tooltip.prototypeで検索」でブロックを見つけ、
そのブロック内をスクロールしながら、お目当てのAPI名を探す→拡張してみるということをやらねばなりません。
（他に方法があったら教えてください。。。）

API名公開してほしいなあ。。。

元の関数

元の関数が引数として渡されます。
APIの機能自体を無効にしたい場合は元の関数.apply(this);しなければOKです。
例えば、Tooltipを表示したままにした場合は、以下のようなコードで実現することが可能です。

(function (H) {
  H.wrap(H.Tooltip.prototype, 'hide', function(defaultFunc){
    //defaultFunc.apply(this);
  });
}(Highcharts));

おわり

おわりです。
拡張関連で他に情報ありましたら、是非是非連絡いただけると助かります！