Bone Flow #019 Image ガイド

このガイドについて

• DOC ID: DOC-0019
• UI ID: UI-019
• Component: #019 Image
• Runtime Version: 1.0.72
• DOC Version: 1.0.4

このDOCは、#019 Imageを初めて使う人が「何を設定すると、実際に何が変わるのか」まで確認できる操作ガイド兼正式仕様です。値の一覧だけでは終わらず、各Propertyを 説明 → 正式仕様 → 全許容値 → 使用サンプル → 使用結果 の順で説明します。コードブロックには「コピー」ボタンが表示され、そのまま利用できます。

このガイドでいう Runtime Default は BoneImage.normalizeValue() が未指定値へ適用する実行時初期値、Property Editor初期値 は bone-image.html の設定画面が最初に表示する値です。両者が違う場合は分けて記載します。

このガイドで使う用語

• Runtime: ブラウザ上でImageを生成・更新する BoneImage 本体。
• Property: Imageの種類、Source、配置、表示領域、状態、OUTなどを決める設定。
• Property Editor: bone-image.html の「プロパティ設定」。編集値は「変更を確定」までDraftです。
• HTML Functional Class: class="bf-image" を付け、通常のHTML画像から#019 Runtimeを利用する入口。
• Public API: HTMLだけでは表現しない高度操作をJavaScriptから実行する正式機能。
• TYPE: ICON / EMOJI / PNGなど、#019が扱う画像表現の種類。
• usage: 画像ファイルを「アイコンとして使う」か「画像として使う」かの用途。
• List Key: TYPEをどの登録済み子UIへ委譲するかを示すUI Registryのキー。
• OUT: #019 Imageから次の処理へ渡す正式出力。
• 表示領域: containerStyle で管理する画像/アイコンの外側領域。

最初に

通常の画像をHTMLから使う最小形はこれです。

<img class="bf-image" src="assets/sample.png" alt="PNGサンプル">

使用結果: bf-image が src の拡張子から TYPE=PNG を判定し、usage=image、listKey=019-bitmap として#019 Runtimeへ渡します。alt は代替テキストとして保持します。

画像の表示方法も標準CSSで指定できます。

<img class="bf-image"
     src="assets/sample.jpg"
     alt="写真サンプル"
     width="320"
     height="220"
     style="object-fit:cover; object-position:right top;">

使用結果: JPEG/JPG画像を320×220pxの表示領域で扱い、画像は領域を埋めるように cover、基準位置は右上になります。

Imageとは

#019 Imageは画像系の親Componentです。画像TYPEそのものを全部独自実装するのではなく、TYPE / List Keyを見て登録済み子UIへ処理を委譲し、共通Property、Preview、OUT、Joint、Completionを統括します。

主な責務:

• TYPE 13種類の管理
• 画像用途 icon / image の分離
• UI Registry / List Keyによる子UI委譲
• Font Awesomeは#018 Bone Iconへ委譲
• EMOJI 1,438件は#019自身で選択・表示
• 画像ファイルのドラッグ＆ドロップ / File選択
• 元画像幅・高さ、表示領域、FIT、表示率、9方向配置
• 画像アイコンのサイズ、回転、反転、Name表示
• Color Propertyを#040 ColorPickerへ委譲
• Container / Border / Shape / Padding / 配置 / Overflow / Opacity / Shadow
• Active / Disabled状態
• #002 Bone Jointによる接続イメージ
• Smoke Test / Validation / Completion
• Public API 16件による高度操作

HTML Functional Class

正式Class

一般利用向けHTML Functional Classは bf-image 1件だけです。旧方式のようにPublic APIの数だけHTML Classを作りません。

<img class="bf-image" src="assets/sample.png" alt="サンプル画像">

対応HTML要素

bf-image の通常利用は img 要素です。src を要素内Textで指定しません。

img 以外に bf-image を付けると BONE_IMAGE_HTML_CLASS_ELEMENT_UNSUPPORTED、src が空なら BONE_IMAGE_HTML_CLASS_SOURCE_REQUIRED です。

HTMLから直接指定できるもの

• src → source、拡張子/Data URLからTYPEを判定
• alt → alt
• title → title
• width / height → containerStyle.width / height
• style="object-fit:..." → fit
• style="object-position:..." → position の9方向へ変換
• style="opacity:..." → containerStyle.opacity（0〜1へ補正）
• aria-disabled="true" → disabled=true

HTMLから直接指定しないもの: usage=icon、ICON/EMOJI選択、List Key管理、displayRate、rotate、flip、ColorPickerのGradient、表示/OUT分離、Name書式、Border/Shadow詳細、Active Style、Disabled Style、Completion。これらはProperty EditorまたはPublic APIを使用します。

