Kengo's blog

Technical articles about original projects, JVM, Static Analysis and TypeScript.

goog.ui.Componentの継承で気をつけるべきこと一覧

javascript google-closure

基本

インスタンスの状態

  • クラスフィールド（static変数）にインスタンスの状態を入れない。
  • インスタンスフィールドはprivateにする。
  • 親クラスのフィールドには触れない。

DOM要素の操作

  • DOM要素を指定する際にはIDではなくclassやカスタムdata属性などを使う。
    • IDは、コンポーネントが画面に常に一つしか存在しないことを保証できる時のみ利用する（1つの画面に2つ以上同じIDを置けないので）。
    • Closure Libraryはclassによる要素検索メソッドを多数提供しているので、classを使うことが望ましい。
  • 自分自身のDOM要素に含まれるDOM要素のみ触ることが望ましい。
    • goog.dom.getElementByClass() などgoog.dom名前空間にあるメソッドやDomHelperのメソッドよりも、 this.getElementsByClass() などgoog.ui.Componentに用意されたメソッドを使うことが望ましい。

各メソッドで気をつけること

コンストラクタ

  • 必ずgoog.base(this, opt_domHelper)する。DomHelperは省略して良いが、引数で受け取る癖をつけて統一感を持たせる。
  • この時点ではDocumentに入っていない状態かつ自分自身のDOM要素がない状態。DOMの更新は控える。
  • 子コンポーネントのインスタンスは極力この時点で作成する。あるいはコンストラクタ引数として受け取る。
  • this.addChild(childComponent)は親子でライフサイクルを統一するためにも効果的。これによって自身がdisposeされたタイミングで自動的に子コンポーネントもdisposeされるようになる。何らかの理由によりthis.addChild()できない場合はthis.registerDisposable(anotherComponent)しておくと良い。
/**
 * @constructor
 * @extends {goog.ui.Component}
 * @param {goog.dom.DomHelper=} opt_domHelper
 */
my.ui.Component = function(opt_domHelper) {
  goog.base(this, opt_domHelper);
  this.addChild(new my.ui.ChildComponent(this.getDomHelper()));
};
goog.inherits(my.ui.Component, goog.ui.Component);

createDom()

  • 必ずthis.setElementInternal(element)する。
/** @override */
my.ui.Component.prototype.createDom = function() {
  var element = this.getDomHelper().createDom(goog.dom.TagName.DIV, { 'data-foo': 'bar' });
  this.setElementInternal(element);
};

canDecorate()

  • decorateできるDOM要素に制限がある場合は、ここでそのチェックを行う。
  • falseを返した時のエラーメッセージ（goog.ui.Component.Error.DECORATE_INVALID）は汎用的なものなので、decorateに適さない理由をデバッグログに出しておくと良い。
/** @override */
my.ui.Component.prototype.createDom = function(element) {
  return element.tagName === goog.dom.TagName.DIV;
};

decorateInternal()

  • 必ずthis.setElementInternal(element)する。またはgoog.base(this, 'decotateInternal', element)でも良いが、特に親クラス実装を呼び出す必要性はない。
/** @override */
my.ui.Component.prototype.decorateInternal = function(element) {
  this.setElementInternal(element);
};

enterDocument()

  • まずgoog.base(this, 'enterDocument')してから、自クラス固有の処理を行う。
  • goog.base(this, 'enterDocument')は必ず呼び出すこと。
  • イベントのlistenはgoog.events.listen()ではなくthis.getHandler().listen()によって行う。これによってexitDocument時に手動でunlistenをする必要がなくなる。
/** @override */
my.ui.Component.prototype.enterDocument = function() {
  goog.base(this, 'enterDocument');
  this.getHandler().listen(this.getElement(), goog.events.EventType.CLICK, function(event) { ... });
};

exitDocument()

  • まず自クラス固有の処理を行ってから、goog.base(this, 'exitDocument')を呼び出す。
  • goog.base(this, 'exitDocument')は必ず呼び出すこと。
  • enterDocument時に自身や他のオブジェクトに加えられた変更があれば、これを巻き戻す。ただしthis.getHandler().listen()で作成されたイベントハンドラは親クラス実装で自動的にunlistenされるので気にする必要はない。
/** @override */
my.ui.Component.prototype.exitDocument = function() {
  // do some operation if we need

  goog.base(this, 'exitDocument');
};

disposeInternal()

  • まず自クラス固有のクリーンアップ処理を行ってから、goog.base(this, 'disposeInternal') する。
    • 自クラス固有の処理を先に行うとdispose()実行時に、自クラス固有のdisposeInstance→自クラス固有のexitDocument→親クラスのexitDocument→親クラスのdisposeInstanceの順に時に処理が行われることになり、exitDocumentがdisposeInstanceに遅れて実行されてしまう。
    • 公式に推奨されている。
  • goog.base(this, 'disposeInternal')は必ず呼び出すこと。
  • インスタンスフィールドにある他のオブジェクトへの参照をnull代入あるいはdelete演算子により断ち切ること。
  • this.isDisposed()が真かどうかは気にしなくて良い（偽であることを前提にして良い）。dispose()がthis.isDisposed()が偽の時のみdisposeInternal()を呼び出してくれる。
/** @override */
my.ui.Component.prototype.disposeInternal = function() {
  goog.base(this, 'disposeInternal');

  // do some operation if we need
};

getContentElement()

  • 子コンポーネントを追加するためのDOM要素がthis.getElement()と異なる場合のみ、このメソッドをoverrideする。
/** @override */
my.ui.Component.prototype.getContentElement = function() {
  return this.getRequiredElementByClass('container');
};

継承してはいけないメソッド

  • setElementInternal()
    • JSDocに Considered protected and final と明記されている
  • dispose()
    • 代わりに disposeInternal() を継承する
  • decorate()
    • 代わりに decorateInternal() を継承する
  • render(), renderBefore()
    • 代わりに createDom() を継承する
  • その他、継承する必要がないもの（ドキュメントには明記されていないが、これら標準実装に手を加える必要性はないものと思われる）
    • getElement()
    • getElementBy...()
    • getParent()
    • getRequiredElementByClass()
    • wasDecorated()
    • 子コンポーネントを扱うメソッド全般

参考資料

  1. goog.ui.Component のはぐれかた
  2. http://docs.closure-library.googlecode.com/git/class_goog_ui_Component.html
  3. GitHub - google/closure-library: Google's common JavaScript library