---
title: "プレイヤー UI"
slug: "vpe-react-player-ui"
updated: 2026-09-17T09:22:05Z
published: 2026-09-17T09:22:05Z
canonical: "guide.ncloud-docs.com/vpe-react-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(画面アスペクト比)

プレイヤー領域の画面アスペクト比を設定します。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        aspectRatio: '16/9', //アスペクト比を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

### objectFit(全画面表示)

動画が画面領域に合わせる方法を設定します。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        objectFit: "cover", // 動画の表示方法を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

### language(多言語)

プレイヤーで使用する言語を設定します。設定しない場合は、ブラウザで設定されている言語に従います。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        lang: "ko", // 言語設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## コントロールバー

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

デフォルトコントロールバー UIの表示有無を設定します。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controls: true, // コントロールバーの表示有無を設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

コントロールバーボタンの表示/非表示を個別に設定します。

              参考

              

Standard料金プランでのみご利用いただけます。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controlBtn: {
          play: true,             // 再生
          progressBar: true,      // コントロールバー
          fullscreen: true,       // 全画面表示
          volume: true,           // ボリューム
          times: true,            // 残り時間
          pictureInPicture: true, // PIP
          setting: true,          // 設定
          subtitle: true,         // 字幕
        },
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

コントロールバーの進行状況の色を設定します。

              参考

              

Standard料金プランでのみご利用いただけます。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        progressBarColor: "#2e6ae0", // コントロールバーの進捗状況の色を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

コントロールバーが表示される時間を設定します。

              参考

              

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controlActiveTime: 3000, // コントロールバーの表示時間を設定(ms)
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

### ui(コントロールバー UI固定)

UIのタイプを指定します。

              参考

              

Standard料金プランでのみご利用いただけます。

- モバイル UIは `touchGestures`、PC UIは `keyboardShortcut`を提供します。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        ui: "mobile", // UIタイプを設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## 字幕

### 字幕設定(VTT)

VTT字幕をリンクします。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
            poster: "https://CDNドメイン/example_video_01.png",
            vtt: [
              {
                id: "ko",
                file: "https://CDNドメイン/example_video_01.vtt",
                label: "韓国語",
                default: true, // デフォルトの字幕設定
              },
            ],
          },
        ],
      }}
    />
  );
}
```

### captionType(字幕のレンダリング方式)

字幕の描画方法を決定するオプションです。`&quot;html&quot;` (デフォルト)、`&quot;native&quot;`の中から選択でき、デザインの一貫性を優先するか、OSのアクセシビリティ設定を優先するかによって異なります。

| 項目 | `&quot;html&quot;` (デフォルト) | `&quot;native&quot;` |
| --- | --- | --- |
| レンダリング主体 | SDKがプレイヤーの上に直接 `&lt;div&gt;`で字幕を描画 | ブラウザ/OSのデフォルト `::cue` レンダリングを使用 |
| captionStyleオプション | すべて適用(インラインスタイルで直接制御) | 無視(ブラウザごとの `::cue` 対応状況の違いにより、一貫したスタイリングができない) |
| OSのアクセシビリティ字幕設定 | 影響なし(モバイルネイティブ字幕 UIは `track.mode=&quot;hidden&quot;`でブロックされているため、一貫したスタイルが維持される) | そのまま反映(iOS**設定 > アクセシビリティ > 標準字幕とバイアフリー字幕**、Android**設定 > ユーザー補助 > 自動字幕起こし**をそのまま反映) |
| おすすめケース | デザインの一貫性を最優先(ダークモード UI、ブランドカラー字幕など) | ウェブアクセシビリティを最優先(視覚支援ポリシー上、OSのアクセシビリティ設定を必ず遵守する必要があるサービス) |

              参考

              

ウェブアクセシビリティ(WCAG)ガイドラインに従い、字幕のフォント、サイズ、色は、ユーザーが直接調整できるようにする必要があります。`captionType: &quot;native&quot;`は、OSが提供するアクセシビリティの字幕設定をそのまま反映しているため、視覚支援を必要とするユーザーにとって最も自然な体験を提供します。

**htmlモード: captionStyleで直接スタイリング(デフォルト)**

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    captionType: "html", // 省略可能 — デフォルト値
    captionStyle: {
      fontSize: 20,
      color: "#FFFF00",
      edgeStyle: "uniform",
    },
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [{ id: "ko", file: "https://CDNドメイン/example_video_01.vtt", label: "韓国語", default: true }],
      },
    ],
  }}
/>
```