拡張子からのTYPE判定

HTML使用サンプル: contain

<img class="bf-image"
     src="assets/sample.png"
     alt="全体を見せる画像"
     width="320"
     height="220"
     style="object-fit:contain; object-position:center center;">

使用結果: 320×220pxの領域内に画像全体が入るように縮尺し、中央へ配置します。

HTML使用サンプル: cover

<img class="bf-image"
     src="assets/sample.jpg"
     alt="領域いっぱいに表示する写真"
     width="320"
     height="220"
     style="object-fit:cover; object-position:left top; opacity:0.9;">

使用結果: 領域を埋めるまで画像を拡大し、はみ出す部分は左上を基準に見せます。表示領域のOpacityは0.9です。

使用サンプル

ここは「仕様値の例」ではなく、実際に何をしたいかから選ぶ使用例です。すべてコピーできます。

1. PNGを普通の画像として表示

<img class="bf-image" src="assets/sample.png" alt="PNGサンプル">

使用結果: PNGとして#019へ入り、通常画像用途で表示されます。

2. Data URLを表示

<img class="bf-image"
     src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='60'%3E%3Crect width='120' height='60' rx='8' fill='%2355e6a5'/%3E%3C/svg%3E"
     alt="Data URLサンプル">

使用結果: TYPE=DATAURL として扱います。

3. 9方向の右下へ配置

<img class="bf-image"
     src="assets/sample.png"
     alt="右下配置"
     width="360"
     height="240"
     style="object-fit:contain; object-position:right bottom;">

使用結果: 画像の基準位置が bottom-right になります。

4. Property Editor相当をPublic APIで指定

<div id="image-host"></div>
<script>
BoneImage.render(document.getElementById("image-host"), {
  id: "image-host-bone",
  type: "IMAGE",
  value: {
  type: "PNG",
  usage: "image",
  listKey: "019-bitmap",
  source: "assets/sample.png",
  alt: "Public APIサンプル",
  width: 320,
  height: 220,
  regionMode: "parent",
  fit: "contain",
  displayRate: 100,
  position: "center"
}
  });
</script>

使用結果: #019 RuntimeへPropertyを明示して画像を生成します。

5. 画像ファイルをアイコン用途で使う

<div id="image-icon-host"></div>
<script>
BoneImage.render(document.getElementById("image-icon-host"), {
  id: "image-icon-host-bone",
  type: "IMAGE",
  value: {
  type: "PNG",
  usage: "icon",
  listKey: "019-bitmap",
  source: "assets/sample.png",
  alt: "画像アイコン",
  size: 48,
  rotate: 0,
  flip: "none",
  visible: { icon: true, name: true, unicode: false },
  output: { icon: true, name: true, unicode: false },
  icon: { type: "image", value: "assets/sample.png", name: "sample" }
}
  });
</script>

使用結果: 元画像の縦横比を維持し、長辺を48pxへ合わせた画像アイコンとして扱います。Nameも表示/OUTします。

6. EMOJIを#019で表示

<div id="emoji-host"></div>
<script>
BoneImage.render(document.getElementById("emoji-host"), {
  id: "emoji-host-bone",
  type: "IMAGE",
  value: {
  type: "EMOJI",
  source: "😀",
  size: 56,
  icon: { type: "emoji", value: "😀", name: "にっこり" },
  visible: { icon: true, name: true, unicode: false }
}
  });
</script>

使用結果: #019自身が絵文字を表示し、Nameや表示領域設定を適用します。

Runtime Default / Property Editor

Runtime Default 全件

以下は BoneImage.normalizeValue() の正式Defaultです。

Property Editorの主な数値範囲

Runtimeは正規化のみで上限を持たない値がありますが、Property Editorは操作しやすい範囲へ制限しています。

TYPE 全13値

type は「画像のファイル形式」だけでなく、#019がどの表示経路を使うかを決めます。Defaultは ICON です。

• ICON: Font Awesome。listKey=018-icon-fontawesome で#018 Bone Iconへ委譲。
• EMOJI: 絵文字。List Keyを使わず#019自身が表示。usage は強制icon。
• BITMAP: 汎用Bitmap。019-bitmapへ解決。
• SVG: SVG。現Runtimeでは 086-svg-surface-dummy へ解決し、#086未作成のためダミー扱い。
• JPEG: .jpeg等をJPEGとして扱うBitmap系。
• JPG: .jpg等をJPGとして扱うBitmap系。
• PNG: PNG画像。
• GIF: GIF画像。
• WEBP: WebP画像。
• AVIF: AVIF画像。
• BMP: BMP画像。
• ICO: ICO画像。
• DATAURL: data:image/... をSourceとして扱うBitmap系。

