@fengzhongwen/kukan-ui 1.0.16 → 1.0.18

package/README.md

@@ -1,50 +1,287 @@
-# KukanUI
 
-## 简介
+# Kukan UI 组件库 使用与开发说明
 
-KukanUI 是酷看前端团队开发的 UI 组件库。
+> 本文档面向此仓库（组件目录位于 `src/components`）的使用者与二次开发者，包含：安装/引入、核心组件说明（以 `FileUpload` 为例）、如何开发新组件、按需导出/发布、调试与常见问题等。
 
-## 当前版本
+---
 
-初始版本（v1.0.0）仅支持**上传组件**。
+**目录**
+- **项目概览**：介绍整体结构与插件安装点
+- **安装与引入**：如何在项目中使用（全量注册与按需）
+- **组件清单**：仓库中已有的主要组件
+- **组件详解 — `KukanUpload`（FileUpload）**：Props、事件、插槽、示例
+- **API 配置**：`apiObj` 结构与 `api.js` 映射说明
+- **开发新组件**：文件组织、命名/导出规则、样式与依赖
+- **调试、构建与发布**：常用命令与建议
+- **常见问题**
 
-## 环境要求
+---
 
-- Vue 2.x
-- Element-ui
-- Axios
+**项目概览**
 
-## 安装
+- 源码入口：`src/index.js`。该文件提供 `install` 函数用于全局注册组件，并且会通过 `setAxiosInstance` 将外部传入的 axios 实例注入到 `FileUpload` 的 `api` 模块中。
+- 组件位于 `src/components`。当前包含（但不限于）：
+	- `FileUpload/`（上传组件）
+	- `VideoPreviewDialog/`（视频预览弹窗）
+	- 未来可能有 `Button/` 等组件目录
 
-```bash
-npm install @fengzhongwen/kukan-ui
-```
+示例：`src/index.js` 通过组件 `name` 字段自动注册组件；若要按需引用，也可在 `src/index.js` 中导出对应组件（见文件末尾的 `export { Upload }`）。
 
-## 使用
+---
 
-### 基本配置
+**安装与引入**
 
-使用 `Vue.use()` 注册组件库时，需要传入 axios 实例：
+1. 作为插件全局注册（推荐）
 
 ```javascript
+// main.js
 import Vue from 'vue'
-import KukanUI from 'kukanui'
+import KukanUI from './path/to/your/lib/src/index.js'
 import axios from 'axios'
 
-Vue.use(KukanUI, {
-    axios: axios
-})
+Vue.use(KukanUI, { axios })
+
+new Vue({ ... }).$mount('#app')
 ```
 
