Video"
m (→clipToFit) |
|||
(29 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
+ | {{ZKComponentReferencePageHeader}} | ||
+ | |||
= Video = | = Video = | ||
Line 4: | Line 6: | ||
*JavaScript API: <javadoc directory="jsdoc">zkmax.med.Video</javadoc> | *JavaScript API: <javadoc directory="jsdoc">zkmax.med.Video</javadoc> | ||
− | + | {{ZK EE}} | |
− | + | since 8.6.0 | |
= Employment/Purpose = | = Employment/Purpose = | ||
− | A <tt> | + | A <tt>Video</tt> component is used to play the video in the browser. Like <tt>audio</tt>, you can either use the <tt>src</tt> property to specify an URL of the video resource, or use the <tt>setContent</tt> method to specify a dynamically generated video. Users can control the video by <tt>play</tt>, <tt>stop</tt> and <tt>pause</tt>. |
= Example = | = Example = | ||
Line 18: | Line 20: | ||
= Supports HTML5 = | = Supports HTML5 = | ||
− | The | + | The Video component is based on HTML 5's <video> tag, and supports the following properties: <tt>src</tt>, <tt>autoplay</tt>, <tt>controls</tt>, <tt>loop</tt>, <tt>playbackRate</tt>, <tt>dimBackground</tt>, <tt>preload</tt>, <tt>clipToFit</tt>, <tt>poster</tt>, <tt>playsinline</tt> and <tt>crossorigin</tt>. |
+ | |||
+ | == Supported Formats == | ||
+ | [https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#File_formats mp4, WebM, ogg] | ||
+ | |||
+ | == Autoplay policy is different between browser == | ||
+ | |||
+ | Please refer to [https://developers.google.com/web/updates/2017/09/autoplay-policy-changes autoplay-policy-changes] and [https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/ auto-play-policy-changes-for-macos] | ||
= Multiple Sources = | = Multiple Sources = | ||
Line 27: | Line 36: | ||
= enableFullScreen = | = enableFullScreen = | ||
− | For security reasons, fullScreen API can only be initiated by an user gesture. Therefore the | + | For security reasons, fullScreen API can only be initiated by an user gesture. Therefore the Video component only provides a client-side method <tt>enableFullScreen()</tt> to enable the full screen mode. |
<source lang="xml" > | <source lang="xml" > | ||
− | + | <video id="player" src="zk.mp4" controls="true"/> | |
− | + | <button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" /> | |
</source> | </source> | ||
= dimBackground = | = dimBackground = | ||
− | The | + | The Video component provides a theater mode, If dimBackground="true", the whole page will be covered by translucent black by default except the Video. |
When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view. | When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view. | ||
Line 58: | Line 67: | ||
= playbackRate = | = playbackRate = | ||
− | The | + | The Video component provides setPlaybackRate(double) to control the video playing speed. The valid value depends on the displayed browser. |
Default: 1.0 | Default: 1.0 | ||
Line 67: | Line 76: | ||
= currentTime = | = currentTime = | ||
− | The | + | The Video component provides <tt>setCurrentTime(double)</tt> to jump to the specified time-point (in seconds) of the playback video. |
<source lang="xml" > | <source lang="xml" > | ||
Line 74: | Line 83: | ||
= playing = | = playing = | ||
− | The | + | The Video component provides <tt>setPlaying(boolean)</tt> to play or pause the video. |
playing="true" is same as invoking <tt>play()</tt>; playing="false" is same as invoking <tt>pause()</tt>. | playing="true" is same as invoking <tt>play()</tt>; playing="false" is same as invoking <tt>pause()</tt>. | ||
Line 83: | Line 92: | ||
= volume = | = volume = | ||
− | The | + | The Video component provides <tt>setVolume(double)</tt> to change the volume. The value should range between 0.0 and 1.0. |
Default: 1.0 | Default: 1.0 | ||
Line 92: | Line 101: | ||
= muted = | = muted = | ||
− | The | + | The Video component provides <tt>setMuted(boolean)</tt> to mute the video. |
Default: false | Default: false | ||
Line 102: | Line 111: | ||
= clipToFit = | = clipToFit = | ||
− | The | + | The Video component provides setClipToFit(boolean) to clip the video when the source size doesn't fit the size specified in the Video tag. |
For example: | For example: | ||
− | The source below is 450 * 320. When you set width="300px", height="320px", blank space will be inserted above and below the video to preserve the aspect ratio ( | + | The source image used in the sample below is 450 * 320. When you set width="300px", height="320px", by default, blank space will be inserted above and below the video to preserve the aspect ratio (left image); when you set clipToFit="true", it will cut off the sides and fill up the space (right image). |
[[file:ClipToFit(false).png]] [[file:ClipToFit(true).png]] | [[file:ClipToFit(false).png]] [[file:ClipToFit(true).png]] | ||
Line 115: | Line 124: | ||
= StateChangeEvent = | = StateChangeEvent = | ||
− | When | + | When you call <tt>play(), stop() or pause()</tt> StateChangeEvent will be triggered. You can check the current state by calling event.getState(). Video has three states, and you can access them by using <tt>Video.PLAY, Video.STOP and Video.PAUSE</tt>. |
For example: | For example: | ||
− | If you want to do something after | + | If you want to do something after the video starts to play, you can write codes as shown below (MVVM style). |
<source language="xml"> | <source language="xml"> | ||
Line 133: | Line 142: | ||
</source> | </source> | ||
− | Video also provides <tt>isPlaying(), isPaused() and isStopped()</tt> methods to check video state. | + | Video component also provides <tt>isPlaying(), isPaused() and isStopped()</tt> methods to check the video state. |
= Supported Events = | = Supported Events = | ||
Line 149: | Line 158: | ||
=Supported Children= | =Supported Children= | ||
− | + | NONE | |
+ | |||
+ | =Version History= | ||
+ | {{LastUpdated}} |
Revision as of 06:43, 12 June 2019
Video
- Available for ZK:
since 8.6.0
Employment/Purpose
A Video component is used to play the video in the browser. Like audio, you can either use the src property to specify an URL of the video resource, or use the setContent method to specify a dynamically generated video. Users can control the video by play, stop and pause.
Example
<video src="zk.mp4" controls="true" autoplay="true" loop="true" />
Supports HTML5
The Video component is based on HTML 5's <video> tag, and supports the following properties: src, autoplay, controls, loop, playbackRate, dimBackground, preload, clipToFit, poster, playsinline and crossorigin.
Supported Formats
Autoplay policy is different between browser
Please refer to autoplay-policy-changes and auto-play-policy-changes-for-macos
Multiple Sources
Most browsers do not support all the video formats, so you can specify multiple source files in different formats for different browsers. If the first format is not supported by the browser, it will fallback to the 2nd format. For example:
<video src="zk.mp4, zk.webm, zk.ogg" />
enableFullScreen
For security reasons, fullScreen API can only be initiated by an user gesture. Therefore the Video component only provides a client-side method enableFullScreen() to enable the full screen mode.
<video id="player" src="zk.mp4" controls="true"/>
<button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" />
dimBackground
The Video component provides a theater mode, If dimBackground="true", the whole page will be covered by translucent black by default except the Video.
When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view.
<video src="zk.mp4" dimBackground="true" />
By default, css of dimBackground has two properties as shown in the following css code.
You can also customize the background in your preference by simply overriding .z-video-dim-background in css.
<style>
.z-video-dim-background {
background: black;
opacity: 0.8;
}
</style>
playbackRate
The Video component provides setPlaybackRate(double) to control the video playing speed. The valid value depends on the displayed browser.
Default: 1.0
<video src="zk.mp4" playbackRate="0.5" />
currentTime
The Video component provides setCurrentTime(double) to jump to the specified time-point (in seconds) of the playback video.
<video src="zk.mp4" currentTime="60" />
playing
The Video component provides setPlaying(boolean) to play or pause the video.
playing="true" is same as invoking play(); playing="false" is same as invoking pause().
<video src="zk.mp4" playing="false" />
volume
The Video component provides setVolume(double) to change the volume. The value should range between 0.0 and 1.0.
Default: 1.0
<video src="zk.mp4" volume="0.5" />
muted
The Video component provides setMuted(boolean) to mute the video.
Default: false
<video src="zk.mp4" muted="true" />
clipToFit
The Video component provides setClipToFit(boolean) to clip the video when the source size doesn't fit the size specified in the Video tag.
For example:
The source image used in the sample below is 450 * 320. When you set width="300px", height="320px", by default, blank space will be inserted above and below the video to preserve the aspect ratio (left image); when you set clipToFit="true", it will cut off the sides and fill up the space (right image).
<video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" />
<video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" clipToFit="true" />
StateChangeEvent
When you call play(), stop() or pause() StateChangeEvent will be triggered. You can check the current state by calling event.getState(). Video has three states, and you can access them by using Video.PLAY, Video.STOP and Video.PAUSE.
For example:
If you want to do something after the video starts to play, you can write codes as shown below (MVVM style).
<video onStateChange="@command('stateChange', event=event)" />
@Command
public void stateChange(@BindingParam("event") StateChangeEvent event) {
if (event.getState() == Video.PLAY) {
// do something...
}
}
Video component also provides isPlaying(), isPaused() and isStopped() methods to check the video state.
Supported Events
Event: StateChangeEvent
Notifies when invoking play(), stop() or pause(). |
- Inherited Supported Events: XulElement
Supported Children
NONE
Version History