# Vue


Компонент для встраивания Kinescope Player в приложения на Vue 3 (с версии пакета 2.0.0). Под капотом — iframe и [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/). Репозиторий: [kinescope/vue-kinescope-player](https://github.com/kinescope/vue-kinescope-player).

## Установка

```bash
npm install @kinescope/vue-kinescope-player --save
```

## Быстрый старт

Глобальная регистрация:

```js
import { createApp } from 'vue'
import KinescopePlayer from '@kinescope/vue-kinescope-player'
import App from './App.vue'

const app = createApp(App)
app.use(KinescopePlayer)
app.mount('#app')
```

Локально в компоненте:

```vue
<script setup>
import { KinescopePlayer } from '@kinescope/vue-kinescope-player'
</script>

<template>
  <kinescope-player video-id="VIDEO_ID" />
</template>
```

### События

```vue
<template>
  <kinescope-player
    video-id="VIDEO_ID"
    @ready="handleReady"
    @play="handlePlay"
  />
</template>
```

### Методы

Методы доступны через `ref` → `player`:

```vue
<template>
  <div>
    <kinescope-player
      ref="kinescope"
      video-id="VIDEO_ID"
      @ready="ready = true"
    />
    <button :disabled="!ready" @click="kinescope.player.play()">Play</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { KinescopePlayer } from '@kinescope/vue-kinescope-player'

const ready = ref(false)
const kinescope = ref(null)
</script>
```

## Props

В шаблоне — kebab-case (`video-id`), в скрипте — camelCase.

### Основные

| Prop | Тип | По умолчанию | Описание |
| :--- | :--- | :--- | :--- |
| `video-id` | `number \| string` | — | ID видео (**обязательный**) |
| `width` | `number \| string` | `100%` | Ширина |
| `height` | `number \| string` | `100%` | Высота |
| `external-id` | `string` | — | Внешний ID для аналитики |

### Поведение

| Prop | Тип | По умолчанию | Описание |
| :--- | :--- | :--- | :--- |
| `auto-play` | `boolean \| string` | `false` | Автостарт. `'viewable'` — при появлении в viewport, `'hover'` — при наведении |
| `muted` | `boolean` | `false` | Старт без звука |
| `loop` | `boolean` | `false` | Зациклить |
| `plays-inline` | `boolean` | `true` | Inline на мобильных без автоперехода в fullscreen |
| `volume` | `number` | — | Громкость 0–1 (реактивно, без перезагрузки плеера) |
| `playback-rate` | `number` | — | Скорость (1 — обычная; реактивно) |
| `text-track` | `boolean \| string` | — | Субтитры при загрузке: `true` или код языка, например `'ru'` |

### Интерфейс

| Prop | Тип | По умолчанию | Описание |
| :--- | :--- | :--- | :--- |
| `language` | `string` | `en` | Язык UI |
| `controls` | `boolean` | `true` | Все контролы; `false` скрывает и заголовок, и панель |
| `title` | `boolean` | `true` | Заголовок поверх видео |
| `control-bar` | `boolean \| string` | `true` | Нижняя панель; `'always'` — всегда видима |
| `progress-bar` | `boolean` | `true` | Полоса прогресса |
| `main-play-button` | `boolean` | `true` | Большая кнопка Play по центру |
| `play-button` | `boolean` | `true` | Play/Pause на панели |
| `volume-button` | `boolean` | `true` | Кнопка громкости |
| `playback-rate-button` | `boolean` | `false` | Кнопка скорости |
| `playback-rates` | `array \| boolean` | — | Список скоростей, например `[0.5, 1, 1.5, 2]`; `false` скрывает кнопку |
| `subtitles-button` | `boolean` | `true` | Кнопка субтитров |
| `settings-button` | `boolean` | `true` | Кнопка настроек |
| `pip-button` | `boolean` | `true` | Picture-in-Picture |
| `fullscreen-button` | `boolean \| string` | `true` | Fullscreen; `'force'` — показывать всегда |
| `video-fit` | `string` | `contain` | `contain` \| `cover` \| `fill` |
| `watermark` | `string \| object` | — | Водяной знак (строка или объект; реактивно) |

Объект водяного знака:

```ts
{
  text: string
  mode?: 'random' | 'stripes'
  scale?: number
  displayTimeout?: number | { visible: number; hidden: number }
}
```

## События

| Событие | Данные |
| :--- | :--- |
| `js-load` | — |
| `js-load-error` | — |
| `ready` | `{ currentTime, duration, quality, qualityLevels }` |
| `quality-changed` | `{ quality }` |
| `auto-quality-changed` | `{ quality }` |
| `seek-chapter` | `{ position }` |
| `size-changed` | `{ width, height }` |
| `play` | — |
| `playing` | — |
| `waiting` | — |
| `pause` | — |
| `ended` | — |
| `time-update` | `{ currentTime }` |
| `progress` | `{ bufferedTime }` |
| `duration-change` | `{ duration }` |
| `volume-change` | `{ muted, volume }` |
| `playback-rate-change` | `{ playbackRate }` |
| `seeking` | — |
| `seeked` | — |
| `fullscreen-change` | `{ isFullscreen, video }` |
| `call-action` | `{ id, title?, type }` |
| `call-bookmark` | `{ id, time, title? }` |
| `error` | `{ error }` |
| `destroy` | — |

## Методы

Вызов: `kinescope.value.player.play()`.

| Метод | Параметры | Результат |
| :--- | :--- | :--- |
| `isPaused` | — | `Promise<boolean>` |
| `isEnded` | — | `Promise<boolean>` |
| `play` | — | `Promise<void>` |
| `pause` | — | `Promise<boolean>` |
| `stop` | — | `Promise<void>` |
| `getCurrentTime` | — | `Promise<number>` |
| `getDuration` | — | `Promise<number>` |
| `seekTo` | `(time: number)` | `Promise<void>` |
| `isMuted` | — | `Promise<boolean>` |
| `mute` | — | `Promise<void>` |
| `unmute` | — | `Promise<void>` |
| `getVolume` | — | `Promise<number>` |
| `setVolume` | `(value: number)` | `Promise<void>` |
| `getPlaybackRate` | — | `Promise<number>` |
| `setPlaybackRate` | `(value: number)` | `Promise<void>` |
| `getVideoQualityList` | — | `Promise<VideoQuality[]>` |
| `getCurrentVideoQuality` | — | `Promise<VideoQuality>` |
| `setVideoQuality` | `(quality: VideoQuality)` | `Promise<void>` |
| `enableTextTrack` | `(lang: string)` | `Promise<void>` |
| `disableTextTrack` | — | `Promise<void>` |
| `closeCTA` | — | `Promise<void>` |
| `isFullscreen` | — | `Promise<boolean>` |
| `setFullscreen` | `(fullscreen: boolean)` | `Promise<void>` |
| `isPip` | — | `Promise<boolean>` |
| `setPip` | `(pip: boolean)` | `Promise<void>` |
| `getPlaylistItem` | — | `Promise<object>` |
| `switchTo` | `(id: string)` | `Promise<void>` |
| `next` | — | `Promise<void>` |
| `previous` | — | `Promise<void>` |

## Что дальше?

- [React](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/react/)
- [Angular](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/angular/)
- [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/)