Overview

概略

以下のように、CSSセレクタを使ってHTMLからノードを取得します。

u('ul#demo li')
u(document.getElementById('demo'))
u(document.getElementsByClassName('demo'))
u([ document.getElementById('demo') ])
u( u('ul li') )
u('<a>')
u('li', context)

パラメータ

第1引数は以下を指定することができます。

• CSSセレクタ。
• HTML Node。thisを渡すだけなので、イベント処理で特に便利です。
• 配列に変換出来るNodeListか、同様のオブジェクト。
• Node配列^*1)
• 他のUmbrellaインスタンス。
• HTMLフラグメント識別子。(idやnameで指定する文字)
• 未指定。

第2引数は、第1引数がCSSセレクタの場合のみ指定することができ、 第1引数のセレクタが適用される一部のDOMを指定します。 例えば、u('li', u('ul').first())では、 最初(first)のulから全てのliを探します。

^*1) 実際は["a", "b"]のように指定することができます。 しかし、この方法は公式でサポートされていないため、 いつ変更されてもおかしくありません。

idで指定する場合、u(document.getElementById('demo'))ではなく、 u('#demo')を使ってください。 内部的にはこの方法が最適化されています。 これは出来ることのほんの一例です^*2)。

*2) jQueryで$('#demo')を指定すると、内部的にdocument.getElementById('demo')を使ってDOMを取得します。 そのため、最初から$(document.getElementById('demo'))と指定する方が高速であるとされています。 一方、Umbrellaではu('#demo')が良いんだよ、という注釈だと思われます。

戻り値

Umbrellaのインスタンスを返します。 これにより、メソッドチェーンを作成することができます。

使い方

ulの全てのliを取得します。

var lis = u('ul > li');    // Same as u('ul').children('li');

全てのh*を取得して目次を作成します。

var headers = u('h1, h2, h3, h4, h5, h6');

簡単にリンクを生成します。

var link = u('<a>').addClass('main').attr({ href: '/hello' });

この方法で多様な要素を簡単に生成することができます。 例えば、シンプルな食料品リストを作るには、 (簡略化のためにES6を使用しています。)

var fruits = ['apple', 'strawberry', 'pear', 'banana'];
var list = u('<ul>').append(fruit => `<li>${ fruit }</li>`, fruits);
 
u('body').append(list);

ネイティブメソッド

このセクションはBliss.js' vanilla methodsにインスパイアされました。

多くのネイティブメソッド、ネイティブプロパティを使うことができます。 これらはそのまま.first()や、.last()を使ったり、.nodesや、ループで全ての要素に対して処理するといったことも可能です。

// .nodesの単一要素
u('h1').nodes[0].classList.add('vanilla');

// 単一要素
u('h1').first().classList.add('vanilla', 'test');

// 複数要素。order(処理順序)はjQueryと違うことに注意してください。
u('h2').each(function(el){
  el.classList.add('vanilla', 'test');
});

そして、配列の場合も似たようなものです。 u().nodesは配列なので、任意の配列メソッドを呼び出すことができます

u('h2').nodes.forEach();
var mapped = u('h2').nodes.map();
var filtered = u('h2').nodes.filter();
var good = u('h2').nodes.some();

しかし、ネイティブメソッドの代わりにUmbrellaのメソッドを使う方がいくつかの利点があります。 例えば、.addClass()vs classList.add()(ネイティブ)では、

• エラー防止 : .nodes.lengthが0の場合、 上記の単一要素の手法は失敗してしまいます。 (.first()と.nodes[0]はnullなので。)
• クロスブラウザ対応 : 複数要素を持つclassList.add()は IE10～11とAndroid4.3以下では互換性がありません。
• メソッドチェーン作成可能 : u('<div>').each(...).addClass(...);
• よりフレキシブル : .addClass()を使用して複数のクラスを指定する方法は沢山ありますが、 ネイティブでは1つの方法だけです。 クラス名を持った配列があるとして、 その配列からネイティブメソッドを使ってクラス追加するなんて考えたくもありません。 これがつまり.addClass()はフレキシブルであるということです。

u('h2').addClass('vanilla', 'test');     // 複数パラメータもOK。
u('h2').addClass(['vanilla', 'test']);   // 配列もOK。
u('h2').addClass(['vanilla'], ['test']); // 複数配列もOK。
u('h2').addClass('vanilla, test');       // スペースまたは、,(カンマ)で区切られた文字もOK。
u('h2').addClass('vanilla', ['test'], 'one, more' ); // どんな組み合わせもOK。

これらの条件がそれに応じて処理されます。 ネイティブメソッドよりも、より適切なUmbrellaのメソッドを使ったり、 必要に応じて独自のメソッドを作成しましょう。