@origen-ui/upload

Enterprise file upload for Vue 3 and Element Plus. OgUpload owns validation, queueing, retries, progress, file actions, and value projection; business code owns the transport through an adapter.

Install

pnpm add @origen-ui/upload element-plus

import { OgUpload } from '@origen-ui/upload'
import '@origen-ui/upload/style.css'

For the aggregate package:

import { OgUpload } from 'origen-ui'
import 'origen-ui/upload.css'

Adapter-first upload

<script setup lang="ts">
import type { OgUploadAdapter } from '@origen-ui/upload'
import { OgUpload } from '@origen-ui/upload'
import { ref } from 'vue'

interface UploadResponse {
  url: string
}

const urls = ref<string[]>([])

const adapter: OgUploadAdapter<UploadResponse> = {
  upload: async ({ file, signal, onProgress }) => {
    const result = await uploadToStorage(file, { signal, onProgress })
    return { url: result.url }
  },
  remove: async ({ file, signal }) => {
    await removeFromStorage(file.url!, { signal })
  },
}
</script>

<template>
  <OgUpload
    v-model="urls"
    :adapter="adapter"
    accept="application/pdf,image/png,image/jpeg"
    :max-size="20 * 1024 * 1024"
    :multiple="true"
    :retry="{ maxAttempts: 2, delay: 400, backoff: 2 }"
    value-type="urls"
  />
</template>

The adapter receives the selected File, an AbortSignal, the attempt number, and a progress callback. It can use fetch, Axios, an OSS SDK, pre-signed direct uploads, or a multipart protocol.

valueType selects the outward v-model shape:

• fileList (default): OgUploadFile[], including progress, status, response and metadata.
• url: one uploaded URL.
• urls: uploaded URL list.

If the endpoint follows a conventional XHR workflow, create an adapter with createXhrUploadAdapter(options) and still pass it through adapter. Use resolveResponse to map an arbitrary server response to { url } or other file fields.

Application defaults

Install createOgUpload() once on a Vue app to share the same transport and presentation defaults across its upload controls. The plugin is scoped to that app, so separate Vue applications do not share configuration.

import { createApp } from 'vue'
import { createOgUpload, createXhrUploadAdapter } from '@origen-ui/upload'

const app = createApp(App)
app.use(
  createOgUpload({
    adapter: createXhrUploadAdapter({ action: '/api/files' }),
    locale: { selectFiles: 'Choose files' },
    concurrency: 4,
    retry: { maxAttempts: 2 },
  }),
)

The component prop takes precedence over the app default, and built-in defaults remain the fallback. beforeUpload remains instance-specific because it often contains workflow-specific validation. A global adapter is a default only: pass a local adapter for a different endpoint, tenant, or storage protocol.

Operations and variants

Use variant="drag" or variant="picture-card" for the selection surface. autoUpload defaults to true; set it to false and call submit() through a template ref to coordinate a form submission. The exposed API also provides abort, retry, remove, clearFiles, getFiles, and validate.

The component emits upload-success, remove-success, progress, validation-error, operation-error, change, and update:modelValue.

Use uploadProps for typed Element Plus Upload presentation options that are not owned by OgUpload. OgUpload applies its queue, selected-file, validation, and transport fields last. getNativeUpload() returns the mounted Element Plus Upload instance when a native imperative API is explicitly needed.

公共契约

由 components.v2.json 自动生成。请先修改公开的 TypeScript 契约，然后运行 pnpm component-contracts:sync 同步。

• 标准导入：import { OgUpload, createXhrUploadAdapter } from '@origen-ui/upload'
• 核心 props：adapter, valueType, accept, limit
• 事件：operationError, uploadSuccess
• 暴露的方法：getNativeUpload