APLコンポーネント（キャラクターディスプレイ）

コンポーネント（キャラクターディスプレイ）

コンポーネントは、viewportに表示されるプリミティブな要素です。

コンポーネント共通のプロパティ

コンポーネントはすべて次のプロパティをサポートしています。

プロパティ 型 デフォルト 動的 説明
description 文字列 "" ✕ このコンポーネントの任意の説明です。
bind バインドの配列 [] ✕ データバインディングコンテキストに追加する式です。
display 文字列 normal ◯ コンポーネントが画面に表示される場合に制御します。
height ディメンション auto ✕ コンポーネントに指定する高さです。
id 文字列 "" ✕ ナビゲーションおよびイベントに使用する、コンポーネントの参照名です。
maxHeight ディメンション <none> ✕ このコンポーネントの高さの上限です。
maxWidth ディメンション <none> ✕ このコンポーネントの幅の上限です。
minHeight ディメンション 0 ✕ このコンポーネントの高さの下限です。
minWidth ディメンション 0 ✕ このコンポーネントの幅の下限です。
onMount コマンドの配列 [] ✕ コンポーネントが最初に表示されたときに実行されるコマンドです。
paddingBottom 絶対ディメンション 0 ✕ このコンポーネントの下側に追加するスペースです。
paddingLeft 絶対ディメンション 0 ✕ このコンポーネントの左側に追加するスペースです。
paddingRight 絶対ディメンション 0 ✕ このコンポーネントの右側に追加するスペースです。
paddingTop 絶対ディメンション 0 ✕ このコンポーネントの上側に追加するスペースです。
type 文字列 必須 ✕ コンポーネントの型です。
when ブール値 true ✕ 評価結果がfalseの場合、このコンポーネントはインフレートされません。
width ディメンション auto ✕ このコンポーネントに指定する幅です。

デフォルト列は、プロパティのデフォルト値を示しています。すべての必須プロパティを設定する必要があります。設定しないと、コンポーネントは表示されません。

動的列は、動的に変更できるプロパティかどうかを示しています（SetValueコマンドを参照）。SetValueを使用して動的プロパティを設定すると、スタイル値はすべて上書きされます。動的プロパティの設定を解除するメカニズムはありません。

bind

コンポーネントのbindプロパティは、コンポーネントおよびその子のデータバインディングコンテキストを展開するためのものです。bindプロパティでは、現在のコンテキストを展開するデータバインディングを順序付きで指定します。バインディングには順序があり、以前のバインディングの定義を、それ以降のバインディングで使用できます。バインディング配列の各バインディングオブジェクトには、次のプロパティが含まれます。

プロパティ 型 デフォルト 説明
name 文字列 必須 このバインディングで使用する名前です。有効な名前を設定する必要があります。
value 任意 必須 このバインディングに割り当てる値です。
type 任意、ブール値、文字列、数値、ディメンション any プロパティの型です。

bindプロパティの評価は、whenプロパティとその他のプロパティとの間に行われます。バインディングは、配列の順序でデータバインディングコンテキストに追加されます。後続のバインディングでは先行するバインディングの結果を使用できます。次に例を示します：

{
  "type": "Text",
  "bind": [
    {"name":"FirstName","value":"ジャスミン"},
    {"name":"LastName","value":"スミス"},
    {"name":"Title","value":"博士"},
    {"name":"FormalName","value":"${LastName}${Title}"}
  ],
  "text": "${FirstName}さん、または${FormalName}のどちらでお呼びしますか？"
}

この例では、FormalNameの内容は、それより前に定義されたTitleとLastNameの値によって決まります。最終的にこのテキストは、「ジャスミンさん、またはスミス博士のどちらでお呼びしますか？」となります。これは例として仮に作られたものであり、実際には、FirstName、LastName、Titleの値が生データ内の要素とバインドされます。

バインドされる値は、SetValueコマンドを使用して動的に変更できます。SetValueコマンドは、コンポーネントのプロパティを変更する場合にも使用されるため、コンポーネント固有のプロパティと競合することがないよう、バインドされるプロパティの名前は大文字で始めることをお勧めします。たとえば、「myCounter」ではなく、「MyCounter」や「MY_COUNTER」のような名前にします。

display

コンポーネントのdisplayプロパティは、画面に表示されるかどうかや、レイアウトの計算に与える影響を決定します。デフォルトのディスプレイ設定である「normal」の場合、コンポーネントは通常どおりに表示されます。ディスプレイ設定が「invisible」の場合、コンポーネントは引き続きレイアウトでスペースを占有しますが、描画やイベントへの応答はしません。「none」を設定すると、コンポーネントがディスプレイ階層から完全に削除されます。レイアウトに影響はありません。

名前 説明
invisible コンポーネントは描画されませんが、スペースを占有します。イベントには応答しません。
none コンポーネントを削除します。コンポーネントはレイアウトの一部ではなくなり、イベントに応答しません。
normal 通常どおりにコンポーネントを描画します。

heightおよびwidth

width、height、minWidth、minHeight、maxWidth、maxHeightはディメンション型のプロパティです。最小幅および最小高のデフォルト値は0であり、コンポーネントは表示されない場合があります。最大幅および最大高のプロパティのデフォルト値はnoneであり、コンポーネントは自由に拡大縮小できます。widthおよびheightの値の指定がない場合は、コンポーネントの元のサイズになります。

id

階層表示で特定のコンポーネントを見つけられるように、開発者が割り当てる文字列値です。idに指定できる有効な文字は[_a-zA-Z0-9]+です。ほかのidと同じ値を使用してもかまいませんが、一意の値を割り当てることをお勧めします。

onMount

このコンポーネントがコンポーネント階層から配置される場合に実行するコマンドです。マウントコマンドは、画面の切り替えを表示するために使用します。マウント時には、event.source.valueは設定されないままです。

onMountコマンドは、ドキュメントの読み込み時にトリガーされます。コンポーネント自体が非表示である場合や画面に表示されていない場合でも、コンポーネントのonMountコマンドは常に実行されます。

生成されるイベントの形式は次のようになります。

"event": {
  "source": {
    "source": NAME,
    "handler": "Mount",
    "id": ID,          // コンポーネントのID   
    "uid": UID,        // ランタイムで生成されたコンポーネントの固有ID
    "value": null      // 値は報告されません
  }
}

イベントのsourceプロパティには、コンポーネントの名前（「Pager」、「Container」など）が設定されます。

padding

paddingの値（paddingBottom、paddingTop、paddingLeft、paddingRight）はディメンション型であり、コンポーネントの周りに追加するスペースを指定します。APL-Tでは、パディングと境界線を含めて要素の全幅と全高を計算します。padding値で相対（パーセント）ディメンションはサポートされません。paddingは絶対ディメンションで指定してください。

type

インフレートするコンポーネントを指定します。このセクションに記載したプリミティブコンポーネントのいずれか、または名前付きレイアウトを指定できます。typeプロパティの指定は必須です（唯一の必須プロパティ）。

when

trueの場合、コンポーネントをインフレートします。falseの場合は、コンポーネントとすべての子コンポーネントが無視されます。