On this page
Related LinksFAQ

NativeVideo

Requires:
@ray-js/ray≥0.6.9

Description

Native video playback component.

Props

PropertyTypeRequiredDefaultDescription
srcstringYes-URL of the video to play; network URLs are supported. In partitioned deployments, ensure the video is accessible
durationnumberNo-Specify the video duration, in seconds
controlsbooleanNotrueWhether to show the default controls (play/pause button, progress, time)
autoplaybooleanNofalseWhether to autoplay
loopbooleanNofalseWhether to loop
mutedbooleanNofalseWhether to mute
initialTimenumberNo0Initial playback position
showFullscreenBtnbooleanNotrueWhether to show the fullscreen button
showPlayBtnbooleanNotrueWhether to show the play button in the bottom control bar
showCenterPlayBtnbooleanNotrueWhether to show the center play button
objectFit"contain" | "fill" | "cover" | "none"NocontainHow the video is fitted when its size differs from the video container
posterstringNo-Poster image URL
showMuteBtnbooleanNofalseWhether to show the mute button
borderWidthnumberNo0Border width, in px
borderStyle"solid" | "dashed"NosolidBorder style; valid values: solid, dashed
borderColorstringNo#ffffffBorder color, must be hex format
borderRadiusnumberNo0Border radius, in px
borderRadiusTopLeftnumberNo-Top-left border radius, in px
borderRadiusTopRightnumberNo-Top-right border radius, in px
borderRadiusBottomLeftnumberNo-Bottom-left border radius, in px
borderRadiusBottomRightnumberNo-Bottom-right border radius, in px
backgroundColorstringNo#ffffffBackground color, must be hex format
No-Triggers when playback starts or resumes
No-Triggers when playback is paused
No-Triggers when playback reaches the end
No-Triggers when the playback position changes
No-Triggers when entering or exiting fullscreen
No-Triggers when buffering occurs
No-Triggers on playback error
No-Triggers when load progress changes; only a single segment is supported
No-Triggers when video metadata has loaded
No-Triggers when controls visibility toggles
No-Triggers when seek completes
updateLayoutunknownNo-Used for cross-layer components to notify the container layer to update styles

Valid Values

objectFit
ValueDescriptionSince
containPreserve the aspect ratio and display the entire video; the container may have empty space-
fillStretch the video to fill the container without preserving the aspect ratio-
coverPreserve the aspect ratio and fill the container, cropping any overflow-
noneKeep the video's original size without scaling-
borderStyle
ValueDescriptionSince
solidSolid border-
dashedDashed border-
NativeVideoFullscreenChangeDetail.direction
ValueDescriptionSince
verticalPortrait orientation-
horizontalLandscape orientation-

Examples

Basic usage

import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        controls
        style={{ width: '100%', height: '200px' }}
        onPlay={() => console.log('Playback started')}
        onPause={() => console.log('Playback paused')}
        onEnded={() => console.log('Playback ended')}
      />
    </View>
  );
}

Playback configuration and cover

import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        poster="https://vjs.zencdn.net/v/oceans.png"
        controls
        autoplay={false}
        loop
        muted
        initialTime={3}
        objectFit="cover"
        showFullscreenBtn
        showPlayBtn
        showCenterPlayBtn={false}
        showMuteBtn
        style={{ width: '100%', height: '200px' }}
        onError={(e) => console.log('Playback error:', e.detail.errMsg)}
        onWaiting={() => console.log('Buffering')}
        onTimeupdate={(e) => console.log('Progress:', e.detail.currentTime, '/', e.detail.duration)}
      />
    </View>
  );
}

Custom border and events

import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        controls
        borderWidth={2}
        borderStyle="dashed"
        borderColor="#1890ff"
        borderRadius={16}
        backgroundColor="#000000"
        style={{ width: '100%', height: '200px' }}
        onPlay={() => console.log('Play')}
        onPause={() => console.log('Pause')}
        onEnded={() => console.log('Ended')}
        onFullscreenchange={(e) => console.log('Fullscreen:', e.detail.fullScreen, 'Direction:', e.detail.direction)}
        onControlstoggle={(e) => console.log('Controls visible:', e.detail.show)}
        onProgress={(e) => console.log('Buffered:', e.detail.buffered + '%')}
        onLoadedmetadata={(e) => console.log('Metadata:', e.detail.width, 'x', e.detail.height)}
        onSeekcomplete={(e) => console.log('seek:', e.detail.position)}
      />
    </View>
  );
}

Related API: createNativeVideoContext. This is a native component based on off-screen rendering. Please note the native component usage restrictions.

Scan with SmartLife App to Try
Download Sample Code

FAQ

  1. native-video default width is 300px and height is 225px. You can set the width and height via tyss.
  2. For related principles, refer to Native components based on off-screen rendering.
  3. Please note the native component usage restrictions.
  4. Supported video format for native-video: MP4 (MPEG-4 files using H.264 video codec and AAC audio codec).