TYPE使用サンプル

<div id="png-example"></div>
<script>
BoneImage.render(document.getElementById("png-example"), {
  id: "png-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG",
  usage: "image",
  listKey: "019-bitmap",
  source: "assets/sample.png"
}
  });
</script>

使用結果: TYPE=PNGとしてBitmap系子UIへ渡します。

不正TYPEは BONE_IMAGE_TYPE_INVALID です。

用途 usage 全2値

usage は画像ファイルを「小さなアイコン素材として扱うか」「通常画像として扱うか」を決めます。TYPE=ICON / EMOJIは常に icon です。

• icon: size を実描画サイズとして使い、Name、回転、反転、表示領域などIcon系設定を利用します。
• image: width / height / fit / displayRate / position を使って通常画像として配置します。

<div id="usage-image"></div>
<script>
BoneImage.render(document.getElementById("usage-image"), {
  id: "usage-image-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "image", listKey: "019-bitmap",
  source: "assets/sample.png", width: 320, height: 220,
  fit: "contain", position: "center"
}
  });
</script>

使用結果: 元画像の幅・高さとFIT/位置を使う通常画像経路です。

不正値は BONE_IMAGE_USAGE_INVALID です。

List Key / UI Registry

List Keyは「このTYPEをどの子UIで描画するか」を示します。TYPE名とList Keyを混同しません。

Runtimeの初期対応:

• ICON → 018-icon-fontawesome
• EMOJI → 空文字（#019自身）
• BITMAP / JPEG / JPG / PNG / GIF / WEBP / AVIF / BMP / ICO / DATAURL → 019-bitmap
• SVG → 086-svg-surface-dummy

Property EditorのUI Registryは、未登録候補と登録済みUIを分離します。List Keyプルダウンは登録済みUIから選択します。登録解除されたList Keyは現在値から外れます。

UI Registry状態値

Registry編集欄にも省略せず状態値があります。

• status=Development: 開発中。正式利用可能状態として扱わない。
• status=Release Ready: リリース準備済み。
• validationStatus=Development: Validation未確定。
• validationStatus=ALL PASS: Validationが全件PASSした状態。
• completionFlag=false: 未完了。
• completionFlag=true: 完了フラグあり。正式UI一覧では Release Ready と組み合わせて判定します。

表示領域 regionMode 全4値

regionMode は通常画像の「どの寸法を表示領域の基準にするか」を示します。Defaultは parent です。

• parent: 親要素側の領域を基準にする。
• original: 元画像サイズを基準にする。
• width: 幅を基準に高さ側を追従させる用途。
• height: 高さを基準に幅側を追従させる用途。

<div id="region-example"></div>
<script>
BoneImage.render(document.getElementById("region-example"), {
  id: "region-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "image", listKey: "019-bitmap",
  source: "assets/sample.png", regionMode: "original",
  width: 320, height: 220
}
  });
</script>

使用結果: 元画像サイズを表示領域の基準として扱います。

不正値は BONE_IMAGE_REGION_MODE_INVALID です。

表示方法 fit 全5値

fit は画像そのものを表示領域へどう収めるかを決めます。Runtime Defaultは contain です。Runtimeは5値を許容しますが、現在の#019テスト画面では contain(FIT) と none(そのまま表示) の2値を直接選択します。

• contain: 縦横比を維持し、画像全体が領域内に収まる最大サイズへ縮尺。余白が出る場合があります。
• cover: 縦横比を維持し、領域全体を埋めるまで拡大。はみ出す部分が発生します。
• fill: 領域へ完全に合わせる。元の縦横比が変わる場合があります。
• none: FITによる自動縮尺を行わず、元の描画寸法を基準にします。
• scale-down: none と contain のうち小さく表示される方を選びます。

<img class="bf-image" src="assets/sample.jpg" alt="cover例"
     width="320" height="180" style="object-fit:cover; object-position:center center;">

使用結果: 320×180pxを埋めるように表示し、必要なら上下または左右を切り取る見え方になります。

不正値は BONE_IMAGE_FIT_INVALID です。

表示率 displayRate

displayRate は通常画像の元寸法へ掛ける倍率を百分率で表します。Runtime Defaultは100、Runtimeは1以上へ補正、Property Editorは1〜500%です。

• 100: 元寸法の100%。
• 50: 半分。
• 200: 2倍。

<div id="rate-example"></div>
<script>
BoneImage.render(document.getElementById("rate-example"), {
  id: "rate-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "image", listKey: "019-bitmap",
  source: "assets/sample.png", width: 320, height: 220,
  displayRate: 50
}
  });
