avatar-container

アバター動画を表示するWeb Componentです。ビデオトラックが自動的にバインドされます。

使用方法

html

<avatar-container
  style="width: 400px; height: 400px;"
  fit="cover"
></avatar-container>

属性

属性	型	デフォルト	説明
`volume`	`number`	`100`	オーディオボリューム（0-100）。プロパティを変更すると `SDK.setVolume()` を自動呼び出しします。HTML属性で指定した初期値は適用されません — 下の「ボリューム制御」を参照してください。
`fit`	`string`	`"cover"`	ビデオフィットモード。`"cover"` \| `"contain"` \| `"fill"`

fit オプション

値	説明
`"cover"`	アスペクト比を維持しながらコンテナを満たす（はみ出た部分はクリップ）
`"contain"`	アスペクト比を維持しながらコンテナ内に全体を表示（余白が生じる場合あり）
`"fill"`	アスペクト比を無視してコンテナに合わせる

イベント

イベント	説明
`avatar-connected`	コンポーネントがDOMにマウントされ、初回レンダリングが完了した後に発火します。SDKがこのイベントを受信してビデオトラックを自動的にバインドします。

ビデオ自動バインディング

ビデオトラックは以下の順序で自動接続されます：

<avatar-container> がDOMに追加されると、初回レンダリング完了後に avatar-connected イベントを発火します。
SDK Coreがこのイベントを受信し、Agoraビデオトラックを内部の .avatar 要素で再生します。
ビデオトラックが先に受信された場合でも、<avatar-container> が後からDOMに追加されれば自動的にバインドされます。

配置順序

ウェルカムメッセージが設定されたアバターの場合、<avatar-container> を init() 呼び出し前にDOMに配置してください。ウェルカムメッセージは接続直後に再生されるため、<avatar-container> がDOMにない状態だと映像なしで音声だけ先に流れる場合があります。

スタイリング

Shadow DOM

Shadow DOMでカプセル化されているため、style 属性はコンポーネントのサイズ・位置・ボーダーなど外部レイアウトにのみ適用されます。内部ビデオ要素のスタイルは変更できません。

html

<avatar-container
  style="
    width: 100%;
    max-width: 500px;
    aspect-ratio: 9/16;
    border-radius: 16px;
    overflow: hidden;
  "
></avatar-container>

ボリューム制御

HTML属性で初期ボリュームを指定することはできません

<avatar-container volume="80"> のようにHTML属性で指定した値は適用されません。 コンポーネントがDOMにマウントされるのは init() 完了前のため、その時点の SDK.setVolume() 呼び出しは無視され、接続完了後に再適用されることもありません。

初期ボリュームが必要な場合は、接続完了（CONNECTED_FINISH）後に指定してください。

SDK.onStatus((status) => {
  if (status === 'CONNECTED_FINISH') {
    SDK.setVolume(80);
  }
});

// 方法1: プロパティ変更（内部的にSDK.setVolume()を呼び出し）
document.querySelector('avatar-container').volume = 50;

// 方法2: SDK APIを直接呼び出し
SDK.setVolume(50);

両方の方法で同じ結果になります。プロパティを変更すると、コンポーネントが SDK.setVolume() を自動的に呼び出します。HTML属性ではなく JavaScriptプロパティ である必要があります。

avatar-container ​

使用方法 ​

属性 ​

fit オプション ​

イベント ​

ビデオ自動バインディング ​

スタイリング ​

ボリューム制御 ​