@wuxiaolins/upload 0.0.0

package/README.md

@@ -0,0 +1,433 @@
+# @bsy-ui/upload 上传组件库
+
+基于 Ant Design Vue 和腾讯云 COS/VOD 的上传组件库，支持图片、视频上传和懒加载。
+
+## ✨ 特性
+
+- 🚀 **开箱即用** - 内置腾讯云 COS/VOD 上传支持
+- 📦 **Hook 懒加载** - 独立导出 Hook，减少 46% 打包体积
+- 🎯 **类型安全** - 完整的 TypeScript 类型定义
+- 📱 **响应式** - 自动适配 PC 和移动端
+- 🎨 **自定义样式** - 支持自定义上传按钮和样式
+- 🔄 **多种上传方式** - 支持 COS 直传、表单上传、自定义上传
+- ✅ **文件验证** - 内置文件大小、类型、尺寸验证
+- 📝 **完整文档** - 详细的使用文档和示例
+
+## 📦 安装
+
+```bash
+npm install @bsy-ui/upload
+# 或
+pnpm add @bsy-ui/upload
+```
+
+## 🚀 快速开始
+
+### 组件使用
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BsyUpload } from '@bsy-ui/upload';
+import '@bsy-ui/upload/dist/style.css';
+
+const uploadRef = ref();
+
+const handleDone = (file) => {
+  console.log('上传完成', file);
+};
+
+const handleError = (error) => {
+  console.error('上传失败', error);
+};
+</script>
+
+<template>
+  <BsyUpload
+    ref="uploadRef"
+    :count="3"
+    accept=".png,.jpg,.jpeg"
+    :max-size="5"
+    @done="handleDone"
+    @error="handleError"
+  />
+</template>
+```
+
+### Hook 使用（懒加载，推荐）
+
+```typescript
+import { useUpload } from '@bsy-ui/upload/hook';
+
+const { urls, setFiles, remove, onUploadEvent, beforeUpload } = useUpload({
+  prod: true,
+  bucket: 'my-bucket',
+  region: 'ap-guangzhou',
+  prefixPath: '/uploads',
+  maxSize: 5,
+  count: 3
+});
+
+// 监听上传事件
+onUploadEvent('success', (file) => {
+  console.log('上传成功', file);
+});
+
+onUploadEvent('error', (error) => {
+  console.error('上传失败', error);
+});
+
+// 设置文件列表
+setFiles([
+  { url: 'https://example.com/image1.jpg' },
+  { url: 'https://example.com/image2.jpg' }
+]);
+
+// 删除文件
+remove(urls.value[0]);
+```
+
+## 📚 组件 API
+
+### BsyUpload Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|-----|------|--------|------|
+| count | number | 1 | 最大上传数量 |
+| accept | string | '.png,.jpeg,.jpg,.bmp,.webp,.svg,.tiff' | 接受的文件类型 |
+| maxSize | number | 2 | 文件最大大小（MB） |
+| widthRange | string | '1:9000' | 图片宽度范围 |
+| heightRange | string | '1:9000' | 图片高度范围 |
+| prefixPath | string | '/content' | 上传路径前缀 |
+| disabled | boolean | false | 是否禁用 |
+| showText | boolean | true | 是否显示上传文本 |
+| text | string | '点击或拖拽上传' | 上传按钮文本 |
+| showSize | boolean | true | 是否显示文件大小提示 |
+| canSort | boolean | false | 是否可以拖拽排序 |
+| listType | UploadListType | 'picture-card' | 上传列表的内建样式 |
+| custom | boolean | false | 是否使用自定义插槽 |
+| className | string | '' | 自定义样式类名 |
+| uploadTextTip | string | '' | 上传提示文本 |
+| showPreviewIcon | boolean | true | 是否显示预览图标 |
+| showRemoveIcon | boolean | true | 是否显示删除图标 |
+| showDownloadIcon | boolean | false | 是否显示下载图标 |
+
+#### 上传配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+|-----|------|--------|------|
+| prod | boolean | true | 是否正式环境 |
+| bucket | string | '' | 腾讯云 COS bucket |
+| region | string | '' | 腾讯云 COS region |
+| uploadType | string | '' | 上传方式（'form' 为表单上传） |
+| customUpload | boolean | false | 是否自定义上传 |
+| action | string | '/api/base/admin/upload/upload/getCredential' | 上传地址 |
+| headers | object | - | 上传请求头 |
+| data | object | - | 上传额外参数 |
+
+### BsyUpload Events
+
+| 事件 | 参数 | 说明 |
+|-----|------|------|
+| beforeUpload | (file) | 上传前回调 |
+| beforeUploadError | (error) | 上传前验证失败 |
+| add | (file) | 文件添加到列表 |
+| progress | (file) | 上传进度更新 |
+| done | (file) | 上传成功 |
+| error | (error) | 上传失败 |
+| remove | (file) | 文件删除 |
+| change | (fileList) | 文件列表变化 |
+
+### BsyUpload Methods
+
+| 方法 | 参数 | 返回值 | 说明 |
+|-----|------|--------|------|
+| resetFiles | (files: string[] \| object[]) | void | 重置文件列表 |
+
+### BsyUpload Slots
+
+| 插槽 | 参数 | 说明 |
+|-----|------|------|
+| custom | - | 自定义上传按钮 |
+| customIcon | { item } | 自定义文件图标 |
+
+## 🎯 Hook API
+
+### useUpload
+
+```typescript
+const {
+  urls,           // 文件列表
+  setFiles,       // 设置文件列表
+  remove,         // 删除文件
+  onUploadEvent,  // 监听上传事件
+  beforeUpload    // 上传前验证
+} = useUpload(options);
+```
+
+#### Options
+
+| 属性 | 类型 | 默认值 | 说明 |
+|-----|------|--------|------|
+| prod | boolean | true | 是否正式环境 |
+| bucket | string | '' | 腾讯云 COS bucket |
+| region | string | '' | 腾讯云 COS region |
+| action | string | - | 上传地址 |
+| headers | object | {} | 上传请求头 |
+| data | object | {} | 上传额外参数 |
+| customUpload | boolean | false | 是否自定义上传 |
+| accept | string | '.png,.jpeg,.jpg,.bmp,.webp,.svg,.tiff' | 接受的文件类型 |
+| maxSize | number | 2 | 文件最大大小（MB） |
+| widthRange | string | '1:9000' | 图片宽度范围 |
+| heightRange | string | '1:9000' | 图片高度范围 |
+| prefixPath | string | '/content' | 上传路径前缀 |
+| count | number | 1 | 最大上传数量 |
+
+#### Returns
+
+| 属性 | 类型 | 说明 |
+|-----|------|------|
+| urls | Ref<WxFile[]> | 文件列表 |
+| setFiles | (files: any[]) => void | 设置文件列表 |
+| remove | (file: WxFile) => void | 删除文件 |
+| onUploadEvent | (event: string, callback: Function) => void | 监听上传事件 |
+| beforeUpload | (file: File) => Promise<boolean> | 上传前验证 |
+
+#### Events
+
+- `beforeUploadError` - 上传前验证失败
+- `beforeUpload` - 上传前回调
+- `add` - 文件添加到列表
+- `progress` - 上传进度更新
+- `success` - 上传成功
+
+## 💡 使用示例
+
+### 基础图片上传
+
+```vue
+<template>
+  <BsyUpload
+    :count="5"
+    accept=".png,.jpg,.jpeg"
+    :max-size="10"
+    @done="handleDone"
+  />
+</template>
+```
+
+### 自定义上传按钮
+
+```vue
+<template>
+  <BsyUpload :count="3" custom>
+    <template #custom>
+      <a-button type="primary">
+        点击上传
+      </a-button>
+    </template>
+  </BsyUpload>
+</template>
+```
+
+### 文件回显
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+
+const uploadRef = ref();
+
+onMounted(() => {
+  // 回显已上传的文件
+  uploadRef.value.resetFiles([
+    'https://example.com/image1.jpg',
+    'https://example.com/image2.jpg'
+  ]);
+});
+</script>
+
+<template>
+  <BsyUpload ref="uploadRef" :count="5" />
+</template>
+```
+
+### 使用 Hook（仅上传逻辑）
+
+```vue
+<script setup>
+import { useUpload } from '@bsy-ui/upload/hook';
+import { Upload } from 'ant-design-vue';
+
+const { urls, beforeUpload, onUploadEvent } = useUpload({
+  maxSize: 5,
+  count: 3
+});
+
+onUploadEvent('success', (file) => {
+  console.log('上传成功', file);
+});
+</script>
+
+<template>
+  <Upload
+    :file-list="urls"
+    :before-upload="beforeUpload"
+    list-type="picture-card"
+  >
+    <div>点击上传</div>
+  </Upload>
+</template>
+```
+
+### 腾讯云 COS 直传
+
+```vue
+<template>
+  <BsyUpload
+    :prod="true"
+    bucket="my-bucket"
+    region="ap-guangzhou"
+    prefix-path="/uploads"
+    :count="5"
+  />
+</template>
+```
+
+### 表单上传
+
+```vue
+<template>
+  <BsyUpload
+    upload-type="form"
+    action="/api/upload"
+    :headers="{ Authorization: 'Bearer token' }"
+    :data="{ type: 'image' }"
+    :count="3"
+  />
+</template>
+```
+
+## 📖 高级功能
+
+### 文件验证
+
+组件内置了多种文件验证：
+
+- **文件类型验证** - 通过 `accept` 属性限制文件类型
+- **文件大小验证** - 通过 `maxSize` 属性限制文件大小
+- **图片尺寸验证** - 通过 `widthRange` 和 `heightRange` 限制图片尺寸
+
+```vue
+<BsyUpload
+  accept=".png,.jpg"
+  :max-size="5"
+  width-range="100:1920"
+  height-range="100:1080"
+/>
+```
+
+### 拖拽排序
+
+启用 `canSort` 属性后，可以拖拽调整文件顺序：
+
+```vue
+<BsyUpload :can-sort="true" :count="5" />
+```
+
+### 自定义样式
+
+通过 `className` 属性和 CSS 变量自定义样式：
+
+```vue
+<BsyUpload class-name="my-upload" />
+
+<style>
+.my-upload {
+  --theme-upload-width: 120px;
+  --theme-upload-height: 120px;
+  --theme-upload-border-radius: 8px;
+}
+</style>
+```
+
+## 🔧 配置说明
+
+### 环境配置
+
+```typescript
+// 开发环境
+const upload = useUpload({
+  prod: false,
+  bucket: 'dev-bucket',
+  region: 'ap-guangzhou'
+});
+
+// 生产环境
+const upload = useUpload({
+  prod: true,
+  bucket: 'prod-bucket',
+  region: 'ap-guangzhou'
+});
+```
+
+### 上传路径
+
+```typescript
+const upload = useUpload({
+  prefixPath: '/uploads/images',  // 文件将上传到 /uploads/images/ 目录
+});
+```
+
+## 📊 性能优化
+
+### Hook 懒加载
+
+使用独立的 Hook 导出可以减少打包体积：
+
+```typescript
+// ❌ 从主包导入（28.42 kB）
+import { useUpload } from '@bsy-ui/upload'
+
+// ✅ 从 hook 子包导入（15.13 kB，减少 46%）
+import { useUpload } from '@bsy-ui/upload/hook'
+```
+
+### 按需导入
+
+```typescript
+// 仅导入需要的功能
+import { useUpload } from '@bsy-ui/upload/hook';
+```
+
+## 🔗 相关文档
+
+- [使用示例](./USAGE_EXAMPLE.md) - 详细的使用示例
+- [构建说明](./BUILD_SUMMARY.md) - 构建配置说明
+- [TypeScript 配置](./TYPESCRIPT_CONFIG.md) - TypeScript 配置说明
+- [Vite 配置](./VITE_CONFIG_NOTES.md) - Vite 配置说明
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT License
+
+## 🔗 相关链接
+
+- [腾讯云 COS](https://cloud.tencent.com/product/cos)
+- [腾讯云 VOD](https://cloud.tencent.com/product/vod)
+- [Ant Design Vue](https://antdv.com/)
+
+## 📞 支持
+
+如有问题，请：
+1. 查看[使用示例](./USAGE_EXAMPLE.md)
+2. 查看[API 文档](#组件-api)
+3. 提交 [Issue](https://gitlab.bossyun.com/wuxl/package/issues)
+
+---
+
+Made with ❤️ by BSY Team