</script>

使用結果: 描画時の幅・高さは元設定の50%を基準にします。

表示位置 position 全9値

position はFIT後の画像を表示領域のどこへ寄せるかを決めます。Defaultは center です。単なる文字寄せではなく、画像の object-position 相当です。

• top-left: 左上。上端・左端を基準に見せる。
• top-center: 上中央。上端を維持して左右中央。
• top-right: 右上。上端・右端を基準に見せる。
• center-left: 左中央。左端を維持して上下中央。
• center: 中央。上下左右の中央。Runtime Default。
• center-right: 右中央。右端を維持して上下中央。
• bottom-left: 左下。下端・左端を基準に見せる。
• bottom-center: 下中央。下端を維持して左右中央。
• bottom-right: 右下。下端・右端を基準に見せる。

<img class="bf-image" src="assets/sample.jpg" alt="右下基準"
     width="320" height="180" style="object-fit:cover; object-position:right bottom;">

使用結果: position=bottom-right。coverで切り取られる場合も右下側を優先して見せます。

不正値は BONE_IMAGE_POSITION_INVALID です。

Source / alt / title / 元画像サイズ

• source: 実画像のURL、相対パス、Data URL、ICON値、EMOJI文字。ICON / EMOJI以外で空なら BONE_IMAGE_SOURCE_REQUIRED。
• alt: 画像の代替テキスト。意味のある画像では内容を短く記述します。
• title: 補助タイトル。alt の代わりではありません。
• width / height: 通常画像では元画像の描画基準寸法。0以上へ補正されます。画像アイコン用途では元画像の縦横比計算にも使用します。

<img class="bf-image"
     src="assets/sample.png"
     alt="売上推移グラフ"
     title="2026年8月売上推移"
     width="320" height="220">

使用結果: HTML Functional Classではwidth/heightは表示領域へ渡し、source/alt/titleを#019へ保持します。

画像アイコン size / rotate / flip

画像ファイルを usage=icon で使う場合、通常画像のFIT/表示率より、Icon系設定を使用します。

size

Runtime Default 56px。Runtimeは1以上、Property Editorは8〜256pxです。元画像の縦横比を維持して長辺をsizeへ合わせます。

rotate

Runtime Default 0。Property Editorは0〜359°。RuntimeはNumberとして保持するため、APIからは範囲外数値も正規化で拒否しません。

flip 全4値

• none: 反転なし。
• horizontal: 左右反転。
• vertical: 上下反転。
• both: 左右と上下の両方を反転。

<div id="flip-example"></div>
<script>
BoneImage.render(document.getElementById("flip-example"), {
  id: "flip-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap",
  source: "assets/sample.png", width: 320, height: 220,
  size: 64, rotate: 90, flip: "horizontal"
}
  });
</script>

使用結果: 長辺64pxの画像アイコンを90°回転し、左右反転します。

表示 / OUT

表示ON/OFFとOUT ON/OFFは別設定です。「画面に見せないが次工程へ値は渡す」ことができます。

• visible.icon: Icon/画像本体を表示するか。Default true。
• visible.name: Nameを表示するか。Default false。
• visible.unicode: Runtime構造には存在するが#019通常UIではUnicodeを表示対象にしない。Default false。
• output.icon: Icon/画像情報をOUTへ含める。Default true。
• output.name: NameをOUTへ含める。Default true。
• output.unicode: Default false。
• containerStyle.output: 表示領域設定をOUTへ渡す。Default true。

<div id="output-example"></div>
<script>
const image = BoneImage.render(document.getElementById("output-example"), {
  id: "output-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap",
  source: "assets/sample.png",
  visible: { icon: true, name: false, unicode: false },
  output: { icon: true, name: true, unicode: false }
}
  });
console.log(BoneImage.getOutput(image));
</script>

使用結果: 画面には画像だけ、OUTにはNameも保持します。

Boolean設定 ON / OFF

Booleanは「あり」だけを書かず、ON/OFF双方の意味を分けます。

