WeChat Mini Program Video Component: Best Practices, Pitfalls, and Implementation Guide

Introduction

The author, a full‑stack developer, shares a month‑long experience of integrating a video section into an online education Mini Program, aiming to provide best practices and a pitfall‑avoidance guide.

1. Video Component Usage

1.1 Import Component

To use the video component, include it in the markup. The component exposes 39 attributes and events (the full list is omitted for brevity).

<video id="videoPlayer"/>

1.2 Property Usage

Key visual and functional properties are demonstrated with screenshots. Important attributes include: duration (number) – video length in seconds; mismatched values cause progress bar inconsistencies. show-progress (boolean) – shows progress bar only when width > 240 px. show-mute-btn and mute – should be used together; otherwise the mute icon may be misleading. show-fullscreen-btn, show-play-btn, show-center-play-btn, play-btn-position – control button visibility and placement. show-casting-button, show-screen-lock-button, show-snapshot-button – enable casting, lock screen, and screenshot features. controls (boolean) – toggles the default control bar; setting to false allows custom controls. danmu-list (Array) – defines bullet‑screen data; danmu-btn and enable-danmu control its visibility. autoplay, loop, initial-time, direction, enable-progress-gesture, object-fit, poster, enable-play-gesture, auto-pause-if-navigate, auto-pause-if-open-native, vslide-gesture, vslide-gesture-in-fullscreen, ad-unit-id, picture-in-picture-mode, picture-in-picture-show-progress, enable-auto-rotation – various playback, UI, and advertising controls.

1.3 Bind Events

The component emits events such as timeupdate, ended, play, pause, waiting, progress, loadedmetadata, controlstoggle, enterpictureinpicture, and screenChange. Example of timeupdate handling:

/**
 * timeupdate: {
 *   currentTime: 0.181185, // seconds
 *   duration: 881.458362   // seconds
 * }
 */
timeupdate(e) {
  console.log('timeupdate', e.detail);
}

1.4 API Usage

Create a VideoContext with wx.createVideoContext(id, this) (do not omit this in custom components) and call methods such as play(), pause(), seek(position), requestFullScreen({direction}), exitFullScreen(), sendDanmu({text, color}), etc.

const videoContext = wx.createVideoContext('videoPlayer', this);
videoContext.play();
videoContext.pause();
videoContext.seek(120);
videoContext.requestFullScreen({direction: 90});
videoContext.exitFullScreen();
videoContext.sendDanmu({text: 'Hello', color: '#ff0000'});

2. Mini Program Video Business Sharing

The video section consists of a video list, video detail page, purchased video list, and order list.

2.1 Waterfall Layout

Pure CSS column layout was insufficient; a JavaScript‑plus‑CSS solution using two arrays and flex flow achieved the required waterfall effect.

.waterfall-layout {
  column-count: 2;
  column-width: 340rpx;
  column-gap: 20rpx;
  break-inside: avoid;
}

2.2 Video Permission Interaction

Playback rights depend on product price, free‑tag status, and user membership. Free videos play directly; paid videos require purchase or a free tag.

2.3 Network Interaction

Use wx.getNetworkType() on init and wx.onNetworkStatusChange() during playback to handle Wi‑Fi warnings, data‑usage prompts, and network loss.

wx.getNetworkType({
  success(res) {
    that.setData({ networkType: res.networkType });
  }
});

2.4 Full‑Screen Landscape Playback

Because enable-auto-rotation is ineffective on Android, fullscreen is controlled via videoContext.requestFullScreen and device orientation is detected with wx.onDeviceMotionChange.

2.5 Playback Continuation

When a video ends, the bindtimeupdate event stores the current time locally. On re‑opening, initial-time or seek() restores playback position.

2.6 Video URL Expiration Handling

Video URLs are valid for five hours. A Redis cache stores them; when expired, the app fetches a fresh URL. Errors are caught via the binderror event.

3. Eight Common Pitfalls

Ensure duration matches the real video length; otherwise progress bar is inaccurate. show-progress hides the bar when width ≤ 240 px regardless of its value.

Use show-mute-btn together with mute to avoid a muted icon while audio plays. enable-auto-rotation does not work on Android; use API‑based fullscreen instead.

The bindseekcomplete event may not fire after a seek operation.

When creating VideoContext in a custom component, never omit the this argument. requestFullScreen ignores the device’s orientation lock.

When using onDeviceMotionChange for landscape detection, consider both beta and gamma thresholds to avoid stuck fullscreen states.

- END -