ProtoViewLogic: defineUiComponents()

呼び出し先の ProtoViewLogic に対して Element を定義して関連付けます（relateElements() も参照）。

構文

protoViewLogic.defineUiComponents(componentDescriptors) => object

引数

• componentDescriptors: object

  各 Element または Array<Element> の記述子をプロパティに持つオブジェクトです。

  各プロパティには obejct または object の配列を指定します。 それぞれの object はプロパティ名で識別される Element または Array<Element>の記述子です。

  記述子は以下のプロパティを持ちます：

  • tagName: string

    定義する Element のタグ名を指定します

  • value: string | undefined （省略可）

    定義する Element の value 属性の値を指定します

    info

    • value の指定は attributes 内の value 属性の指定に優先します（後者の値は前者の値で上書きされます）

  • text: string | undefined （省略可）

    定義する Element の textContent を指定します

    info

    • children プロパティと併用した際、text は定義される Element の最初のノード (firstNode) として登録されます（結果として children のインデックスは 1 つずれることに注意してください）

  • children: Array<Element | string | object> | undefined （省略可）

    定義する Element の子のノードとなる要素、テキスト、または要素の記述子を指定します

    info

    • text プロパティと併用した際、定義される Element の最初のノード (firstNode) として text が先に登録され、それに続いて children の成分が追加されます（結果として children のインデックスは 1 つずれることに注意してください）

  • primary: string | undefined （省略可）

    定義する Element の data-primary カスタムデータ属性の値を指定します

    info

    • primary の指定は attributes 内の data-primary 属性の指定に優先します（後者の値は前者の値で上書きされます）

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

    定義する Element の data-active-events カスタムデータ属性を指定します

    info

    • activeEvents の指定は attributes 内の data-active-events 属性の指定に優先します（後者の値は前者の値で上書きされます）
    • string として指定した場合、カンマ区切りされたイベント種別の文字列になっていなければなりません

  • attributes: object | undefined （省略可）

    定義する Element の属性を指定します。

    定義する属性と同じ名前を持つプロパティに、設定する値を持たせたオブジェクトを指定します。

    info

    • value, primary, activeEvents プロパティの指定は attributes 内の value, data-primary, data-active-events 属性の指定に優先します（後者の値は前者の値で上書きされます）
    • attributes 内の id 属性の指定は常に無視され、記述子を持つプロパティ名 またはそれに配列の添え字を付けたものが使用されます（前者は componentDescriptors のプロパティが object の場合、後者は object の配列だった場合に使用されます）

返値: object

呼び出し先の ProtoViewLogic から関連付けの解消された要素をプロパティに持つオブジェクト（relateElements() の返値の項を参照）。

例外

• TypeError
  • 引数 componentDescriptors が 非 null のオブジェクトでなかった場合
• AggregateError
  • 以下のいずれかの例外が発生した場合、それらを集約した AggregateError が発生します：
    • TypeError: 値 componentDescriptors[component_name] が非 null のオブジェクトでなかった場合
    • TypeError: 値 componentDescriptors[component_name].tagName が文字列でなかった場合
    • TypeError: 値 componentDescriptors[component_name].value が null でも文字列でもなかった場合
    • TypeError: 値 componentDescriptors[component_name].text が null でも文字列でもなかった場合
    • TypeError: 値 componentDescriptors[component_name].children が null でも反復可能オブジェクト (iterable) でもなかった場合
    • TypeError: 値 componentDescriptors[component_name].primary が null でも文字列でもなかった場合
    • TypeError: 値 componentDescriptors[component_name].activeEvents が null でも文字列でも反復可能オブジェクト (iterable) でもなかった場合
    • TypeError: 値 componentDescriptors[component_name].attributes が null でも非 null オブジェクトでもなかった場合
    • TypeError: 記述子のプロパティ tagName がタグ名として正しくなかった場合
    • TypeError: 記述子のプロパティ activeEvents が文字列でない成分を含んでいた場合
    • TypeError: 記述子のプロパティ activeEvents が空文字列または空白のみからなる文字列を含んでいた場合
    • TypeError: 記述子のプロパティ attributes が空文字列または空白のみからなる文字列をキーとするプロパティを持っていた場合
    • TypeError: 記述子のプロパティ attributes が NaN を値とするプロパティを持っていた場合
    • TypeError: 記述子のプロパティ attributes が Symbol 型の値のプロパティを持っていた場合
    • TypeError: 記述子のプロパティ attributes が function 型の値のプロパティを持っていた場合
    • TypeError: 記述子のプロパティ children が Element でも文字列でも非 null のオブジェクトでもなかった場合