• active=false: 通常状態。active=true: Active背景/Active Borderを適用する状態。
• disabled=false: 通常操作可能表示。disabled=true: Disabled Styleを適用する状態。
• visible.icon=false: 画像/Icon本体を画面へ出さない。true: 表示する。Default true。
• visible.name=false: Nameを画面へ出さない。true: 表示する。Default false。
• visible.unicode=false: Unicode表示なし。true: Runtime構造上は表示対象にできるが#019通常Editorでは使用しない。
• output.icon=false: OUTへIcon/画像情報を含めない。true: 含める。Default true。
• output.name=false: OUTへNameを含めない。true: 含める。Default true。
• output.unicode=false: OUTへUnicodeを含めない。true: 含める。Default false。
• containerStyle.borderEnabled=false: Borderなし。true: Border幅/種類/色を適用。
• containerStyle.shadowEnabled=false: Shadowなし。true: Shadow設定を適用。
• containerStyle.shadowInset=false: 外側Shadow。true: 内側Shadow。
• containerStyle.output=false: 表示領域設定をOUTへ含めない。true: 含める。Default true。
• 背景色の「色あり」OFF: backgroundColor / activeBackgroundColor を null として背景なし。ON: #040 ColorPicker RETURNの色値を使用。

Name設定

nameStyle は画像アイコンのName表示用です。

• fontSize: Runtime Default 16px。Property Editor 8〜96px。
• color: Default #DCE8F8。#040 ColorPicker経由で設定。
• fontFamily: Default inherit。
• gap: Default 8px。Property Editor 0〜100px。

position 全4値

• top: Nameを画像アイコンの上へ配置。
• bottom: 下へ配置。Default。
• left: 左へ配置。
• right: 右へ配置。

<div id="name-example"></div>
<script>
BoneImage.render(document.getElementById("name-example"), {
  id: "name-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap",
  source: "assets/sample.png",
  icon: { type: "image", value: "assets/sample.png", name: "sample" },
  visible: { icon: true, name: true, unicode: false },
  nameStyle: { fontSize: 16, color: "#DCE8F8", fontFamily: "inherit", position: "right", gap: 12 }
}
  });
</script>

使用結果: 画像アイコンの右側へ12px空けて sample を表示します。

ColorPicker

#019は独自ColorPickerを持ちません。既存Color Propertyの色トリガーから #040 ColorPicker attachCaller() を呼び、RETURN値を既存Propertyへ反映します。#040のOverlay / Tooltip DOMを#019へコピーしません。

対象例: color、backgroundColor、activeBackgroundColor、nameStyle.color、containerStyle.borderColor、activeStyle.borderColor、disabledStyle.backgroundColor、disabledStyle.borderColor。

Solid / Transparent / Gradientを受けるPropertyがあります。containerStyle.shadowColor は既存契約維持のためSolid / Transparentです。

<div id="gradient-image-icon"></div>
<script>
BoneImage.render(document.getElementById("gradient-image-icon"), {
  id: "gradient-image-icon-bone",
  type: "IMAGE",
  value: {
  type: "ICON",
  source: "fa-image",
  color: {
    kind: "gradient", type: "linear", angle: 90,
    stops: [
      { position: 0, color: "#55E6A5" },
      { position: 100, color: "#5BA6FF" }
    ]
  }
}
  });
</script>

使用結果: TYPE=ICON時は#018 Bone IconへGradient Colorを渡します。

表示領域 Container

containerStyle は画像/画像アイコンの外側領域です。画像そのものの元寸法 width/height と混同しません。

• width / height: Default 220×150px。
• minWidth / minHeight: Default 0。
• maxWidth / maxHeight: Default null、制限なし。
• paddingTop / Right / Bottom / Left: Default各10px。
• output: Default true。

<div id="container-example"></div>
<script>
BoneImage.render(document.getElementById("container-example"), {
  id: "container-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap",
  source: "assets/sample.png",
  containerStyle: {
    width: 180, height: 120,
    paddingTop: 12, paddingRight: 16, paddingBottom: 12, paddingLeft: 16,
    justify: "center", align: "center", overflow: "hidden", opacity: 1
  }
}
  });
</script>

使用結果: 180×120pxの領域内にPaddingを持つ画像アイコンになります。

数値Property詳細

単位とProperty Editor範囲をまとめます。Runtimeに上限検証がない値は、そのことを明記します。

• width / height: px相当の数値。Runtimeは0以上へ補正。Editorの元画像幅/高さ入力にはHTML min 指定なし。
• displayRate: %。Runtime 1以上、Editor 1〜500。
• size: px。Runtime 1以上、Editor 8〜256。
• rotate: degree。RuntimeはNumber化、Editor 0〜359。
• nameStyle.fontSize: px。Editor 8〜96。
• nameStyle.gap: px。Editor 0〜100。
• containerStyle.width / height / minWidth / minHeight: px。Editor 0以上。
• containerStyle.maxWidth / maxHeight: px。空欄はnull=制限なし、入力時0以上。
• containerStyle.paddingTop / Right / Bottom / Left: px。Editor 0以上。
• containerStyle.borderWidth: px。Editor 0〜20。
• containerStyle.borderRadius: px。Editor 0〜999。
• containerStyle.opacity: 無単位0〜1、step 0.05。
• containerStyle.shadowX / shadowY / shadowSpread: px。Editorは負値も入力可能。
• containerStyle.shadowBlur: px。Editor 0以上。
• activeStyle.borderWidth: px。Editor 0以上。
• disabledStyle.opacity: 無単位0〜1、step 0.05。

