---
title: "プレイヤー UIのオプション"
slug: "vpe-player-ui-option"
updated: 2026-09-17T09:22:05Z
published: 2026-09-17T09:22:05Z
canonical: "guide.ncloud-docs.com/vpe-player-ui-option"
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

controlBtnプロパティでコントロールバーのボタン UIの使用有無を設定します。 コントロールバーのすべてのボタン UIを表示するように設定するユースケースは、次の通りです。

```
<VpePlayer
    ...
    options={{
          playlist: [ //再生ソース
              {
                  file: 'https://CDNドメイン/example_video_01.mp4'
              },
          ],
          controls: true, // true: ボタンを表示する、false: ボタンを表示しない
          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プロパティでコントロールバーを表示する時間を設定します。 コントロールバーを3秒間表示するように設定するユースケースは、次の通りです。

```
<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){
                  player.current.controlBarBtnStateUpdate({  //例) 動画の長さが10秒未満の場合、ボタンは隠す
                      fullscreen:false, // フルスクリーンボタンを表示しない(true: フルスクリーンボタンを表示する)
                      pictureInPicture:false, // PIPボタンを表示しない(true: PIPボタンを表示する)
                      setting:false, // 設定ボタンを表示しない(true: 設定ボタンを表示する)
                  })
              }
        },
      }}
      options={{
            playlist: [ //再生ソース
                {
                    file: 'https://CDNドメイン/example_video_01.mp4'
                },
            ],
            controlBtn:{
                play:true,
                fullscreen:true,
                volume:true,
                times:true,
                setting:true,
                subtitle:false,
            },
          }}
      ...
  />
)
```

## 字幕 UIの設定

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

```
const playerRef = useRef(null);

return(
  <VpePlayer
      ...
      ref={playerRef}
      
      options={{
            playlist: [ //再生ソース
                {
                    file: 'https://CDNドメイン/example_video_01.mp4'
                },
            ],
            captionStyle: {  // CAPTION環境設定
              fontSize: 12, //字幕のサイズ
              color: '#FFFFFF', //字幕の色
              backgroundColor: 'rgba(0, 0, 0, 0.7)', //背景色
              edgeStyle: 'dropshadow', //テキストのエッジを設定(dropshadow、raised、depressed、uniform)
            },
          }}
      ...
  />
)
```