例

//  SP
const { ProtoViewLogic } = await Alier.import("/alier_sys/ProtoViewLogic.js");
//  Web
//  import { ProtoViewLogic } from "/path/to/alier/src/ProtoViewLogic.js";

const vl = new class Watcher extends ProtoViewLogic {
    async messageHandler(msg) {
        console.group(`${msg.id}+${msg.code}`);
        console.log("%cmsg.id          :", "font-weight: bold; font-family: monospace;", msg.id);
        console.log("%cmsg.code        :", "font-weight: bold; font-family: monospace;", msg.code);
        console.log("%cmsg.origin      :", "font-weight: bold; font-family: monospace;", msg.origin);
        console.log("%cmsg.target      :", "font-weight: bold; font-family: monospace;", msg.target);
        console.log("%cmsg.param       :", "font-weight: bold; font-family: monospace;", msg.param);
        console.log("%cmsg.param?.value:", "font-weight: bold; font-family: monospace;", msg.param?.value);
        console.log("%cmsg.param?.event:", "font-weight: bold; font-family: monospace;", msg.param?.event);
        console.groupEnd();
    }
};

//  paragraph, textarea, buttons を vl に関連付けられた要素として定義する。
//  paragraph は <p> 要素、textarea は <textarea> 要素を表し、buttons は <button> 要素の配列を表す。
vl.defineUiComponents({
    paragraph: {
        tagName: "p",
        text   : "this is a paragraph"
    },
    textarea: {
        tagName     : "textarea",
        value       : "default value of this textarea",
        activeEvents: "input"
    },
    buttons: [
        {
            tagName     : "button",
            value       : "ok",
            text        : "OK",
            activeEvents: "click",
            attributes  : { type: "button" }
        },
        {
            tagName     : "button",
            value       : "cancel",
            text        : "Cancel",
            activeEvents: "click",
            attributes  : { type: "button" }
        }
    ]
});

//  vl に関連付けられた要素を確認する
console.log(vl.getRelatedElements());

//  vl.paragraph の内容をログに出力する
console.log("vl.paragraph.textContent: ", vl.paragraph.textContent);

//  vl.textarea の値を変更する
vl.textarea.value = "another text input";

//  input イベントを textarea に対して送る
vl.textarea.dispatchEvent(new Event("input"));
//  ==> { id: "textarea", code: "input" } のメッセージが vl に送信される


//  OK ボタンをクリックする
vl.buttons[0].click();
//  ==> { id: "buttons", code: "click", param: { value: "ok" } } のメッセージが vl に送信される

//  Cancel ボタンをクリックする
vl.buttons[1].click();
//  ==> { id: "buttons", code: "click" , param: { value: "cancel" } } のメッセージが vl に送信される

解説

呼び出し先の ProtoViewLogic に対して引数 componentDescriptors で記述された Element を関連付けます。

この関数は document.createElement() による Element の生成とその初期化処理、初期化済みの Element の ProtoViewLogic への関連づけを一括して行う関数です。

要素の生成のみを行いたい場合、代わりに ProtoViewLogic.createUiComponents() または ProtoViewLogic.createElement() を使用できます。