Border / Shape

borderStyle 全4値

• solid: 実線。Default。
• dotted: 点線。
• dashed: 破線。
• double: 二重線。

shape 全6値

• square: 四角。角丸を強制しない。
• rounded: 角丸。Default、borderRadius=8。
• circle: 円形。縦横同寸法で円として使う。
• ellipse: 楕円。
• capsule: 大きなRadiusでカプセル形状。
• custom: borderRadius の任意値を使う。

Property Editor: Border幅0〜20px、Radius 0〜999px。

<div id="border-example"></div>
<script>
BoneImage.render(document.getElementById("border-example"), {
  id: "border-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap", source: "assets/sample.png",
  containerStyle: {
    width: 96, height: 96, borderEnabled: true,
    borderColor: "#55E6A5", borderWidth: 2, borderStyle: "dashed",
    shape: "circle", borderRadius: 48
  }
}
  });
</script>

使用結果: 96×96pxの円形領域へ2px破線Borderを設定します。

配置 / Overflow / Opacity

justify 全3値

• start: 横方向の左側。
• center: 横中央。Default。
• end: 横方向の右側。

align 全3値

• start: 縦方向の上側。
• center: 縦中央。Default。
• end: 縦方向の下側。

overflow 全3値

• visible: 領域外も表示。Default。画像アイコンやNameが領域を超えてもクリップしない。
• hidden: 領域外をクリップして非表示。
• auto: 必要に応じて領域内スクロール。

opacity

0で完全透明、1で不透明。Runtime Default 1、Property Editor 0〜1です。

<div id="overflow-example"></div>
<script>
BoneImage.render(document.getElementById("overflow-example"), {
  id: "overflow-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap", source: "assets/sample.png",
  size: 120,
  containerStyle: { width: 80, height: 80, overflow: "hidden", justify: "end", align: "end", opacity: 0.8 }
}
  });
</script>

使用結果: 80×80pxを超える部分は切り、右下寄せ、Opacity 0.8で表示します。

RuntimeとProperty Editorの列挙値差

Runtimeが明示的に不正値Errorを出す列挙Propertyは type / usage / regionMode / fit / position です。その他の下記設定は、現在のProperty Editorが正式選択肢を限定していますが、normalizeValue() 自体は同じ列挙検証を行いません。したがって一般利用ではEditorの値だけを使用します。

• flip: Editor none / horizontal / vertical / both。
• nameStyle.position: Editor top / bottom / left / right。
• containerStyle.borderStyle: Editor solid / dotted / dashed / double。
• containerStyle.shape: Editor square / rounded / circle / ellipse / capsule / custom。
• containerStyle.justify: Editor start / center / end。
• containerStyle.align: Editor start / center / end。
• containerStyle.overflow: Editor visible / hidden / auto。

Shadow

Shadowは表示領域へ適用します。

• shadowEnabled: Default false。
• shadowInset: Default false。trueなら内側Shadow。
• shadowX: Default 0px。
• shadowY: Default 4px。
• shadowBlur: Default 12px、Property Editorは0以上。
• shadowSpread: Default 0px。
• shadowColor: Default #000000。Solid / Transparent。

<div id="shadow-example"></div>
<script>
BoneImage.render(document.getElementById("shadow-example"), {
  id: "shadow-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap", source: "assets/sample.png",
  containerStyle: {
    width: 100, height: 100,
    shadowEnabled: true, shadowInset: false,
    shadowX: 0, shadowY: 6, shadowBlur: 18, shadowSpread: 0,
    shadowColor: "#000000"
  }
}
  });
</script>

使用結果: 表示領域の外側へ下方向6px・Blur 18pxのShadowを付けます。

Active / Disabled

Active

active=true のときActive用背景/Borderを使用します。

• activeBackgroundColor: Default null。
• activeStyle.borderColor: Default #5BA6FF。
• activeStyle.borderWidth: Default 2px。

Disabled

disabled=true のときDisabled Styleを使用します。

• disabledStyle.opacity: Default 0.45。
• disabledStyle.backgroundColor: Default #222B38。
• disabledStyle.borderColor: Default #687386。

