caveman-ve-ui

从 basis-admin-pc 抽离的课程视频播放器（CourseVideo）与全局小窗宿主（CourseVideoFloatingHost），基于 Vue 3、Element Plus、Plyr、Pinia。

目录结构

├─ src
│   ├─ components
│   │   ├─ CourseVideo
│   │   │   ├─ index.ts
│   │   │   └─ CourseVideo.vue
│   │   ├─ CourseVideoFloatingHost
│   │   │   ├─ index.ts
│   │   │   └─ CourseVideoFloatingHost.vue
│   │   └─ index.ts
│   ├─ styles
│   │   └─ index.scss
│   ├─ stores
│   ├─ types
│   ├─ utils
│   └─ index.ts
├─ dist
├─ package.json
├─ vite.config.ts
└─ README.md

依赖（peer）

• vue ^3.4
• element-plus ^2.4
• @element-plus/icons-vue ^2.3
• pinia ^2.1
• lodash-es ^4.17
• plyr ^3.7

业务项目需已注册 Pinia，并引入 Element Plus 样式（含 CSS 变量，组件使用了 --el-text-color-* 等）。

其他项目如何引入

1. 安装：npm install caveman-ve-ui（或 file:相对路径 / 私有 registry）。
2. 安装 peer：vue、element-plus、@element-plus/icons-vue、pinia、lodash-es、plyr（版本见本包 peerDependencies）。
3. 样式：在入口增加 import "caveman-ve-ui/styles"。
4. Pinia：app.use(createPinia()) 必须在渲染使用本库组件的页面之前执行。
5. 组件：二选一——全局 app.use(CavemanVeUI) 后模板里写 <CourseVideo />；或 局部 import { CourseVideo, CourseVideoFloatingHost } from "caveman-ve-ui" 再在 components / <script setup> 中使用。
6. 小窗：应用内（如根 App.vue）只放置 一个 <CourseVideoFloatingHost />。

使用

全局注册（推荐与 app.use 配合）

业务入口需 先 app.use(pinia)，再注册本库（组件内会用到 useCourseVideoPlayerStore）：

import { createApp } from "vue"
import { createPinia } from "pinia"
import CavemanVeUI from "caveman-ve-ui"
import "caveman-ve-ui/styles"

const app = createApp(App)
app.use(createPinia())
app.use(CavemanVeUI)

等价于调用 install(app)，会全局注册组件名 CourseVideo、CourseVideoFloatingHost。

按需引入

import {
  CourseVideo,
  CourseVideoFloatingHost,
  install,
  useCourseVideoPlayerStore
} from "caveman-ve-ui"
import "caveman-ve-ui/styles" // 可选，见 src/styles/index.scss

// 也可手动：install(app)

在应用根布局（如 App.vue）挂载一次小窗宿主：

<CourseVideoFloatingHost />

页面中使用播放器；若需在关闭弹窗时把正在播放的实例迁入小窗，设置 auto-float-on-unmount：

<CourseVideo
  :src="videoUrl"
  :slices="slices"
  :auto-float-on-unmount="true"
/>

本地调试（修改组件库实时生效）

核心思路：不要让业务项目去跑 node_modules/caveman-ve-ui/dist，而是用 Vite resolve.alias 把包名指到本仓库的 src/index.ts，由业务/演示应用的 Dev Server 直接编译源码，这样改 .vue / .ts 会走与普通页面一样的 HMR。

方式一：本仓库自带 playground（推荐）

cd caveman-ve-ui
npm install
cd playground && npm install && npm run dev

或在仓库根目录：

npm run playground

浏览器默认打开 http://localhost:5174。编辑上一级 src/ 下组件库源码即可热更新。

方式二：在业务项目（如 basis-admin-pc）里联调

在业务项目的 vite.config.ts 里增加（路径按实际目录调整）：

import path from "node:path"

const useLocalCavemanVeUi = process.env.LOCAL_CAVEMAN_VE_UI === "1"

export default defineConfig({
  resolve: {
    alias: useLocalCavemanVeUi
      ? [
          {
            find: "caveman-ve-ui/styles",
            replacement: path.resolve(__dirname, "../caveman-ve-ui/src/styles/index.scss")
          },
          {
            find: "caveman-ve-ui",
            replacement: path.resolve(__dirname, "../caveman-ve-ui/src/index.ts")
          }
        ]
      : []
  }
})

启动时打开开关，例如：

# Windows cmd
set LOCAL_CAVEMAN_VE_UI=1 && npm run dev

# PowerShell
$env:LOCAL_CAVEMAN_VE_UI=1; npm run dev

# bash
LOCAL_CAVEMAN_VE_UI=1 npm run dev

业务项目仍需 file: 或 registry 安装依赖以便解析 peer，alias 会覆盖主入口与样式子路径。

方式三：只盯 dist（无 HMR 或需手动刷新）

组件库终端执行 npm run build:watch，业务项目正常引用包内 dist；每次保存会重新打包，需在浏览器刷新或依赖打包链是否监听 node_modules（一般不如 alias 顺滑）。

构建

npm install
npm run build

产物在 dist/：index.js / index.cjs、类型声明与 style.css（含 Plyr 与 SFC 抽取样式）。

发布到 npm

前置条件

1. 在 npmjs.com 注册账号；若开启双因素认证，登录时按提示输入一次性密码。
2. 本仓库 package.json 已配置 prepublishOnly，执行 npm publish 时会自动执行 npm run build，无需手动先构建（如需可本地先 npm run build 自检）。

登录与检查包名

在组件库根目录执行：

npm login
npm whoami

检查当前 name（默认 caveman-ve-ui）是否已被占用：

npm view caveman-ve-ui

若返回包信息说明名称已被他人使用，请修改 package.json 中的 name（例如改为作用域包 @你的用户名或组织/caveman-ve-ui）。

首次发布

在仓库根目录：

npm publish

若为 @scope/包名 且需要公开安装（多数团队组件库如此），使用：

npm publish --access public

发布后，业务项目可执行：

npm install caveman-ve-ui

（若使用作用域包，则 npm install @scope/caveman-ve-ui。）

后续升级版本

1. 提交代码并确认构建通过。
2. 提升版本号（任选其一）：

npm version patch   # 0.1.0 → 0.1.1
npm version minor   # 0.1.0 → 0.2.0
npm version major   # 0.1.0 → 1.0.0

npm version 默认会打 git tag；若不用 git，可加 --no-git-tag-version 仅改 package.json。

3. 再次发布：

npm publish
# 作用域公开包：
npm publish --access public

与发包相关的说明

• files 字段当前仅包含 dist，安装方只会下载构建产物；peerDependencies 需在使用方项目中自行安装。
• 若 npm 包主页需要展示本 README，可将 README.md 加入 package.json 的 files 数组。
• 建议补全 license（如 MIT）、repository、keywords，便于合规与检索。
• 使用私有 registry（如公司 Nexus / Verdaccio）时，先执行 npm config set registry <你的registry地址>，再 npm publish；发公共 npm 前请把 registry 设回 https://registry.npmjs.org/。

在 basis-admin-pc 中接入

1. npm install file:../caveman-ve-ui（或发包后从 registry 安装）。
2. 删除或改为从包中导入原 CourseVideo 目录下的组件与 course-video-player store。
3. 确保全局仍只渲染一个 CourseVideoFloatingHost。