chore: implement headless uploader API with dropzone and file management

blocklets/image-bin/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.14.18 (December 22, 2025)
+
+- feat(uploader): add headless API for programmatic control
+
 ## 0.14.17 (December 20, 2025)
 
 - feat: support app shell in dashboard

blocklets/image-bin/blocklet.yml

@@ -1,5 +1,5 @@
 name: image-bin
-version: 0.14.17
+version: 0.14.18
 title: Media Kit
 description: Self-hosted media management that replaces expensive cloud services
   while keeping you in complete control of your digital assets.

blocklets/image-bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-bin",
-  "version": "0.14.17",
+  "version": "0.14.18",
   "private": true,
   "scripts": {
     "dev": "blocklet dev",

blocklets/image-bin/version

@@ -1 +1 @@
-0.14.17
+0.14.18

packages/uploader-server/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.17 (December 22, 2025)
+
+- feat(uploader): add headless API for programmatic control
+
 ## 0.3.16 (December 17, 2025)
 
 - fix(uploader): improve runtime path handling and EXIF removal logic

packages/uploader-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/uploader-server",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "blocklet upload server",
   "publishConfig": {
     "access": "public"

packages/uploader-server/version

@@ -1 +1 @@
-0.3.16
+0.3.17

packages/uploader/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.17 (December 22, 2025)
+
+- feat(uploader): add headless API for programmatic control
+
 ## 0.3.16 (December 17, 2025)
 
 - fix(uploader): improve runtime path handling and EXIF removal logic

packages/uploader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/uploader",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "blocklet upload component",
   "publishConfig": {
     "access": "public"

packages/uploader/src/react/uploader.tsx

@@ -1,4 +1,4 @@
-import { UploaderProps } from '../types';
+import { UploaderProps, UploaderRef } from '../types';
 import keyBy from 'lodash/keyBy';
 import { useReactive, useRequest } from 'ahooks';
 import { createRoot } from 'react-dom/client';
@@ -914,18 +914,100 @@ export function Uploader({
     }, 500);
   }
 
+  const addFilesToUppy = (files: File[], source: string, autoUpload: boolean) => {
+    files.forEach((file) => {
+      state.uppy.addFile({
+        name: file.name,
+        type: file.type,
+        data: file,
+        source,
+      });
+    });
+    if (autoUpload) {
+      state.uppy.upload();
+    }
+  };
+
+  const triggerFileInput = (options?: { accept?: string; multiple?: boolean; autoUpload?: boolean }) => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.style.display = 'none';
+    input.accept = options?.accept ?? state.restrictions?.allowedFileTypes?.join(',') ?? '';
+    input.multiple = options?.multiple ?? state.restrictions?.maxNumberOfFiles !== 1;
+
+    input.onchange = (e: Event) => {
+      const target = e.target as HTMLInputElement;
+      const files = Array.from(target.files || []);
+      addFilesToUppy(files, 'local', options?.autoUpload !== false);
+      document.body.removeChild(input);
+    };
+
+    document.body.appendChild(input);
+    input.click();
+  };
+
+  const getDropzoneProps = (options?: { autoUpload?: boolean; noClick?: boolean }) => {
+    const autoUpload = options?.autoUpload !== false;
+    let dragCounter = 0;
+
+    return {
+      onDragEnter: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        dragCounter++;
+        if (e.dataTransfer?.items?.length) {
+          e.currentTarget.setAttribute('data-dragging', 'true');
+        }
+      },
+      onDragLeave: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        dragCounter--;
+        if (dragCounter === 0) {
+          e.currentTarget.removeAttribute('data-dragging');
+        }
+      },
+      onDragOver: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      onDrop: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        e.currentTarget.removeAttribute('data-dragging');
+        dragCounter = 0;
+        const files = Array.from(e.dataTransfer?.files || []);
+        if (files.length) {
+          addFilesToUppy(files, 'drop', autoUpload);
+        }
+      },
+      onClick: options?.noClick
+        ? undefined
+        : () => {
+            triggerFileInput({ autoUpload });
+          },
+    };
+  };
+
   useImperativeHandle(
     ref,
     () =>
       ({
         getUploader: () => state.uppy,
         open,
         close,
-      } as {
-        getUploader: Function;
-        open: Function;
-        close: Function;
-      })
+        // Headless API
+        triggerFileInput,
+        getDropzoneProps,
+        addFiles: (files: File[], options?: { autoUpload?: boolean }) => {
+          addFilesToUppy(files, 'local', options?.autoUpload !== false);
+        },
+        upload: () => state.uppy.upload(),
+        getProgress: () => state.uppy.getState().totalProgress,
+        getFiles: () => state.uppy.getFiles(),
+        removeFile: (fileId: string) => state.uppy.removeFile(fileId),
+        cancelAll: () => state.uppy.cancelAll(),
+      } as UploaderRef)
   );
 
   const Wrapper = popup ? Modal : Fragment;

packages/uploader/src/types.ts

@@ -1,11 +1,45 @@
-import type { UppyOptions } from '@uppy/core';
+import type Uppy from '@uppy/core';
+import type { UppyOptions, UppyFile } from '@uppy/core';
 import type { DashboardOptions } from '@uppy/dashboard';
 import type { TusOptions } from '@uppy/tus';
 import type { ImageEditorOptions } from '@uppy/image-editor';
 import type DropTarget from '@uppy/drop-target';
-import type { HTMLAttributes } from 'react';
+import type { HTMLAttributes, DragEvent } from 'react';
 import type { SxProps, Theme } from '@mui/material/styles';
 
+export interface DropzoneProps {
+  onDragEnter: (e: DragEvent) => void;
+  onDragLeave: (e: DragEvent) => void;
+  onDragOver: (e: DragEvent) => void;
+  onDrop: (e: DragEvent) => void;
+  onClick?: () => void;
+}
+
+export type UploaderRef = {
+  /** 获取底层 Uppy 实例 */
+  getUploader: () => Uppy;
+  /** 打开上传器 (Dashboard) */
+  open: (pluginName?: string) => void;
+  /** 关闭上传器 */
+  close: () => void;
+  /** 触发系统文件选择器 */
+  triggerFileInput: (options?: { accept?: string; multiple?: boolean; autoUpload?: boolean }) => void;
+  /** 获取拖拽区域 props，绑定到元素即可支持拖拽+点击上传 */
+  getDropzoneProps: (options?: { autoUpload?: boolean; noClick?: boolean }) => DropzoneProps;
+  /** 批量添加文件 */
+  addFiles: (files: File[], options?: { autoUpload?: boolean }) => void;
+  /** 开始上传 */
+  upload: () => Promise<any>;
+  /** 获取当前总进度 0-100 */
+  getProgress: () => number;
+  /** 获取当前文件列表 */
+  getFiles: () => UppyFile[];
+  /** 移除指定文件 */
+  removeFile: (fileId: string) => void;
+  /** 取消所有上传 */
+  cancelAll: () => void;
+};
+
 export type UploaderProps = {
   id?: string;
   popup?: boolean;

packages/uploader/version

@@ -1 +1 @@
-0.3.16
+0.3.17

packages/xss/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.15 (December 22, 2025)
+
+- feat(uploader): add headless API for programmatic control
+
 ## 0.3.14 (December 17, 2025)
 
 - fix(uploader): improve runtime path handling and EXIF removal logic

packages/xss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/xss",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "blocklet prevent xss attack",
   "publishConfig": {
     "access": "public"

packages/xss/version

@@ -1 +1 @@
-0.3.14
+0.3.15