-### 上传组件
+说明：`Vue.use(KukanUI, { axios })` 会把 `axios` 实例传给 `src/components/FileUpload/api.js` 的 `setAxiosInstance`，以便组件内的网络请求使用外部统一配置的 axios（例如带 token 的拦截器）。
+
+2. 按需引入
+
+在 `src/index.js` 中把需要导出的组件加入 `export { ... }`，然后在页面中按需 import 使用：
+
+```javascript
+import { Upload } from 'kukan-ui'
+// 或者
+import Upload from 'kukan-ui/src/components/FileUpload/index.vue'
+```
+
+---
+
+**组件清单（当前）**
+
+- `KukanUpload`（文件上传组件，目录：`src/components/FileUpload`） — 功能最完整，支持拖拽、多文件、分片上传队列控制、上传回调、校验等。
+- `VideoPreviewDialog`（目录：`src/components/VideoPreviewDialog`）— 视频预览弹窗组件。
+
+（若新增组件，请在 `src/index.js` 的 `components` 数组中加入组件并在 `export` 区段导出以支持按需引入。）
+
+---
+
+**组件详解 — `KukanUpload`（`src/components/FileUpload`）**
+
+概述：此组件名为 `KukanUpload`，在 `src/index.js` 中被注册为 `Upload`（导出名为 `Upload`，组件 `name` 为 `KukanUpload`），用于文件（视频/图片/文本/字幕等）上传，内置分块与队列控制逻辑。
+
+主要 Props：
+
+- `addDataBaseLinkConfig` (Object, default: {...}) — 与后台建立文件/数据库关联的配置：
+	- `addDataBaseLink` (Boolean) 是否在上传后创建数据库链接
+	- `addFileType` (String) 可选：`video`/`txt`/`pictrue`/`audio`/`subTitle`，用于限制文件类型
+	- `addProgramVersion` (Number) 节目版本号
+- `autoUpload` (Boolean, default: true) — 选择完文件是否自动上传
+- `multiple` (Boolean) — 是否允许多选
+- `startButtonText` (String) — 上传区域显示的提示文字
+- `showSuccessPicture` (Boolean, default: true) — 单选上传成功后是否展示图片
+- `model` (String, default: 'small') — 上传区域 UI 风格（`small`/`mini`/`info`）
+- `showIconTip` (Boolean) — 是否显示上传图标
+- `noneBoder` (Boolean) — 不显示上传区域边框
+- `apiObj` (Object) — 自定义接口地址映射（详见下文“API 配置”）
+
+事件（组件会 $emit 的事件）：
+
+- `removeFile` — 文件被删除时，返回被删除文件的数组
+- `informTableOfRefresh` — 上传完毕后触发，建议父组件刷新数据表格
+- `handelResult` — 上传结果回调（整个结果数组）
+- `getUUID` — 上传成功后返回 UUID 列表
+- `uploadStart` — 上传开始
+- `otherFilterFiles` — 在上传开始后触发，用于父组件按需筛选文件；接收 `(needUploadFilesArr, done)`，监听方应在合适时机调用 `done(filterFiles)` 来决议
+
+插槽：
+
+- 命名插槽 `tips` 可用于替换或补充上传区域的提示内容
+
+重要方法（对外可触发的交互，组件内部实现，以使用顺序排序）：
+
+- `reviewUploadMultipleFiles()` — 按钮触发选取文件（当 `autoUpload` 为 false 时可通过按钮调用）
+- `startUploadMultipleFiles()` — 按钮触发开始批量上传（当 `autoUpload` 为 false 时可通过按钮调用）
+- `uploadFilesConfig_AndStart()` — 上传的入口函数
+- `uploadSingleFile()` — 单个文件上传
+- `createConcurrentController()` — 生成并发控制器
+
+
+使用示例：
 
 ```vue
 <template>
-    <kukan-upload />
+	<div>
+		<Upload
+			:apiObj="apiObj"
+			:autoUpload="false"
+			:multiple="true"
+			:startButtonText="'点击或拖拽上传'"
+			:addDataBaseLinkConfig="{ addDataBaseLink: true, addFileType: 'video', addProgramVersion: 1 }"
+			@handelResult="onUploadResult"
+			@getUUID="onGetUUID"
+			@otherFilterFiles="onOtherFilterFiles"
+		>
+			<template #tips>
+				<div class="my-custom-tip">支持拖拽或点击上传</div>
+			</template>
+		</Upload>
+	</div>
 </template>
+
+<script>
+export default {
+	data() {
+		return {
+			apiObj: {
+				checkfileStatusUrl: '/zt-api/resources/check',
+				filesAllUoloadedUrl: '/zt-api/resources/chunk/merge',
+				searchFileIsUploadedUrl: '/zt-api/resources/check',
+				searchChunkIsUploadedUrl: '/zt-api/resources/check/chunk',
+				uploadFileChunkUrl: '/zt-api/resources/chunk/upload',
+				addNewFileOfVideoUrl: '/api/v1/program/create-video',
+				// ... 根据后端实际接口补全
+			}
+		}
+	},
+	methods: {
+		onUploadResult(result) { console.log('上传结果', result) },
+		onGetUUID(arr) { console.log('uuid 列表', arr) },
+		onOtherFilterFiles(arr, done) {
+			// 举例：只上传文件名包含特定关键字的文件
+			const filtered = arr.filter(f => f.name.includes('期望关键字'))
+			done(filtered)
+		}
+	}
+}
+</script>
+```
+
+---
+
+**API 配置（`apiObj` / `src/components/FileUpload/api.js`）**
+
+`api.js` 提供 `mapApiToRequest(apiObj)` 的映射，期望接收一个形如：
+
+```javascript
+{
+	checkfileStatusUrl: '/zt-api/resources/check',
+	filesAllUoloadedUrl: '/zt-api/resources/chunk/merge',
+	searchFileIsUploadedUrl: '/zt-api/resources/check',
+	searchChunkIsUploadedUrl: '/zt-api/resources/check/chunk',
+	uploadFileChunkUrl: '/zt-api/resources/chunk/upload',
+	addNewFileOfTxtUrl: '/api/v1/program/create-doc',
+	addNewFileOfVideoUrl: '/api/v1/program/create-video',
+	addNewFileOfAudioUrl: '/api/v1/program/create-audio',
+	addNewFileOfPicUrl: '/api/v1/program/create-pic',
+	addNewFileOfSubTitleUrl: '/api/v1/program/create-srt'
+}
 ```
 