**nativeモード: OSのアクセシビリティ設定にある字幕設定をそのまま反映**

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    captionType: "native",
    // captionStyleは適用されない
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [{ id: "ko", file: "https://CDNドメイン/example_video_01.vtt", label: "韓国語", default: true }],
      },
    ],
  }}
/>
```

### captionStyle(字幕スタイル)

字幕のフォントサイズ、色、背景、縁取り、行間、位置などをオプションで直接設定します。`captionType`が `&quot;html&quot;` (デフォルト)の場合にのみ適用され、`&quot;native&quot;` モードでは無視されます。ブランドカラーやダークモード UIなど、一貫した字幕のスタイリングが必要な場合に利用できます。

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [
          {
            id: "ko",
            file: "https://CDNドメイン/example_video_01.vtt",
            label: "韓国語",
            default: true,
          },
        ],
      },
    ],
    captionStyle: {
      fontSize: {
        pc: 18,      // 字幕のフォントサイズ(pxまたは%)
        mobile: 14,
      },
      color: "#ffffff",
      edgeStyle: "uniform",  // テキストの縁取り(dropshadow、raised、depressed、uniform)
      bottomOffset: {
        pc: 30,      // コントロールバーと重ならないよう、もっと上へ
        mobile: 50,
      },
      sidePadding: {
        pc: 60,      // 左右の余白をもっと広く
        mobile: 40,
      },
      lineHeight: {
        pc: 1,       // 字幕の行間を狭く
        mobile: 1.2,
      },
    },
  }}
/>
```

**captionStyleプロパティ**

指定がない場合はデフォルト値が自動的に適用され、オプションが指定された場合はデフォルト値と deep-mergeされます。(例: `{ fontSize: 20 }`さえ超えたら `fontSize=20` + 残りはデフォルト値)

レスポンシブ分岐: `fontSize`、`lineHeight`、`bottomOffset`、`sidePadding`は単一の値または `{ pc, mobile }` オブジェクトとして指定できます。

| プロパティ | タイプ | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| `fontSize` | `number \\| string \\| { pc?, mobile? }` | `{ pc: 20, mobile: 14 }` | 字幕のフォントサイズ(px/CSS単位)。PC/モバイルの分岐に対応 |
| `fontFamily` | `string` | — | 字幕のフォント(CSS font-family) |
| `color` | `string` | `#ffffff` | 字幕の文字色(CSSの色値) |
| `backgroundColor` | `string` | `transparent` | 字幕ボックスの背景色。例: `rgba(0,0,0,0.4)` |
| `opacity` | `number` | `1` | 字幕テキスト全体の不透明度(0~1) |
| `lineHeight` | `number \\| string \\| { pc?, mobile? }` | `{ pc: 1.3, mobile: 1.2 }` | 字幕の行間(倍数)。PC/モバイルの分岐に対応 |
| `edgeStyle` | `none \\| dropshadow \\| raised \\| depressed \\| uniform` | `uniform` | テキストの縁取り方法(明るい画像/暗い画像のいずれでも読みやすさが優れている) |
| `bottomOffset` | `number \\| { pc?, mobile? }` | `{ pc: 30, mobile: 10 }` | プレイヤー下部からの間隔(px)。コントロールバーと重ならないように調整。PC/モバイルの分岐に対応 |
| `sidePadding` | `number \\| { pc?, mobile? }` | `{ pc: 60, mobile: 40 }` | 左/右の安全領域(px)。PC/モバイルの分岐に対応 |
| `padding` | `number \\| string` | `3px 5px` | 字幕テキストボックス内部のパディング(CSSの padding値) |

              参考

              

