---
title: "プレイヤー UI"
slug: "vpe-rn-player-ui"
updated: 2026-09-17T09:22:05Z
published: 2026-09-17T09:22:05Z
canonical: "guide.ncloud-docs.com/vpe-rn-player-ui"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# プレイヤー UI

Classic/VPC環境で利用できます。

プレイヤー UIを構成・設定するオプションをご案内します。

## デフォルトオプション

### aspectRatio(画面アスペクト比)

`aspectRatio` プロパティでプレイヤーの縦横比を指定できます。プレイヤーが固定型サイズ(width、height)を持っていない場合のみ適用できます。containerのサイズが変わっても縦横比は維持されます。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    aspectRatio: '16/9', //アスペクト比の設定
  }}
/>
```

### objectFit(全画面表示)

`objectFit` プロパティで全画面表示の方式を設定できます。再生ソースの比率を維持し、画面サイズに合わせるように設定するユースケースは、次の通りです。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    aspectRatio: '16/9',
    objectFit: 'cover', // 全画面表示の設定(比率を維持する+画面サイズに合わせる)
  }}
/>
```

## コントロールバー

### controls(コントロールバーの表示)

`controls` プロパティでコントロールバーの表示有無を設定します。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    controls: false, // コントロールバーを表示しない(true: コントロールバーを表示)
  }}
/>
```

### controlBtn(コントロールバーボタン UI)

`controlBtn` プロパティでコントロールバーのボタン UIの使用有無を設定します。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    controls: true,
    controlBtn: {
      play: true,        // 再生
      progressBar: true, // 再生バーの使用有無
      fullscreen: true,  // 全画面表示に切り替え
      volume: true,      // ボリュームコントロール
      times: true,       // 再生時間
      setting: true,     // 設定
    },
  }}
/>
```

### progressBarColor(コントロールバーの色)

`progressBarColor` プロパティでコントロールバーの動画シークスライダの色を設定できます。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    progressBarColor: "#ff0000", // 色コード(赤)
  }}
/>
```

### controlActiveTime(コントロールバーの表示時間)

`controlActiveTime` プロパティでコントロールバーを表示する時間を設定します。

              参考

              

`controlActiveTime: 0`に設定すると、コントロールバーは自動的に非表示にならず常に表示されます。ライブコマースのように、UIが常に表示される必要がある画面で役立ちます。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    controlActiveTime: 3000, // コントロールバーの表示時間を設定(3000 = 3秒)
  }}
/>
```

### コントロールバー UIの動的変更

動画の長さによってボタン UIを動的に変更できます。例えば、動画の長さが10秒未満の場合、全画面表示、PIP、設定ボタンを提供しないように設定できます。

```
const playerRef = useRef(null);

return (
  <VpePlayer
    ref={playerRef}
    events={{
      timeupdate: (res) => {
        if (res.duration < 10) {
          playerRef.current.controlBarBtnStateUpdate({
            fullscreen: false,
            pictureInPicture: false,
            setting: false,
          });
        }
      },
    }}
    options={{
      playlist: [
        { file: 'https://CDNドメイン/example_video_01.mp4' },
      ],
      controlBtn: {
        play: true,
        fullscreen: true,
        volume: true,
        times: true,
        setting: true,
        subtitle: false,
      },
    }}
  />
);
```

## 字幕 UIの設定

字幕のサイズ、背景、スタイルを設定します。

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNドメイン/example_video_01.mp4' },
    ],
    captionStyle: {
      fontSize: 12,
      color: '#FFFFFF',
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
      edgeStyle: 'dropshadow', // dropshadow, raised, depressed, uniform
    },
  }}