<div id="disabled-example"></div>
<script>
BoneImage.render(document.getElementById("disabled-example"), {
  id: "disabled-example-bone",
  type: "IMAGE",
  value: {
  type: "PNG", usage: "icon", listKey: "019-bitmap", source: "assets/sample.png",
  disabled: true,
  disabledStyle: { opacity: 0.35, backgroundColor: "#222B38", borderColor: "#687386" }
}
  });
</script>

使用結果: Disabled用Opacity/背景/枠色で表示します。

Emoji

TYPE=EMOJI は画像ファイル入力やList Keyを使わず、#019自身が表示します。Runtimeの BoneImage.getEmojiCatalog() は現在1,438件を返し、9グループに整理されています。

グループ:

• Smileys & Emotion / 顔・感情
• People & Body / 人・体
• Animals & Nature / 動物・自然
• Food & Drink / 食べ物・飲み物
• Travel & Places / 乗り物・場所
• Activities / 活動
• Objects / 物
• Symbols / 記号
• Flags / 旗

Flags / 旗 グループには通常の国旗に加えて 🎌（祝日）も含みます。

選択した絵文字は source と icon.value に入り、Name、size、rotate、flip、Container設定を利用できます。Flags / 旗 では 🎌 を「祝日」として選択できます。さらに BoneEmojiRegistry.register() で共有絵文字を追加でき、追加した定義は BoneEmojiRegistry.getCatalog() と BoneImage.getEmojiCatalog() の両方から取得できます。Sourceが空なら BONE_IMAGE_EMOJI_VALUE_REQUIRED です。

共有絵文字追加サンプル

<script src="../js/bone-emoji-registry.js"></script>
<script>
BoneEmojiRegistry.register({
  emoji: "📌✨",
  name: "重要",
  group: "objects",
  groupLabel: "Objects / 物"
});
const allCatalog = BoneEmojiRegistry.getCatalog();
const imageCatalog = BoneImage.getEmojiCatalog();
</script>

他のUIから共通利用する

共有絵文字は #019 Image の内部機能ではありません。bone-emoji-registry.js 単体で標準Catalog 1,438件と追加Catalogを保持するため、Button / Label / List など他のUIは #019 Image や bone-image.js を読み込まずに利用できます。

<script src="../js/bone-emoji-registry.js"></script>
<script>
const catalog = BoneEmojiRegistry.getCatalog();
const holiday = BoneEmojiRegistry.find("🎌");
</script>

他UIで絵文字選択UIを作る場合は getCatalog() または getGroups() を利用します。#019のDOMやProperty Editorを参照してはいけません。追加内容は同一Originの localStorage に保存され、同じBone Flow環境の他UIから取得できます。

補助API:

• BoneEmojiRegistry.getBaseCatalog() — Bone Flow共通標準1438件。
• BoneEmojiRegistry.getCustomCatalog() — 追加済み共有絵文字のみ。
• BoneEmojiRegistry.remove(emoji) — 追加済み共有絵文字1件を削除。
• BoneEmojiRegistry.clearCustom() — 追加済み共有絵文字を全削除。

Joint / 接続イメージ

接続線の責務は#002 Bone Jointです。#019独自の見た目だけの線へ置き換えません。現正本は BoneJoint.drawLine() の gradient-flow を使い、Bone Jointが生成した実パスを接続イメージとして表示します。

確認対象:

• IN / OUT
• Target Field不存在
• 型不一致
• 接続エラー
• #002が生成した接続パスと状態表示

接続判定・描画・アニメーションを#019単独で再実装しません。

Smoke / Validation

Smoke Testは通常系、Validation Reportは異常系・契約検証です。テスト期待値を変更してPASSにしてはいけません。

最低限の確認対象:

• Bone Core IMAGE構造
• TYPE / usage / List Key
• ICON → #018委譲
• EMOJI表示
• Bitmap系Source
• Preview / OUT / Child Input / Child OUT
• ColorPicker Caller/RETURN
• Joint実パス
• Registry登録/解除
• Completion構造

Runtimeテストが未実行なら NOT RUN のまま扱います。

Completion

「変更を確定」はPropertyのDraftを確定する操作であり、Component Completionとは別です。

正式CompletionはSmoke TestとValidation ReportがALL PASSのときだけ実行します。BoneImage.complete() はCompletion Flag、Status、Validation Status、完了日時を更新し、reopen() でDevelopmentへ戻します。

ユーザーlocalhost確認前にCompleted / Specification Frozenとは扱いません。

Public API

HTML Functional Class bf-image とPublic APIを混同しません。Runtimeが getPublicAPI() で公開する正式16件は以下です。getCompletionState / complete / reopen やRegistry管理用メソッドなど、Runtime object上に存在しても getPublicAPI() の16件へ含まれない管理機能は、HTML Functional Class数へ変換しません。