edgeStyleの種類: `none` (効果なし) / `dropshadow` (影) / `raised` (浮き出るような効果) / `depressed` (沈み込むような効果) / `uniform` (4方向の輪郭線、デフォルト推奨)

## レイアウトシステム

レイアウトシステムを使用すると、コントロールバーのボタンの配置、領域の構成、カスタムコンポーネントの挿入を、JSONベースで宣言型に定義できます。画面環境別(PC/モバイル/全画面)およびコンテンツのタイプ別(VOD/Live)に、それぞれ分けて管理できます。

              参考

              

- Standard料金プランでのみご利用いただけます。
- レイアウトの JSONは、[UI Editor](https://vpe-player-editor.web.app/)で視覚的に編集し、その結果をそのままコードに反映させることができます。詳細な構造やプロパティについては、[レイアウトシステムガイド](https://developer.vpe.naverncp.com/docs/ja/layout-system)をご参照ください。

### デフォルトレイアウトの構成

`order`でセクションの順序を決め、各セクションに Rowを配置します。Rowの `items`には、ビルトインコンポーネントやカスタム要素を配置できます。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["ProgressBar"] },
        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: ["SettingBtn", "PipBtn", "FullscreenBtn"], wrapper: "Group" },
      ],
    },
  },
};

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      layout={layout}
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

### レイアウトタイプ

`layout` propは、次の3つの形式で渡すことができます。

```
// 1) 単一レイアウト — ライブ/VOD/デバイスの分岐なしに、1つのコントロールバーを構成
type ControlBarLayout = {
  order?: string[];
  top?: Group[];
  upper?: Group[];
  center?: Group[];
  lower?: Group[];
  bottom?: Group[];
};

// 2) ライブ / VODを分岐
type ControlBarLayoutVariant = {
  live: ControlBarLayout;
  vod: ControlBarLayout;
};

// 3) レスポンシブ(PC / Mobile / Fullscreenを分岐)
type ControlBarLayoutResponsive = {
  pc: { live: ControlBarLayout; vod: ControlBarLayout };
  mobile: { live: ControlBarLayout; vod: ControlBarLayout };
  fullscreen: { live: ControlBarLayout; vod: ControlBarLayout };
  breakpoint?: number; // デフォルト768
};
```

### 構成構造

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

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

`layout.json`

### セクションと順序

`order` 配列によってレンダリング順序が決まります。デフォルトセクションは `top`、`upper`、`center`、`lower`、`bottom`です。

```
{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "items": ["MetaDesc"] },
    { "wrapper": "Blank", "items": [], "align": "left" },
    { "items": ["ShareBtn"] }
  ],
  "center": [
    { "items": ["BigPlayBtn"], "align": "center" }
  ],
  "bottom": [
    { "items": ["ProgressBar"] },
    { "items": ["PlayBtn", "VolumeBtn", "TimeDisplay"], "align": "left" },
    { "items": ["SettingBtn", "PIPBtn", "FullscreenBtn"], "align": "right" }
  ]
}
```

`pc.vod.json`

### 行(Row)の構成

各セクションは複数の Rowで構成されています。Rowは、`items` 配列を通じてボタンやコンポーネントを配置し、`align`および `wrapper`でソートやグループ化の方法を調整します。