/>
```

## レイアウトシステム

サポートプラットフォーム: `Android` `iOS`

VPE React Native SDKは、ウェブ SDKから移植された layout-driven ControlBarシステムを提供します。JSON宣言により、コントロールボタンの配置、グループ化、画面環境別(PC/モバイル/全画面)およびコンテンツタイプ別(VOD/ライブ)構成を定義できます。

### 概要

`layout` propにレイアウトオブジェクトを渡すことで、ControlBarのすべての領域をカスタマイズできます。`layout` propがない場合は、デフォルトのレスポンシブレイアウトが使用されます。

- 5つのセクション: `top`、`upper`、`center`、`lower`、`bottom`
- 環境別に分離: `pc` / `mobile` / `fullscreen`
- コンテンツタイプ別に分離: `vod` / `live`
- モバイル判定の breakpoint: デフォルト768
- ユーザー layout × デフォルト layoutを自動マージ(セクション単位で replace)

### 構成構造

最上位キーは `pc`、`mobile`、`fullscreen`に分かれており、各環境内で `vod`と `live` のレイアウトを定義します。

```
{
  "pc": {
    "vod": {},
    "live": {}
  },
  "mobile": {
    "vod": {},
    "live": {}
  },
  "fullscreen": {
    "vod": {},
    "live": {}
  },
  "breakpoint": 768
}
```

`layout.json`

各 variantの内部は、5つのセクションの順序と、グループ/アイテムのソートで構成されています。

```
{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "wrapper": "Group", "items": ["BackBtn"] },
    { "wrapper": "Blank" },
    { "wrapper": "Group", "items": ["ShareBtn", "SettingBtn"] }
  ],
  "center": [
    { "wrapper": "Blank", "items": ["BigPlayBtn"] }
  ],
  "bottom": {
    "seekbar": ["SeekBar"],
    "left": [
      { "wrapper": "Group", "items": ["PlayBtn", "VolumeBtn"] },
      { "wrapper": "Group", "items": ["TimeBtn"] }
    ],
    "right": [
      { "wrapper": "Group", "items": ["SubtitleBtn", "FullscreenBtn"] }
    ]
  }
}
```

`variant.json`

### 使用可能なコントロールアイテム

`items` 配列には、以下の名前を使用できます。

| 名前 | 説明 |
| --- | --- |
| `PlayBtn` | 再生/一時停止/再視聴トグル(isEnded分岐) |
| `BigPlayBtn` | 中央大型再生ボタン。playlist > 1の場合、左右に prev/nextを自動表示 |
| `VolumeBtn` | 音量トグル |
| `MuteBtn` | ミュート専用ボタン |
| `TimeBtn` | 現在時刻 / 総時間または LIVEインジケータ |
| `CurrentTimeBtn` | 現在の再生時間(分割バージョン) |
| `DurationBtn` | 総再生時間(分割バージョン) |
| `SeekBar` | 進捗率スライダー |
| `FullscreenBtn` | 全画面表示トグル |
| `SubtitleBtn` | 字幕即時トグル(SettingsMenuを経由しない) |
| `SettingBtn` | SettingsMenuトグル(画質/再生速度/字幕) |
| `PrevBtn` | 前のトラック |
| `NextBtn` | 次のトラック |
| `NextPrevBtn` | 前へ/次へ統合ボタン |
| `BackBtn` | 戻る。`events.backPress` 呼び出し |
| `ShareBtn` | React Native Share API呼び出し |
| `SkipForwardBtn` | 10秒進む |
| `SkipBackBtn` | 10秒戻る |
| `MetaDesc` | 動画メタデータ(タイトル/プロファイル/登録日) |
| `Blank` | 子要素がない場合は spacer(`flex:1`)、ある場合は整列用 row |

              参考

              

React Nativeでは、明示的 PIPボタン(`PipBtn`)が非標準であるため廃止されました。代わりに、`playerRef.current.pip()` または `options.allowsPictureInPicture` lifecycleをご利用ください。

### wrapperの種類

- `Group` — 基本的なピル型グループ(半透明背景、borderRadius 999)。単一の子要素の場合は円形(`aspectRatio: 1`)処理、`TimeBtn`は単独の場合にバイパス。
- `Blank` — 子要素がない場合は spacer、子要素がある場合は alignを適用した row。

### 基本ユースケース

```
import { VpePlayer } from 'vpe-react-native';

const myLayout = {
  pc: {
    vod: {
      order: ['top', 'center', 'bottom'],
      top: [
        { wrapper: 'Group', items: ['BackBtn'] },
        { wrapper: 'Blank' },
        { wrapper: 'Group', items: ['ShareBtn', 'SettingBtn'] },
      ],
      center: [{ wrapper: 'Blank', items: ['BigPlayBtn'] }],
      bottom: {
        seekbar: ['SeekBar'],
        left: [
          { wrapper: 'Group', items: ['PlayBtn', 'VolumeBtn'] },
          { wrapper: 'Group', items: ['TimeBtn'] },
        ],
        right: [
          { wrapper: 'Group', items: ['SubtitleBtn', 'FullscreenBtn'] },
        ],
      },
    },
    live: { /* ... */ },
  },
  mobile: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  fullscreen: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  breakpoint: 768,
};

export default function MyPlayer() {
  return (
    <VpePlayer
      accessKey={'YOUR_ACCESS_KEY'}
      layout={myLayout}
      options={{
        playlist: [{ file:'https://CDNドメイン/master.m3u8' }],
        aspectRatio: '16/9',
      }}
    />
  );
}
```

### レイアウトマージ動作

ユーザーが指定した layoutは、デフォルトの layoutと自動マージされます。一部の環境(例: (`pc`のみ)または一部のセクションのみを定義しても、残りはデフォルトが使用されます。ただし、**セクション単位の replace**方式であるため、あるセクションを定義するとデフォルトの同じセクションは完全に置き換えられます。

開発(`__DEV__`)モードでは、不正なアイテム名や必須セクションの欠落などに対してコンソールに警告が表示されます。

### タッチジェスチャー

ControlBarは、シングルタップ/ダブルタップのジェスチャーを処理します。画面を左/中央/右の1/3ずつに分割し、ダブルタップすると10秒ずつ累積して seekが行われ、シングルタップするとコントロールバーをトグル表示します。

- シングルタップのトグルは300ms遅延(その間に2回目のタップが入るとダブルタップとして処理され、コントロールの点滅を防止)
- 左/右のダブルタップ → 10秒ずつ累積して seek(500ms後に実際の seekを実行)
- `options.touchGestures: false` 時にダブルタップを無効化(シングルタップトグルのみ動作)

## 関連ガイド

- [カスタムアイコン(IconOverrides)](https://developer.vpe.naverncp.com/docs/rn/custom-icon)
- [プレイヤー UIオプション](https://developer.vpe.naverncp.com/docs/rn/player-ui)
- [プレイヤー UXオプション](https://developer.vpe.naverncp.com/docs/rn/player-ux)