From daef38517cca6bac031a67e986e5f359c6f54621 Mon Sep 17 00:00:00 2001
From: AC-0308 <pzzxtyh@qq.com>
Date: Tue, 22 Jul 2025 09:15:27 +0800
Subject: [PATCH] =?UTF-8?q?doc:=20=F0=9F=93=9D=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E4=B8=8A=E4=BC=A0(upload)=E7=9A=84=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../upload/__docs__/__case__/UploadBasic.vue  | 187 ++++++++++++++++++
 .../upload/__docs__/__case__/UploadSlots.vue  |  73 +++++++
 .../upload/__docs__/__case__/uploadUsage.ts   |  95 +++++++++
 .../src/upload/__docs__/index.en-US.md        |  18 ++
 .../src/upload/__docs__/index.zh-CN.md        |  18 ++
 5 files changed, 391 insertions(+)
 create mode 100644 packages/opendesign/src/upload/__docs__/__case__/UploadBasic.vue
 create mode 100644 packages/opendesign/src/upload/__docs__/__case__/UploadSlots.vue
 create mode 100644 packages/opendesign/src/upload/__docs__/__case__/uploadUsage.ts
 create mode 100644 packages/opendesign/src/upload/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/upload/__docs__/index.zh-CN.md

diff --git a/packages/opendesign/src/upload/__docs__/__case__/UploadBasic.vue b/packages/opendesign/src/upload/__docs__/__case__/UploadBasic.vue
new file mode 100644
index 00000000..460c8965
--- /dev/null
+++ b/packages/opendesign/src/upload/__docs__/__case__/UploadBasic.vue
@@ -0,0 +1,187 @@
+<docs lang="md">
+<!--zh-CN-->
+### Upload basic
+
+<!--en-US-->
+### Upload basic
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OUpload, type UploadFileT, OButton } from '@opensig/opendesign';
+import { onAfterSelect, uploadRequest, onBeforeUpload, onBeforeRemove } from '../../__demo__/upload';
+
+const uploadRef = ref<InstanceType<typeof OUpload> | null>(null);
+const doUpload = () => {
+  uploadRef.value?.upload()?.then((res) => {
+    const s = res.filter((item) => item.status === 'finished');
+    const f = res.filter((item) => item.status === 'failed');
+    console.log('Success:', s.map((item) => item.name).join(', '));
+    console.log('Failed', f.map((item) => item.name).join(', '));
+  });
+};
+
+const imgs = [
+  'https://www.openeuler.org/assets/fenhuo_light.8205c177.png',
+  'https://www.openeuler.org/assets/tongYuan.fd26d7bf.png',
+  'https://www.openeuler.org/assets/suse.37147e0c.png',
+];
+
+const defaultFileList: UploadFileT[] = [
+  {
+    id: '1',
+    name: 'test.png',
+    status: 'finished',
+    imgUrl: imgs[0],
+  },
+];
+
+const singleFileList = ref<UploadFileT[]>([
+  {
+    id: '1',
+    name: 'test.png',
+    status: 'finished',
+    imgUrl: imgs[0],
+  },
+]);
+
+const fileList = ref<UploadFileT[]>([
+  {
+    id: '1',
+    name: 'test.png',
+    status: 'finished',
+    imgUrl: imgs[2],
+  },
+  {
+    id: '2',
+    name: 'test2.png',
+    status: 'failed',
+    message: '上传失败',
+  },
+]);
+
+const onProgress = (f: UploadFileT) => {
+  console.log(f.name, f.percent);
+};
+
+const onChange = (f: UploadFileT[]) => {
+  const r = f.map((item) => `${item.name}:${item.status}`);
+  console.log(r.join(', '));
+  console.log('onChange', fileList.value);
+};
+const onSelect = (f: UploadFileT[]) => {
+  const r = f.map((item) => `${item.name}:${item.status}`);
+  console.log(r.join(', '));
+  console.log('onSelect', fileList.value);
+};
+</script>
+<template>
+  <section style="flex-wrap: wrap; align-items: flex-start">
+    <div class="upload-item">
+      <OUpload
+        v-model="singleFileList"
+        :on-after-select="onAfterSelect"
+        :upload-request="uploadRequest"
+        :btn-props="{ size: 'large' }"
+        color="normal"
+        variant="solid"
+        accept=".docx,.xlsx,.xls,.doc,.pdf"
+      />
+    </div>
+    <div class="upload-item">
+      <OUpload
+        multiple
+        btn-label="上传(多选)"
+        accept=".jpg,.png,.svg"
+        v-model="fileList"
+        :on-after-select="onAfterSelect"
+        :upload-request="uploadRequest"
+        :on-before-upload="onBeforeUpload"
+        @select="onSelect"
+        @change="onChange"
+      />
+    </div>
+    <div class="upload-item">
+      <OUpload
+        multiple
+        btn-label="上传(多选)"
+        :on-after-select="onAfterSelect"
+        :upload-request="uploadRequest"
+        :on-before-upload="onBeforeUpload"
+        color="primary"
+      />
+    </div>
+    <div class="upload-item">
+      <OUpload
+        :on-after-select="onAfterSelect"
+        :upload-request="uploadRequest"
+        btn-label="上传(单选)"
+        :default-file-list="defaultFileList"
+        disabled
+        @select="onSelect"
+        @progress="onProgress"
+      />
+    </div>
+    <div class="upload-item">
+      <OUpload multiple :on-after-select="onAfterSelect" :upload-request="uploadRequest" :on-before-upload="onBeforeUpload" color="primary" draggable>
+        <template #select-drag-extra><div>请不要上传个人敏感数据</div></template>
+      </OUpload>
+    </div>
+    <div class="upload-item">
+      <OUpload
+        multiple
+        v-model="fileList"
+        :on-after-select="onAfterSelect"
+        :upload-request="uploadRequest"
+        :on-before-upload="onBeforeUpload"
+        list-type="picture-card"
+      />
+    </div>
+  </section>
+  <section style="flex-wrap: wrap; align-items: flex-start">
+    <div class="upload-item">
+      <p>无进度上传</p>
+      <OUpload
+        multiple
+        btn-label="上传(多选)"
+        :on-after-select="onAfterSelect"
+        :upload-request="(e) => uploadRequest(e, false)"
+        :on-before-upload="onBeforeUpload"
+      />
+    </div>
+
+    <div class="upload-item">
+      <p>无进度上传</p>
+      <OUpload
+        multiple
+        :on-after-select="onAfterSelect"
+        :upload-request="(e) => uploadRequest(e, false)"
+        :on-before-upload="onBeforeUpload"
+        list-type="picture-card"
+      />
+    </div>
+    <div class="upload-item">
+      <p>延迟上传</p>
+      <OButton class="btn" @click="doUpload">开始上传</OButton>
+      <OUpload ref="uploadRef" multiple :upload-request="uploadRequest" lazy-upload btn-label="选择文件" />
+    </div>
+    <div class="upload-item">
+      <p>删除前确认 onBeforeRemove</p>
+      <OUpload multiple :upload-request="uploadRequest" :on-before-upload="onBeforeUpload" :on-before-remove="onBeforeRemove" />
+    </div>
+  </section>
+</template>
+<style lang="scss" scoped>
+p {
+  font-size: 14px;
+  margin: 16px 0 12px;
+  color: var(--o-color-info2);
+}
+.upload-item {
+  width: calc(50% - 16px);
+  flex-shrink: 0;
+}
+.btn {
+  margin-bottom: 8px;
+}
+</style>
diff --git a/packages/opendesign/src/upload/__docs__/__case__/UploadSlots.vue b/packages/opendesign/src/upload/__docs__/__case__/UploadSlots.vue
new file mode 100644
index 00000000..378211b5
--- /dev/null
+++ b/packages/opendesign/src/upload/__docs__/__case__/UploadSlots.vue
@@ -0,0 +1,73 @@
+<docs lang="md">
+<!--zh-CN-->
+### Slots
+
+<!--en-US-->
+### Slots
+</docs>
+
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+import { OUpload, type UploadFileT, OIconCalendar, OButton } from '@opensig/opendesign';
+import { uploadRequest } from '../../__demo__/upload';
+
+const onAfterSelect2 = (fileList: FileList): Promise<UploadFileT[]> => {
+  return Promise.resolve(
+    Array.from(fileList).map((file) => {
+      return {
+        id: file.name,
+        name: file.name,
+        file: file,
+        retry: false,
+        icon: shallowRef(OIconCalendar),
+      };
+    })
+  );
+};
+</script>
+<template>
+  <section>
+    <div class="upload-item">
+      <p>自定义上传区域</p>
+      <OUpload :upload-request="uploadRequest" show-uploading-icon>
+        <div style="width: 200px; height: 100px; background-color: #ccc; display: flex; justify-content: center; align-items: center">这是自定义上传区域</div>
+      </OUpload>
+    </div>
+    <div class="upload-item">
+      <p>自定义上传按钮</p>
+      <OUpload :upload-request="uploadRequest" show-uploading-icon>
+        <OButton color="primary" size="large" variant="solid">这是自定义上传按钮</OButton>
+      </OUpload>
+    </div>
+    <div class="upload-item">
+      <p>上传说明</p>
+      <OUpload :upload-request="uploadRequest" show-uploading-icon>
+        <template #select-extra>这是上传说明</template>
+      </OUpload>
+    </div>
+    <div class="upload-item">
+      <p>通过自定义文件列表文件图标2</p>
+      <OUpload multiple :on-after-select="onAfterSelect2" :upload-request="uploadRequest" show-uploading-icon />
+    </div>
+  </section>
+</template>
+<style lang="scss" scoped>
+p {
+  font-size: 14px;
+  margin: 16px 0 12px;
+  color: var(--o-color-info2);
+}
+.upload-item {
+  width: calc(50% - 16px);
+  flex-shrink: 0;
+}
+.diy-icon {
+  margin-left: 8px;
+}
+.prefix-icon {
+  margin-right: 8px;
+}
+.done {
+  color: green;
+}
+</style>
diff --git a/packages/opendesign/src/upload/__docs__/__case__/uploadUsage.ts b/packages/opendesign/src/upload/__docs__/__case__/uploadUsage.ts
new file mode 100644
index 00000000..ca946bbd
--- /dev/null
+++ b/packages/opendesign/src/upload/__docs__/__case__/uploadUsage.ts
@@ -0,0 +1,95 @@
+import { propsToAttrStr } from '../../../_demo/utils';
+import { onAfterSelect, uploadRequest, onBeforeUpload, onBeforeRemove } from '../../__demo__/upload';
+import {  reactive } from 'vue';
+import type { UploadFileT } from '../../../../lib';
+import { DocDemoSchema, DocDemoTemplate } from '../../../_demo/types.ts';
+
+// 该导出会作为该使用示例的文案，文案是markdown格式
+export const docs = {
+  'zh-CN':
+    '用于上传文件到服务端。可设置项包含：  \n' +
+    '- MIME类型`accept`  \n' +
+    '- 是否禁用`disabled`  \n' +
+    '- 是否支持多选`multiple`  \n' +
+    '- 上传触发时机`lazyUpload`  \n' +
+    '- 拖拽上传`draggable`  \n' +
+    '- 文件列表类型`listType`  \n' +
+    '- 按钮文本`btnLabel`等',
+  'en-US':
+    'Virtual scrolling is used to control the number of rendered items in a list to optimize rendering performance.Configurable options include:  \n' +
+    '- list: the list data to render  \n' +
+    '- defaultStartIndex: sets the default initial scroll position item  \n' +
+    '- itemSize: defines the height of each item  \n' +
+    '- defaultItemSize: specifies the default item height for variable-height items  \n' +
+    '- buffer: sets front/render buffer padding  \n' +
+    '- scrollbar: controls scrollbar behavior',
+};
+
+const imgs = [
+  'https://www.openeuler.org/assets/fenhuo_light.8205c177.png',
+  'https://www.openeuler.org/assets/tongYuan.fd26d7bf.png',
+  'https://www.openeuler.org/assets/suse.37147e0c.png',
+];
+
+export const ctx = {
+  onAfterSelect, uploadRequest, onBeforeUpload, onBeforeRemove,
+  singleFileList: reactive<UploadFileT[]>([
+    {
+      id: '1',
+      name: 'test.png',
+      status: 'finished',
+      imgUrl: imgs[0],
+    },
+  ])
+};
+
+export const schema = {
+  accept: {
+    type: 'string',
+    default: 'image/jpeg,image/jpg,image/png,image/gif,video/mp4'
+  },
+  disabled: {
+    type: 'boolean',
+    default: false
+  },
+  multiple: {
+    type: 'boolean',
+    default: false,
+  },
+  btnLabel: {
+    type: 'string',
+    default: 'upload'
+  },
+  lazyUpload: {
+    type: 'boolean',
+    default: false
+  },
+  draggable: {
+    type: 'boolean',
+    default: true
+  },
+  dragLabel: {
+    type: 'string',
+    default: 'drag to upload'
+  },
+  dragHoverLabel: {
+    type: 'string',
+    default: 'put the file here'
+  },
+  listType: {
+    type: 'list',
+    list: ['text', 'picture', 'picture-card'] as const
+  }
+} satisfies Record<string, DocDemoSchema>;
+
+export const template: DocDemoTemplate<typeof schema> = (_props) => {
+  return `<OUpload
+  v-model="ctx.singleFileList"
+  ${propsToAttrStr(_props)}
+  :on-after-select="ctx.onAfterSelect"
+  :upload-request="ctx.uploadRequest"
+  :btn-props="{ size: 'large' }"
+  color="normal"
+  variant="solid"
+/>`;
+};
diff --git a/packages/opendesign/src/upload/__docs__/index.en-US.md b/packages/opendesign/src/upload/__docs__/index.en-US.md
new file mode 100644
index 00000000..da3e197e
--- /dev/null
+++ b/packages/opendesign/src/upload/__docs__/index.en-US.md
@@ -0,0 +1,18 @@
+---
+sidebar: OUpload
+---
+
+# Upload
+
+## Usage
+
+<!-- @usage uploadUsage -->
+
+## Cases
+
+<!-- @case UploadBasic -->
+<!-- @case UploadSlots -->
+
+## Api
+
+<!-- @api OUploadList -->
\ No newline at end of file
diff --git a/packages/opendesign/src/upload/__docs__/index.zh-CN.md b/packages/opendesign/src/upload/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..c6e26970
--- /dev/null
+++ b/packages/opendesign/src/upload/__docs__/index.zh-CN.md
@@ -0,0 +1,18 @@
+---
+sidebar: OUpload 上传
+---
+
+# 上传
+
+## 使用
+
+<!-- @usage uploadUsage -->
+
+## 示例
+
+<!-- @case UploadBasic -->
+<!-- @case UploadSlots -->
+
+## Api
+
+<!-- @api OUpload -->
\ No newline at end of file
-- 
Gitee