| キー | タイプ | 説明 |
| --- | --- | --- |
| `key` | `string` | Group識別子。ランタイム `layout()` のマージ時、同じ `key`の Group同士を交換(推奨) |
| `items` | `(string \\| ReactNode)[]` | Rowに配置するコントロールリスト(ビルトインキーまたはカスタムコンポーネント) |
| `align` | `left \\| center \\| right` | Row内のコンテンツのソート方法 |
| `wrapper` | `&quot;Group&quot; \\| &quot;Blank&quot;` | Rowに適用するラッパータイプ(Group＝グループ化、Blank＝空白/間隔) |
| `cap` | `number` | Row内の表示アイテム数を制限 |
| `noPadding` | `boolean` | Group左右のパディングを削除 |

### デフォルトレイアウトのユースケース

各 Groupに `key`を指定すると、ランタイムのマージ時に特定の Groupのみを安全に置き換えられます。

```
const layout: ControlBarLayout = {
  top: [],
  center: [{ key: "bigPlayBtn", items: ["BigPlayBtn"] }],
  bottom: [
    { key: "play",   items: ["PlayBtn"],    wrapper: "Group", noPadding: true },
    { key: "volume", items: ["VolumeBtn"],  wrapper: "Group" },
    { key: "time",   items: ["TimeBtn"],    wrapper: "Group" },
    { key: "blank",  wrapper: "Blank",      items: [] },
    { key: "right",  items: ["SubtitleBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
  ],
};
```

### カスタムコンポーネントの挿入

レイアウトの `items` 配列に、ビルトインキーの代わりに自作のコンポーネントを渡すことで、コントロールバー内の希望する位置にカスタム UIを配置できます。

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// カスタムロゴのコンポーネント
function Logo() {
  return (
    <div style={{ padding: "0 15px" }}>
      <a href="https://example.com" target="_blank">
        <img
          src="https://example.com/logo.webp"
          style={{ height: 24 }}
          alt="Logo">
      </a>
    </div>
  );
}

const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["PlayBtn", "PrevBtn", "NextBtn"], wrapper: "Group" },
        { items: ["VolumeBtn"], wrapper: "Group" },
        { items: ["TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: [Logo()], wrapper: "Group" }, // カスタムコンポーネント
        { items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
      ],
    },
  },
};

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      layout={layout}
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

### リアルタイム変更(ref)

`playerRef.current?.layout(nextLayout, merge?)` を呼び出すと、再生中でもレイアウトを動的に変更できます。2番目の引数 `merge`のデフォルト値は `true`です。

**マージルール(merge: true)**

1. `top` / `upper` / `center` / `lower` / `bottom` / `order` のうち、nextで定義されていないセクションは baseのまま維持
2. section内の Groupマージは `key` ベース:
  - baseと nextにある同じ keyの Group → nextに置き換え
  - baseにのみある key → baseを維持
  - nextにのみある key → 結果の末尾に append
  - nextに keyがない Group → 結果の末尾に append(新規追加とみなす)
3. 両方の Groupに keyがない場合 → section丸ごと置き換え(下位互換)

**例: 特定の Groupのみ置き換え**

```
// base (default pcLayout.vod)
// bottom: [
//   { key: "play",   items: ["PlayBtn"] },
//   { key: "volume", items: ["VolumeBtn"] },
//   { key: "time",   items: ["TimeBtn"] },
//   { key: "blank",  wrapper: "Blank", items: [] },
//   { key: "right",  items: ["SubtitleBtn", "FullscreenBtn"] },
// ]

playerRef.current?.layout({
  bottom: [{ key: "right", items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"] }],
});
// 結果: play/volume/time/blankを維持、rightのみ置き換え
```

**例: 新しい Groupを追加**

```
playerRef.current?.layout({
  bottom: [{ key: "extra", items: ["ShareBtn"] }],
});
// 結果: 既存の5つの Group + 末尾に extra(ShareBtn) append
```

**例: section全体を置き換え(merge: false)**

```
playerRef.current?.layout(
  { bottom: [{ items: ["PlayBtn"] }] },
  false, // 丸ごと置き換え
);
```