UI パーツ

UI パーツ（UI Parts）は、スクリプトでユーザーインターフェースを作るための基本部品です。情報表示や入力受付のための部品を組み合わせて UI を構築できます。UI パーツは、サイドバーパネル、スクリプトパネル、ツールボックスオプションなどの UI 拡張や、モーダル＆ウィンドウの中身として利用できます。

UI パーツは type プロパティを持つオブジェクトとして定義します。type ごとにプロパティが異なり、挙動と見た目を定義します。

レイアウト系コンポーネント

Row

Row レイアウトは、子コンポーネントを 1 行に横並びで配置します。content に UI パーツ配列を渡します。flex（row）として動作し、spacing と alignment で間隔と縦方向の揃えを制御できます。

例：

{
  type: 'row',
  content: [
    {
      type: 'text',
      text: 'First Item'
    },
    {      
      type: 'text',
      text: 'Second Item'
    }
  ]
}

Column

Column レイアウトは、子コンポーネントを縦 1 列に配置します。content に UI パーツ配列を渡します。flex（column）として動作し、spacing と alignment で間隔と横方向の揃えを制御できます。

例：

{
  type: 'column',
  content: [
    {
      type: 'text',
      text: 'First Item'
    },
    {
      type: 'text',
      text: 'Second Item'
    }
  ]
}

Box

Box レイアウトは、背景色と枠線のあるボックスの中に子コンポーネントを配置します。content に UI パーツ配列を渡します。より自由なスタイルを当てたい場合は、代わりに style を持つ Container を使ってください。

例：

{
  type: 'box',
  content: [
    {
      type: 'text',
      text: 'This is inside a box.'
    }
  ]
}

Container

Container は、子コンポーネントを単純な div で包むラッパーです。content に UI パーツ配列を渡します。style でグループにカスタムスタイルを適用したいときに便利です。

例：

{
  type: 'container',
  style: {
    border: '1px solid #ff0000',
    padding: '10px'
  },
  content: [
    {
      type: 'text',
      text: 'This is inside a custom-styled container.'
    }
  ]
}

入力系コンポーネント

Text Input

1 行テキスト入力です。storageKey を指定すると、入力値を永続ストレージにバインドして、セッションを跨いで保存/復元できます。onChange と onSubmit で、入力変化や送信（Enter など）を受け取れます。

例：

{
  type: 'textInput',
  storageKey: 'user-value',
  onChange: (value) => {
    api.v1.log('User changed input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted input: ' + value)
  }
}

Multiline Text Input

複数行テキスト入力です。storageKey、onChange、onSubmit などの考え方は Text Input と同じです（送信は Ctrl+Enter など）。

例：

{
  type: 'multilineTextInput',
  storageKey: 'user-multiline-value',
  onChange: (value) => {
    api.v1.log('User changed multiline input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted multiline input: ' + value)
  }
}

Number Input

数値入力です。storageKey、onChange、onSubmit が利用できます。

例：

{
  type: 'numberInput',
  storageKey: 'user-number-value',
  onChange: (value) => {
    api.v1.log('User changed number input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted number input: ' + value)
  }
}

Checkbox Input

真偽値の切り替え（チェックボックス）です。storageKey と onChange が利用できます。

例：

{
  type: 'checkboxInput',
  storageKey: 'user-checkbox-value',
  onChange: (value) => {
    api.v1.log('User changed checkbox to: ' + value)
  }
}

表示系コンポーネント

Text

テキスト表示です。text に表示内容を入れます。markdown: true を指定すると Markdown 表示が有効になります。ただし、セキュリティとプライバシーの理由により、URL はクリック可能なリンクになりません。

{{curly braces}} で囲まれた文字列は storage key として扱われ、対応する保存値で置換されます。この挙動を無効化したい場合は noTemplate: true を指定します。historyStorage / storyStorage / tempStorage を参照したい場合は、{{history:key}}、{{story:key}}、{{temp:key}} の形式を使います。

例：

{
  type: 'text',
  text: `# Heading
This is **bold** text and this is *italic* text.`,
  markdown: true
}

Image

画像表示です。src に画像 URL、alt に代替テキストを指定できます。

src は Data URL（例：“data:image/png;base64,…”）のみ対応です。外部 URL から画像を読み込むことはできません（セキュリティとプライバシーのため）。

また、安定のため height と width を明示的に指定することが推奨されます。

例：

{
  type: 'image',
  src: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
  alt: 'Example Image',
  height: 200,
  width: 200
}

Button

クリック可能なボタンです。text がラベル、callback がクリック時に実行される関数です。disabled: true で無効化できます。disableWhileCallbackRunning: true にすると、callback 実行中にボタンを無効化できます。

例：

{
  type: 'button',
  text: 'Click Me',
  callback: () => {
    api.v1.log('Button was clicked!')
  }
}

スタイル（Styling）

多くの UI パーツは style プロパティで見た目をカスタマイズできます。style は CSS プロパティと値のオブジェクトで、プロパティ名は camelCase で書きます（例：backgroundColor）。

これはインラインスタイルなので、疑似クラスやメディアクエリは使えません。URL はセキュリティとプライバシーの理由で style から削除されます。

テーマカラー（例：bg0、textHeadings、warning）やフォントファミリー（例：default、headings）のキー名を値として使うと、現在のテーマに応じた実値へ置換されます。

状態管理（State Management）

storageKey

多くの入力 UI パーツは storageKey をサポートし、入力値を永続ストレージへ自動保存できます。ユーザーが入力を変えると指定キーで保存され、保存値が別 UI パーツや別スクリプトで変更された場合も、入力 UI が自動で追従します。

参考