ProtoViewLogic: collectElements()

対象の DOM 要素から特定条件を満たす要素を収集します。

この関数は引数 rootElement がプロミスでなければ同期関数、プロミスであれば非同期関数です。

構文

protoViewLogic.collectElements(rootElement) => object | Promise<object>
protoViewLogic.collectElements(rootElement, id1, id2, ...) => object | Promise<object>

引数

  • rootElement: Element

    収集対象の要素を子孫に含む DOM 要素または解決時に要素を返すプロミスです。

  • idsForElementsToBeCollected: Array<string> | undefined （省略可）

    収集対象の要素の id 属性値の集合です。

返値: object | Promise<object>

収集された要素を値とし、その id 属性値をキャメルケースに変換した文字列をキーとするプロパティを持ったオブジェクト、または履行時にそれを与える Promise です。

得られたオブジェクトは、キーが id 属性値、値が収集された要素となります。

例外

  • TypeError

    • 引数 rootElement が Element でなかった場合。

  • SyntaxError

    • 収集対象の要素の id 属性が不正な値を持つ場合。以下の条件のいずれかを満たすと不正な値となります：

      • 値に JavaScript の識別子として使用できない文字を値に含む。

      • 値にドット "." を含む。

      • 値に角括弧 "[]" が複数組含まれている。

      • 値が空文字列または未定義。

      • 対象の ProtoViewLogic のプロトタイプチェーンに同名のプロパティが存在する。

        これは id 属性値をキャメルケース変換した結果によって判断されます。

解説

この関数は収集対象の要素の id 属性値 idsForElementsToBeCollected が提供されたかどうかによって異なる動作をします。id 属性値が提供されなかった場合、この関数は以下の条件を満たす要素を収集します：

  • id 属性が定義されている
  • data-ui-component カスタムデータ属性が定義されている

ここでカスタムデータ属性 data-ui-component は収集対象の要素に対するマーカとして機能します。

収集対象の id 属性値が提供された場合、この関数は提供された id 属性値に一致する id 属性値を持つ要素を収集します。

const vl = new ProtoViewLogic();

const textarea = document.createElement("textarea");
const field = document.createElement("input");
const button = document.createElement("button");

// id のみを設定する
textarea.setAttribute("id", "textarea");

// data-ui-component のみを設定する
field.setAttribute("data-ui-component", "");

// id と data-ui-component を設定する
button.setAttribute("id", "button");
button.setAttribute("data-ui-component", "");

// rootElement を作成
const div = document.createElement("div");
div.append(textarea, field, button);

vl.relateElements({ div });

// id と data-ui-component を持つ Element を収集する
const collected = vl.collectElements(div);

// button のみ収集された
console.log([...collected.keys()]);
// => [ "button" ]

// 一致した id を持つ要素を収集する
console.log([...vl.collectElements(div, "textarea", "button").keys()]);
// => [ "textarea", "button" ]

id 属性値が Base64 形式で符号化されている場合、元の文字列へ復号されます。

また、id 属性の値がケバブケース[^kebab-case]の場合、キャメルケース[^camel-case]へ変換した文字列をキーとします。