react-native-expo-video-player 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 xiaocheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# react-native-expo-video-player
+
+[![npm version](https://img.shields.io/npm/v/react-native-expo-video-player?style=flat-square)](https://www.npmjs.com/package/react-native-expo-video-player)
+[![license](https://img.shields.io/npm/l/react-native-expo-video-player?style=flat-square)](https://github.com/xiaocheng121380/react-native-expo-video-player/blob/main/LICENSE)
+[![platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey?style=flat-square)](https://reactnative.dev/)
+[![expo](https://img.shields.io/badge/expo-%E2%89%A551-blue?style=flat-square&logo=expo)](https://expo.dev/)
+[![runs with expo](https://img.shields.io/badge/Runs%20with%20Expo-4630EB.svg?style=flat-square&logo=EXPO&labelColor=f3f3f3&logoColor=000)](https://expo.dev/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/xiaocheng121380/react-native-expo-video-player/pulls)
+[![GitHub stars](https://img.shields.io/github/stars/xiaocheng121380/react-native-expo-video-player?style=flat-square)](https://github.com/xiaocheng121380/react-native-expo-video-player/stargazers)
+
+基于 [`expo-video`](https://docs.expo.dev/versions/latest/sdk/video/) 构建的功能丰富的 React Native 视频播放器组件，开箱即用的自定义控制栏、全屏手势和倍速切换。
+
+## 功能特性
+
+- 🎬 自定义浮层控制栏（播放/暂停、进度条、倍速切换、全屏）
+- 🖐️ 全屏手势：左侧上下滑 = 音量，右侧上下滑 = 亮度，水平滑 = 快进快退
+- ⏩ 倍速选择器（0.5x – 2x）
+- 🎞️ 画质选择器（通过不同 URL 切换画质，自动保持播放进度）
+- 📱 控制栏自动隐藏，超时可配置
+- 🔄 全屏管理 Hook（屏幕方向锁定 & 状态栏隐藏）
+- 🎨 支持主题色自定义
+- 🍎 iOS 滑块缩略图优化（内置 14px 小圆点图片）
+- 🤖 Android 返回键自动退出全屏
+- 🔀 完整透传 `VideoView` 原生属性（`contentFit`、`allowsPictureInPicture` 等）
+
+## 安装
+
+```bash
+npx expo install react-native-expo-video-player expo-video expo-brightness expo-screen-orientation react-native-safe-area-context @react-native-community/slider
+```
+
+## 快速开始
+
+```tsx
+import { useVideoPlayer } from 'expo-video';
+import { ExpoVideoPlayer, useFullscreen } from 'react-native-expo-video-player';
+
+export default function Player() {
+  const player = useVideoPlayer(null);
+  const { isFullscreen, toggleFullscreen } = useFullscreen();
+
+  useEffect(() => {
+    player.replaceAsync('https://example.com/video.mp4').then(() => player.play());
+  }, []);
+
+  return (
+    <ExpoVideoPlayer
+      player={player}
+      isFullscreen={isFullscreen}
+      onToggleFullscreen={toggleFullscreen}
+      onBack={() => navigation.goBack()}
+      theme={{ primary: '#FF6B00' }}
+    />
+  );
+}
+```
+
+## 组件
+
+### `<ExpoVideoPlayer>`
+
+主组件，渲染 expo-video 的 `VideoView` 并叠加自定义控制栏。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `player` | `VideoPlayer` | **必填** | expo-video 播放器实例 |
+| `theme` | `VideoPlayerTheme` | `{ primary: '#2979FF' }` | 主题色配置 |
+| `isFullscreen` | `boolean` | `false` | 当前是否全屏 |
+| `onToggleFullscreen` | `() => void` | `() => {}` | 全屏切换回调 |
+| `onBack` | `() => void` | `() => {}` | 返回按钮回调 |
+| `speedOptions` | `number[]` | `[0.5, 0.75, 1, 1.25, 1.5, 2]` | 可选倍速 |
+| `speedLabel` | `string` | `'倍速'` | 1x 速度时显示的文字 |
+| `autoHideTimeout` | `number` | `3000` | 控制栏自动隐藏时间（毫秒） |
+| `enableGestures` | `boolean` | `true` | 是否启用全屏手势 |
+| `showSpeedPicker` | `boolean` | `true` | 是否显示倍速按钮 |
+| `showFullscreenButton` | `boolean` | `true` | 是否显示全屏按钮 |
+| `showQualityPicker` | `boolean` | `false` | 是否显示画质选择按钮 |
+| `qualityLabel` | `string` | `'画质'` | "自动"画质时按钮上显示的文字 |
+| `qualityOptions` | `Array<{ label, url }>` | `[]` | 画质选项列表，如 `[{ label: '1080p', url: '...' }]` |
+| `onQualityChange` | `(quality \| null) => void` | `() => {}` | 画质切换回调，`null` 表示选了"自动" |
+| `thumbImage` | `ImageSource` | 内置 14px 圆点 | 自定义滑块拇指图片 |
+| `width` | `number` | 窗口宽度 | 视频容器宽度 |
+| `height` | `number` | width × 9/16 | 视频容器高度 |
+| `...videoViewProps` | `VideoViewProps` | - | **所有原生 `VideoView` 属性均会透传** |
+
+#### 透传的 VideoView 属性
+
+所有 expo-video 的 `VideoView` 原生属性均会透传到底层组件，包括但不限于：
+
+| 属性 | 说明 |
+|------|------|
+| `contentFit` | `'contain'` / `'cover'` / `'fill'` — 视频缩放模式 |
+| `contentPosition` | `{ dx, dy }` — 视频位置偏移（iOS） |
+| `allowsPictureInPicture` | 启用画中画模式 |
+| `startsPictureInPictureAutomatically` | 后台自动进入画中画 |
+| `allowsVideoFrameAnalysis` | 视频中的实况文本（iOS 16+） |
+| `requiresLinearPlayback` | 禁止用户拖拽进度 |
+| `showsTimecodes` | 显示/隐藏时间码（iOS） |
+| `surfaceType` | `'surfaceView'` / `'textureView'`（Android） |
+| `useExoShutter` | ExoPlayer 快门（Android） |
+| `onFirstFrameRender` | 首帧渲染回调 |
+| `onPictureInPictureStart` | 画中画开始回调 |
+| `onPictureInPictureStop` | 画中画结束回调 |
+
+### `<VideoControls>`
+
+控制栏浮层组件，如果你想配合自己的 `VideoView` 单独使用。
+
+### `<PlayerIcon>`
+
+基于 Unicode 的轻量级图标组件，内部使用。可用图标：`play`、`pause`、`arrow-left`、`fullscreen`、`fullscreen-exit`、`fast-forward`、`rewind`、`volume-off`、`volume-medium`、`volume-high`、`brightness-6`。
+
+## Hooks
+
+### `useFullscreen(initialFullscreen?: boolean)`
+
+管理全屏状态，包括屏幕方向锁定、状态栏显隐和 Android 返回键处理。
+
+```tsx
+const { isFullscreen, enterFullscreen, exitFullscreen, toggleFullscreen } = useFullscreen();
+```
+
+## 全屏手势
+
+全屏模式下且 `enableGestures` 开启时：
+
+| 手势 | 操作 |
+|------|------|
+| 左侧上下滑动 | 调节音量 |
+| 右侧上下滑动 | 调节亮度 |
+| 水平滑动 | 快进/快退 |
+| 单击 | 显示/隐藏控制栏 |
+| 双击 | 播放/暂停 |
+
+## 主题定制
+
+```tsx
+<ExpoVideoPlayer
+  player={player}
+  theme={{
+    primary: '#FF6B00',    // 滑块颜色、选中状态
+    text: '#ffffff',       // （预留）
+    textSecondary: '#aaa', // （预留）
+  }}
+/>
+```
+
+## 画质切换
+
+画质切换通过不同 URL 实现，适配国内大部分视频平台的分发方式：
+
+```tsx
+<ExpoVideoPlayer
+  player={player}
+  showQualityPicker
+  qualityOptions={[
+    { label: '1080p', url: 'https://cdn.example.com/video_1080p.mp4' },
+    { label: '720p', url: 'https://cdn.example.com/video_720p.mp4' },
+    { label: '480p', url: 'https://cdn.example.com/video_480p.mp4' },
+  ]}
+  onQualityChange={(quality) => {
+    console.log('切换画质:', quality?.label ?? '自动');
+  }}
+/>
+```
+
+切换时会自动记住当前播放进度，通过 `replaceAsync` 加载新 URL 后恢复到之前的位置继续播放。选择"自动"时使用列表中第一个 URL。
+
+## 从 expo-video 重新导出
+
+为方便使用，以下常用符号从 `expo-video` 重新导出：
+
+```tsx
+// 组件和 hooks
+import { useVideoPlayer, VideoView, createVideoPlayer, isPictureInPictureSupported } from 'react-native-expo-video-player';
+
+// 类型
+import type { VideoSource, VideoPlayer, VideoPlayerStatus, VideoContentFit, DRMOptions, BufferOptions, VideoMetadata } from 'react-native-expo-video-player';
+```
+
+## Peer Dependencies
+
+| 依赖 | 最低版本 |
+|------|----------|
+| `expo` | >= 51 |
+| `expo-video` | >= 2 |
+| `expo-brightness` | >= 12 |
+| `expo-screen-orientation` | >= 7 |
+| `react` | >= 18 |
+| `react-native` | >= 0.75 |
+| `react-native-safe-area-context` | >= 4 |
+| `@react-native-community/slider` | >= 4 |
+
+> 所有 expo 相关依赖均声明为 `peerDependencies`，不会与宿主项目的版本冲突。
+
+## 兼容性
+
+| 平台 | 支持情况 |
+|------|----------|
+| iOS | ✅ |
+| Android | ✅ |
+| Web | ❌（expo-video 暂不支持 Web） |
+
+## 参与贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'feat: 添加新功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 提交 Pull Request
+
+## 致谢
+
+- [expo-video](https://docs.expo.dev/versions/latest/sdk/video/) — Expo 官方视频播放模块
+- [expo-brightness](https://docs.expo.dev/versions/latest/sdk/brightness/) — 亮度调节
+- [expo-screen-orientation](https://docs.expo.dev/versions/latest/sdk/screen-orientation/) — 屏幕方向控制
+- [@react-native-community/slider](https://github.com/callstack/react-native-slider) — 进度条滑块组件
+
+## 技术交流
+
+[![QQ群](https://img.shields.io/badge/QQ%E7%BE%A4-1048378204-blue?style=flat-square&logo=tencentqq&logoColor=white)](https://qm.qq.com/q/1048378204)
+
+欢迎加入 QQ 技术交流群：**1048378204**，一起讨论 React Native、Expo 和移动端开发。
+
+## 开源协议
+
+[MIT](./LICENSE) © [xiaocheng](https://github.com/xiaocheng121380)

package/lib/ExpoVideoPlayer.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { ExpoVideoPlayerProps } from './types';
+/**
+ * 开箱即用的视频播放器组件，基于 `expo-video` 构建。
+ *
+ * 提供自定义浮层控制栏：播放/暂停、进度条、倍速切换、
+ * 全屏切换、全屏手势（音量/亮度/快进快退）。
+ *
+ * 所有原生 `VideoView` 属性（如 `contentFit`、`allowsPictureInPicture`、
+ * `surfaceType`、`onFirstFrameRender`、`onPictureInPictureStart` 等）
+ * 均会透传给底层 `VideoView` 组件。
+ *
+ * 可使用本包的 `useFullscreen()` hook 管理全屏状态，
+ * 也可自行提供 `isFullscreen` / `onToggleFullscreen`。
+ */
+export declare const ExpoVideoPlayer: React.FC<ExpoVideoPlayerProps>;

package/lib/ExpoVideoPlayer.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { View, StyleSheet, useWindowDimensions } from 'react-native';
+import { VideoView } from 'expo-video';
+import { VideoControls } from './VideoControls';
+const DEFAULT_THEME = { primary: '#2979FF' };
+const DEFAULT_SPEED_OPTIONS = [0.5, 0.75, 1, 1.25, 1.5, 2];
+/**
+ * 开箱即用的视频播放器组件，基于 `expo-video` 构建。
+ *
+ * 提供自定义浮层控制栏：播放/暂停、进度条、倍速切换、
+ * 全屏切换、全屏手势（音量/亮度/快进快退）。
+ *
+ * 所有原生 `VideoView` 属性（如 `contentFit`、`allowsPictureInPicture`、
+ * `surfaceType`、`onFirstFrameRender`、`onPictureInPictureStart` 等）
+ * 均会透传给底层 `VideoView` 组件。
+ *
+ * 可使用本包的 `useFullscreen()` hook 管理全屏状态，
+ * 也可自行提供 `isFullscreen` / `onToggleFullscreen`。
+ */
+export const ExpoVideoPlayer = ({ player, theme, isFullscreen = false, onToggleFullscreen = () => { }, onBack = () => { }, speedOptions = DEFAULT_SPEED_OPTIONS, speedLabel = '倍速', autoHideTimeout = 3000, enableGestures = true, showSpeedPicker = true, showFullscreenButton = true, showQualityPicker = false, qualityLabel = '画质', qualityOptions = [], onQualityChange = () => { }, thumbImage, width: propWidth, height: propHeight, 
+// --- 剩余属性全部透传给 VideoView ---
+...videoViewProps }) => {
+    const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+    const resolvedTheme = { ...DEFAULT_THEME, ...theme };
+    const videoWidth = isFullscreen ? windowWidth : (propWidth ?? windowWidth);
+    const videoHeight = isFullscreen ? windowHeight : (propHeight ?? videoWidth * 9 / 16);
+    return (_jsxs(View, { style: isFullscreen ? styles.fullscreenContainer : { width: videoWidth, height: videoHeight }, children: [_jsx(VideoView, { player: player, style: styles.video, nativeControls: false, ...videoViewProps }), _jsx(VideoControls, { player: player, theme: resolvedTheme, isFullscreen: isFullscreen, onToggleFullscreen: onToggleFullscreen, onBack: onBack, speedOptions: speedOptions, speedLabel: speedLabel, autoHideTimeout: autoHideTimeout, enableGestures: enableGestures, showSpeedPicker: showSpeedPicker, showFullscreenButton: showFullscreenButton, showQualityPicker: showQualityPicker, qualityLabel: qualityLabel, qualityOptions: qualityOptions, onQualityChange: onQualityChange, thumbImage: thumbImage })] }));
+};
+const styles = StyleSheet.create({
+    fullscreenContainer: {
+        ...StyleSheet.absoluteFillObject,
+        backgroundColor: '#000',
+        zIndex: 999,
+    },
+    video: {
+        width: '100%',
+        height: '100%',
+    },
+});

package/lib/PlayerIcon.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import { type TextStyle } from 'react-native';
+interface IconProps {
+    name: string;
+    size?: number;
+    color?: string;
+    style?: TextStyle;
+}
+export declare const PlayerIcon: React.FC<IconProps>;
+export {};

package/lib/PlayerIcon.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text, StyleSheet } from 'react-native';
+/**
+ * 基于 Unicode 符号的轻量级图标组件，无需引入外部图标库。
+ * 如需替换图标，使用者可通过 render props 自行覆盖。
+ */
+const ICONS = {
+    play: '▶',
+    pause: '❚❚',
+    'arrow-left': '←',
+    fullscreen: '⛶',
+    'fullscreen-exit': '⛶',
+    'fast-forward': '⏩',
+    rewind: '⏪',
+    'volume-off': '🔇',
+    'volume-medium': '🔉',
+    'volume-high': '🔊',
+    'brightness-4': '☀',
+    'brightness-6': '☀',
+    'brightness-7': '☀',
+};
+export const PlayerIcon = ({ name, size = 22, color = '#fff', style }) => {
+    const icon = ICONS[name] || '?';
+    return (_jsx(Text, { style: [styles.icon, { fontSize: size * 0.75, color, lineHeight: size }, style], children: icon }));
+};
+const styles = StyleSheet.create({
+    icon: {
+        textAlign: 'center',
+    },
+});

package/lib/VideoControls.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { VideoControlsProps } from './types';
+export declare const VideoControls: React.FC<VideoControlsProps>;