-## 后续规划
+内部行为：
+- `setAxiosInstance(axios)` 会把 `axios` 赋值给模块内的 `request`，后续所有接口调用都会使用该实例（因此建议在 `Vue.use(lib, { axios })` 时传入配置过的 axios）。
+- `uploadFileChunk` 在内部会封装成 `FormData`，并以 `multipart/form-data` 提交（带 10 分钟超时）。
+
+---
+
+**如何开发新组件（详细步骤）**
+
+1. 新建目录和文件
+
+- 在 `src/components/` 下创建新目录，例如 `MyWidget`。文件最少包括： `index.vue`（组件实现），如需分发可增加 `index.js` 暴露（方便按需引入）。
+
+2. 组件实现规范
+
+- 在 `index.vue` 的 `export default` 中定义 `name` 字段（例如 `name: 'MyWidget'`），`src/index.js` 会根据 `name` 来注册组件。
+- 遵循现有样式：尽量使用现有的 UI 依赖（当前仓库使用 Element UI 组件），命名 CSS 类带组件前缀以避免冲突。
+- Props/Events 明确注释，并提供合理的默认值与类型校验。
+
+3. 将组件加入全局注册/导出
+
+- 编辑 `src/index.js`：把组件 import 后放入 `components` 数组，以便 `install` 时自动注册；同时在 `export { ... }` 区域中添加导出，支持按需引入。
+
+示例：
+
+```javascript
+import MyWidget from './components/MyWidget'
+const components = [ Upload, DialogVideoReview, MyWidget ]
+export { Upload, DialogVideoReview, MyWidget }
+```
+
+4. 网络请求与 axios
+
+- 若组件需要发起 HTTP 请求，请使用 `api` 模块（或按现有 `api.js` 风格接入），并避免在组件内部直接创建 axios 实例。通过 `Vue.use(lib, { axios })` 注入 `axios`，统一处理 token/拦截器。
+
+5. 本地调试
+
+- 在本地工程中引入组件，使用 `npm run serve`（或项目中相应的 dev 命令）调试样式与交互。
+
+6. 测试与质量
+
+- 为组件添加单元测试（若仓库使用 jest 或其他测试框架）。
+- 保持代码风格一致（lint）、并在 PR 中提供使用示例。
+
+---
+
+**调试、构建与发布（建议）**
+
+- 本地安装依赖：
+
+```bash
+npm install
+```
+
+- 暂不支持。本地调试（视项目脚本而定）
+
+```bash
+npm run serve
+```
+
+- 构建发布（视项目配置而定，若用 rollup/webpack 打包库）
+
+```bash
+npm run build
+```
+
+- 更新版本
+
+```bash
+npm version patch
+```
+
+- 发布版本（需要登录）
+
+```bash
+npm publish --access publish
+```
+
+注意：仓库中并未显式包含打包脚本文件（请检查 `package.json` 的 `scripts` 字段并按需补充）。
+
+---
+
+**按需引入与发布注意事项**
+
+- 若希望支持按需引入（tree-shaking），请确保 `src/index.js` 中对外导出的组件是命名导出；并在打包时生成 `module` / `main` 指向的构建产物。
+- 发布到 npm 前，确保：构建产物已生成、`package.json` 中的 `main` / `module` 指向正确、README 与类型声明（如有）同步更新。
+
+---
+
+**常见问题（FAQ）**
+
+- Q: 如何替换 axios？
+	- A: 在 `main.js` 中通过 `Vue.use(KukanUI, { axios })` 传入你配置过的 axios 实例。
+- Q: 如何自定义上传接口？
+	- A: 将 `apiObj` 传入 `Upload` 组件，键名请参考 `src/components/FileUpload/api.js` 中的 `mapApiToRequest`。
+- Q: 上传取消/重试如何处理？
+	- A: 组件内置 `cancelFileUpload` 与 `resetFileUpload` 等方法，并通过回调与状态触发提示，父组件可监听 `handelResult` 与 `getUUID` 获取结果。
+
+---
+
+**贡献与联系方式**
+
+欢迎提交 PR 或 issue。请在 PR 中包含示例页面、复现步骤与必要的测试。
+
+---
 
-- 优化使用体验
-- 扩展更多组件
+（文档结束）