1. BoneImage.create(input) — IMAGE Bone / Propertyから要素を生成。
2. BoneImage.getBone(element) — Instanceが保持するBoneを取得。
3. BoneImage.getValue(element) — 正規化済みPropertyを取得。
4. BoneImage.getOutput(element) — #019正式OUTを取得。
5. BoneImage.getChildInput(element) — 子Componentへ渡すInputを取得。
6. BoneImage.getChildOutput(element) — 子ComponentのOUT相当を取得。
7. BoneImage.buildOutput(input) — PropertyからOUT構造を生成。
8. BoneImage.buildChildInput(input) — Propertyから子Inputを生成。
9. BoneImage.buildChildOutput(input) — Propertyから子OUTを生成。
10. BoneImage.createEditor(options) — Property Editorを生成。
11. BoneImage.createParent(options) — 複数Image用の親領域を生成。
12. BoneImage.resolveChild(input) — List Keyから子UIを解決。
13. BoneImage.getEmojiCatalog() — 1,438件のEmoji Catalogを取得。
14. BoneImage.render(target, input) — targetへImageを生成してappend。
15. BoneImage.update(element, input) — 既存Instanceを新Propertyで置換。
16. BoneImage.destroy(element) — Instance管理を解除してDOMを削除。

Public API使用サンプル

<div id="api-image"></div>
<script>
const image = BoneImage.render(document.getElementById("api-image"), {
  id: "api-image-bone",
  type: "IMAGE",
  value: {
  type: "PNG",
  usage: "image",
  listKey: "019-bitmap",
  source: "assets/sample.png",
  alt: "APIサンプル",
  fit: "contain",
  position: "center"
}
  });
console.log(BoneImage.getValue(image));
console.log(BoneImage.getOutput(image));
</script>

使用結果: 生成後の正式PropertyとOUTを取得できます。

Error / Troubleshooting

Runtime Error Code

• BONE_IMAGE_TYPE_INVALID: TYPEが13値に含まれない。
• BONE_IMAGE_USAGE_INVALID: usageがicon/imageでない。
• BONE_IMAGE_REGION_MODE_INVALID: regionModeが4値に含まれない。
• BONE_IMAGE_FIT_INVALID: fitが5値に含まれない。
• BONE_IMAGE_POSITION_INVALID: positionが9値に含まれない。
• BONE_IMAGE_ICON_VALUE_REQUIRED: TYPE=ICONなのにIcon値がない。
• BONE_IMAGE_EMOJI_VALUE_REQUIRED: TYPE=EMOJIなのに絵文字Sourceがない。
• BONE_IMAGE_SOURCE_REQUIRED: 画像TYPEなのにSourceがない。
• BONE_IMAGE_CORE_DEPENDENCY_MISSING: #001 Bone Coreが利用できない。
• BONE_IMAGE_REGISTRY_DEPENDENCY_MISSING: Bone UI Registryが利用できない。
• BONE_IMAGE_DOCUMENT_UNAVAILABLE: DOM Documentが利用できない。
• BONE_IMAGE_BONE_TYPE_MISMATCH: IMAGE以外のBoneを渡した。
• BONE_IMAGE_INVALID: その他の正規化/検証Error。

HTML Functional Class Error Code

• BONE_IMAGE_HTML_CLASS_CORE_UNAVAILABLE: #001 Bone Coreが読み込まれていない。
• BONE_IMAGE_HTML_CLASS_RUNTIME_UNAVAILABLE: BoneImage Runtimeが読み込まれていない。
• BONE_IMAGE_HTML_CLASS_ELEMENT_UNSUPPORTED: img以外へbf-imageを付けた。
• BONE_IMAGE_HTML_CLASS_SOURCE_REQUIRED: srcが空。
• BONE_IMAGE_HTML_CLASS_CREATE_FAILED: Runtime生成に失敗。

よくある確認

画像がダミー表示になる: TYPEに対応するList Keyが未作成UIの場合があります。特にSVGは現正本では#086 planned/dummyです。

画像全体が見えない: fit=cover は領域を埋めるため一部が切れます。全体を見せるなら contain。

Positionを変えても差が見えない: 画像と表示領域の縦横比が同じ、または余白/切り取りがない場合は見た目の差が出ません。cover と異なる縦横比の領域で確認します。

画像アイコンのNameが見えない: visible.name=true を確認し、containerStyle.overflow がhiddenでNameを切っていないか確認します。

色Pickerが開かない: #019独自Pickerではなく#040 ColorPicker Caller経路です。#040依存とCaller RETURNを確認します。