Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(sheets-drawing-ui): add batch save images functionality with customizable file naming options (#6252)

WEI ZHANG2fce94959336
diff --git a/packages/sheets-drawing-ui/src/facade/f-range.ts b/packages/sheets-drawing-ui/src/facade/f-range.ts
index 79429473e2..47e40c46e9 100644
--- a/packages/sheets-drawing-ui/src/facade/f-range.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-range.ts
@@ -17,9 +17,24 @@
import type { ISheetLocationBase } from '@univerjs/sheets';
import { IUniverInstanceService, UniverInstanceType } from '@univerjs/core';
import { getCurrentTypeOfRenderer, IRenderManagerService } from '@univerjs/engine-render';
-import { SheetDrawingUpdateController } from '@univerjs/sheets-drawing-ui';
+import { FileNamePart, IBatchSaveImagesService, SheetDrawingUpdateController } from '@univerjs/sheets-drawing-ui';
import { FRange } from '@univerjs/sheets/facade';
+/**
+ * Options for saving cell images
+ */
+export interface ISaveCellImagesOptions {
+ /**
+ * Whether to use cell address in file name (e.g., A1, B2)
+ * @default true
+ */
+ useCellAddress?: boolean;
+ /**
+ * Column index to use for file name (0-based). If specified, the value from this column will be used in file name.
+ */
+ useColumnIndex?: number;
+}
+
export interface IFRangeSheetDrawingMixin {
/**
* Inserts an image into the current cell.
@@ -38,6 +53,32 @@ export interface IFRangeSheetDrawingMixin {
* ```
*/
insertCellImageAsync(file: File | string): Promise<boolean>;
+
+ /**
+ * Save all cell images in this range to the file system.
+ * This method will open a directory picker dialog and save all images to the selected directory.
+ *
+ * @param {ISaveCellImagesOptions} [options] Options for saving images
+ * @returns {Promise<boolean>} True if images are saved successfully, otherwise false
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Save all cell images in range A1:D10
+ * const fRange = fWorksheet.getRange('A1:D10');
+ *
+ * // Save with default options (using cell address as file name)
+ * await fRange.saveCellImagesAsync();
+ *
+ * // Save with custom options
+ * await fRange.saveCellImagesAsync({
+ * useCellAddress: true,
+ * useColumnIndex: 0, // Use values from column A for file names
+ * });
+ * ```
+ */
+ saveCellImagesAsync(options?: ISaveCellImagesOptions): Promise<boolean>;
}
export class FRangeSheetDrawingUI extends FRange implements IFRangeSheetDrawingMixin {
@@ -61,6 +102,59 @@ export class FRangeSheetDrawingUI extends FRange implements IFRangeSheetDrawingM
return controller.insertCellImageByFile(file, location);
}
}
+
+ override async saveCellImagesAsync(options?: ISaveCellImagesOptions): Promise<boolean> {
+ const batchSaveService = this._injector.get(IBatchSaveImagesService);
+ const unitId = this._workbook.getUnitId();
+ const subUnitId = this._worksheet.getSheetId();
+ const range = this.getRange();
+
+ // Get images in the range
+ const images = batchSaveService.getCellImagesFromRanges(unitId, subUnitId, [range]);
+
+ if (images.length === 0) {
+ return false;
+ }
+
+ // If only one image, download directly
+ if (images.length === 1) {
+ try {
+ await batchSaveService.downloadSingleImage(images[0]);
+ return true;
+ } catch (error) {
+ console.error('Failed to download image:', error);
+ return false;
+ }
+ }
+
+ // Build config from options
+ const fileNameParts: FileNamePart[] = [];
+ const useCellAddress = options?.useCellAddress ?? true;
+ const useColumnIndex = options?.useColumnIndex;
+
+ if (useCellAddress) {
+ fileNameParts.push(FileNamePart.CELL_ADDRESS);
+ }
+ if (useColumnIndex !== undefined) {
+ fileNameParts.push(FileNamePart.COLUMN_VALUE);
+ }
+
+ // Ensure at least one naming option
+ if (fileNameParts.length === 0) {
+ fileNameParts.push(FileNamePart.CELL_ADDRESS);
+ }
+
+ try {
+ await batchSaveService.saveImagesWithContext(images, {
+ fileNameParts,
+ columnIndex: useColumnIndex,
+ }, unitId, subUnitId);
+ return true;
+ } catch (error) {
+ console.error('Failed to save images:', error);
+ return false;
+ }
+ }
}
FRange.extend(FRangeSheetDrawingUI);
diff --git a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
index 7c1c479025..399c46a9b9 100644
--- a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
@@ -20,10 +20,11 @@ import type { ISheetFloatDom, ISheetImage } from '@univerjs/sheets-drawing';
import type { ICanvasFloatDom, ICanvasFloatDomInfo, IDOMAnchor } from '@univerjs/sheets-drawing-ui';
import type { IFComponentKey } from '@univerjs/sheets-ui/facade';
import type { FRange } from '@univerjs/sheets/facade';
+import type { ISaveCellImagesOptions } from './f-range';
import { DrawingTypeEnum, ImageSourceType, toDisposable } from '@univerjs/core';
import { IRenderManagerService } from '@univerjs/engine-render';
import { ISheetDrawingService } from '@univerjs/sheets-drawing';
-import { InsertSheetDrawingCommand, RemoveSheetDrawingCommand, SetSheetDrawingCommand, SheetCanvasFloatDomManagerService, transformToDrawingPosition } from '@univerjs/sheets-drawing-ui';
+import { FileNamePart, IBatchSaveImagesService, InsertSheetDrawingCommand, RemoveSheetDrawingCommand, SetSheetDrawingCommand, SheetCanvasFloatDomManagerService, transformToDrawingPosition } from '@univerjs/sheets-drawing-ui';
import { ISheetSelectionRenderService } from '@univerjs/sheets-ui';
import { transformComponentKey } from '@univerjs/sheets-ui/facade';
import { FWorksheet } from '@univerjs/sheets/facade';
@@ -588,6 +589,34 @@ export interface IFWorksheetLegacy {
* ```
*/
newOverGridImage(): FOverGridImageBuilder;
+
+ /**
+ * Save all cell images from specified ranges to the file system.
+ * This method will open a directory picker dialog and save all images to the selected directory.
+ *
+ * @param {ISaveCellImagesOptions} [options] - Options for saving images
+ * @param {FRange[]} [ranges] - The ranges to get cell images from. If not provided, all images in the worksheet will be saved.
+ * @returns {Promise<boolean>} True if images are saved successfully, otherwise false
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Save cell images from multiple ranges
+ * const range1 = fWorksheet.getRange('A1:B10');
+ * const range2 = fWorksheet.getRange('D1:E10');
+ *
+ * // Save with default options (using cell address as file name)
+ * await fWorksheet.saveCellImagesAsync(undefined, [range1, range2]);
+ *
+ * // Save with custom options
+ * await fWorksheet.saveCellImagesAsync({
+ * useCellAddress: true,
+ * useColumnIndex: 2, // Use values from column C for file names
+ * }, [range1, range2]);
+ * ```
+ */
+ saveCellImagesAsync(options?: ISaveCellImagesOptions, ranges?: FRange[]): Promise<boolean>;
}
export class FWorksheetLegacy extends FWorksheet implements IFWorksheetLegacy {
@@ -1011,6 +1040,61 @@ export class FWorksheetLegacy extends FWorksheet implements IFWorksheetLegacy {
const subUnitId = this.getSheetId();
return this._injector.createInstance(FOverGridImageBuilder, unitId, subUnitId);
}
+
+ override async saveCellImagesAsync(options?: ISaveCellImagesOptions, ranges?: FRange[]): Promise<boolean> {
+ const batchSaveService = this._injector.get(IBatchSaveImagesService);
+ const unitId = this._fWorkbook.getId();
+ const subUnitId = this.getSheetId();
+
+ // Get all ranges as IRange array
+ const iRanges = ranges ? ranges.map((r) => r.getRange()) : [this._worksheet.getCellMatrix().getDataRange()];
+
+ // Get images from all ranges
+ const images = batchSaveService.getCellImagesFromRanges(unitId, subUnitId, iRanges);
+
+ if (images.length === 0) {
+ return false;
+ }
+
+ // If only one image, download directly
+ if (images.length === 1) {
+ try {
+ await batchSaveService.downloadSingleImage(images[0]);
+ return true;
+ } catch (error) {
+ console.error('Failed to download image:', error);
+ return false;
+ }
+ }
+
+ // Build config from options
+ const fileNameParts: FileNamePart[] = [];
+ const useCellAddress = options?.useCellAddress ?? true;
+ const useColumnIndex = options?.useColumnIndex;
+
+ if (useCellAddress) {
+ fileNameParts.push(FileNamePart.CELL_ADDRESS);
+ }
+ if (useColumnIndex !== undefined) {
+ fileNameParts.push(FileNamePart.COLUMN_VALUE);
+ }
+
+ // Ensure at least one naming option
+ if (fileNameParts.length === 0) {
+ fileNameParts.push(FileNamePart.CELL_ADDRESS);
+ }
+
+ try {
+ await batchSaveService.saveImagesWithContext(images, {
+ fileNameParts,
+ columnIndex: useColumnIndex,
+ }, unitId, subUnitId);
+ return true;
+ } catch (error) {
+ console.error('Failed to save images:', error);
+ return false;
+ }
+ }
}
FWorksheet.extend(FWorksheetLegacy);
diff --git a/packages/sheets-drawing-ui/src/services/batch-save-images.service.ts b/packages/sheets-drawing-ui/src/services/batch-save-images.service.ts
index 806528accb..2d1a5df937 100644
--- a/packages/sheets-drawing-ui/src/services/batch-save-images.service.ts
+++ b/packages/sheets-drawing-ui/src/services/batch-save-images.service.ts
@@ -19,6 +19,13 @@ import type { IImageData } from '@univerjs/drawing';
import { createIdentifier, Disposable, IImageIoService, ImageSourceType, Inject, IUniverInstanceService, UniverInstanceType } from '@univerjs/core';
import { SheetsSelectionsService } from '@univerjs/sheets';
+declare global {
+ // eslint-disable-next-line ts/naming-convention
+ interface Window {
+ showDirectoryPicker(options?: { mode?: 'read' | 'readwrite' }): Promise<FileSystemDirectoryHandle>;
+ }
+}
+
/**
* File name part type for multi-select
*/
@@ -59,11 +66,27 @@ export interface IBatchSaveImagesService {
*/
getCellImagesInSelection(): ICellImageInfo[];
+ /**
+ * Get cell images from specified ranges
+ * @param unitId The workbook unit ID
+ * @param subUnitId The worksheet ID
+ * @param ranges The ranges to get images from
+ */
+ getCellImagesFromRanges(unitId: string, subUnitId: string, ranges: IRange[]): ICellImageInfo[];
+
/**
* Get columns that have data in the current selection
*/
getDataColumns(): Array<{ index: number; label: string }>;
+ /**
+ * Get columns that have data for specified ranges
+ * @param unitId The workbook unit ID
+ * @param subUnitId The worksheet ID
+ * @param ranges The ranges to check
+ */
+ getDataColumnsForRanges(unitId: string, subUnitId: string, ranges: IRange[]): Array<{ index: number; label: string }>;
+
/**
* Get current selection range as A1 notation
*/
@@ -76,6 +99,15 @@ export interface IBatchSaveImagesService {
*/
generateFileName(imageInfo: ICellImageInfo, config: IBatchSaveImagesConfig): string;
+ /**
+ * Generate file name with specified worksheet context
+ * @param imageInfo The cell image info
+ * @param config The file name configuration
+ * @param unitId The workbook unit ID
+ * @param subUnitId The worksheet ID
+ */
+ generateFileNameWithContext(imageInfo: ICellImageInfo, config: IBatchSaveImagesConfig, unitId: string, subUnitId: string): string;
+
/**
* Save images to the file system
* @param images The images to save
@@ -83,6 +115,15 @@ export interface IBatchSaveImagesService {
*/
saveImages(images: ICellImageInfo[], config: IBatchSaveImagesConfig): Promise<void>;
+ /**
+ * Save images to the file system with specified worksheet context
+ * @param images The images to save
+ * @param config The file name configuration
+ * @param unitId The workbook unit ID
+ * @param subUnitId The worksheet ID
+ */
+ saveImagesWithContext(images: ICellImageInfo[], config: IBatchSaveImagesConfig, unitId: string, subUnitId: string): Promise<void>;
+
/**
* Download a single image directly
* @param imageInfo The cell image info
@@ -249,6 +290,43 @@ export class BatchSaveImagesService extends Disposable implements IBatchSaveImag
return images;
}
+ getCellImagesFromRanges(unitId: string, subUnitId: string, ranges: IRange[]): ICellImageInfo[] {
+ const workbook = this._univerInstanceService.getUnit<Workbook>(unitId, UniverInstanceType.UNIVER_SHEET);
+ if (!workbook) return [];
+
+ const worksheet = workbook.getSheetBySheetId(subUnitId);
+ if (!worksheet) return [];
+
+ const cellMatrix = worksheet.getCellMatrix();
+ const images: ICellImageInfo[] = [];
+
+ for (const range of ranges) {
+ const { startRow, endRow, startColumn, endColumn } = range;
+
+ for (let row = startRow; row <= endRow; row++) {
+ for (let col = startColumn; col <= endColumn; col++) {
+ const cell = cellMatrix.getValue(row, col);
+
+ if (cellHasImage(cell)) {
+ const imageData = getCellImageData(cell!);
+ if (imageData) {
+ images.push({
+ row,
+ col,
+ cellAddress: toA1Notation(row, col),
+ source: imageData.source,
+ imageSourceType: imageData.imageSourceType,
+ imageId: imageData.drawingId,
+ });
+ }
+ }
+ }
+ }
+ }
+
+ return images;
+ }
+
getDataColumns(): Array<{ index: number; label: string }> {
const workbook = this._univerInstanceService.getCurrentUnitForType<Workbook>(UniverInstanceType.UNIVER_SHEET);
if (!workbook) return [];
@@ -312,6 +390,66 @@ export class BatchSaveImagesService extends Disposable implements IBatchSaveImag
return columns;
}
+ getDataColumnsForRanges(unitId: string, subUnitId: string, ranges: IRange[]): Array<{ index: number; label: string }> {
+ const workbook = this._univerInstanceService.getUnit<Workbook>(unitId, UniverInstanceType.UNIVER_SHEET);
+ if (!workbook) return [];
+
+ const worksheet = workbook.getSheetBySheetId(subUnitId);
+ if (!worksheet) return [];
+
+ const cellMatrix = worksheet.getCellMatrix();
+ const dataRange = cellMatrix.getDataRange();
+
+ // Get row range and column indices from ranges
+ let minRow = Infinity;
+ let maxRow = -Infinity;
+ const rangeColumnIndices = new Set<number>();
+
+ for (const range of ranges) {
+ minRow = Math.min(minRow, range.startRow);
+ maxRow = Math.max(maxRow, range.endRow);
+
+ // Collect all column indices within ranges
+ for (let col = range.startColumn; col <= range.endColumn; col++) {
+ rangeColumnIndices.add(col);
+ }
+ }
+
+ // Find columns that have values in the row range, excluding range columns
+ const columnsWithData = new Set<number>();
+
+ for (let col = dataRange.startColumn; col <= dataRange.endColumn; col++) {
+ // Skip columns that are within the ranges
+ if (rangeColumnIndices.has(col)) {
+ continue;
+ }
+
+ for (let row = minRow; row <= maxRow; row++) {
+ const cell = cellMatrix.getValue(row, col);
+ if (cell) {
+ const value = cell.v?.toString() || cell.p?.body?.dataStream?.trim() || '';
+ if (value) {
+ columnsWithData.add(col);
+ break;
+ }
+ }
+ }
+ }
+
+ // Convert to array and sort
+ const columns: Array<{ index: number; label: string }> = [];
+ const sortedCols = Array.from(columnsWithData).sort((a, b) => a - b);
+
+ for (const col of sortedCols) {
+ columns.push({
+ index: col,
+ label: columnIndexToLetter(col),
+ });
+ }
+
+ return columns;
+ }
+
getSelectionRangeNotation(): string {
const selections = this._selectionService.getCurrentSelections();
if (!selections || selections.length === 0) return '';
@@ -390,11 +528,48 @@ export class BatchSaveImagesService extends Disposable implements IBatchSaveImag
return `${parts.join('_')}.${extension}`;
}
+ generateFileNameWithContext(imageInfo: ICellImageInfo, config: IBatchSaveImagesConfig, unitId: string, subUnitId: string): string {
+ const workbook = this._univerInstanceService.getUnit<Workbook>(unitId, UniverInstanceType.UNIVER_SHEET);
+ const extension = getFileExtension(imageInfo.source, imageInfo.imageSourceType);
+ const parts: string[] = [];
+
+ // Process each selected file name part in order
+ for (const part of config.fileNameParts) {
+ if (part === FileNamePart.CELL_ADDRESS) {
+ parts.push(imageInfo.cellAddress);
+ } else if (part === FileNamePart.COLUMN_VALUE && config.columnIndex !== undefined) {
+ const worksheet = workbook?.getSheetBySheetId(subUnitId);
+ if (worksheet) {
+ const cellMatrix = worksheet.getCellMatrix();
+ const cell = cellMatrix.getValue(imageInfo.row, config.columnIndex);
+
+ if (cell) {
+ // Get cell display value
+ const value = cell.v?.toString() || cell.p?.body?.dataStream?.trim() || '';
+ if (value) {
+ // Sanitize file name (remove invalid characters)
+ const sanitized = value.replace(/[<>:"/\\|?*]/g, '_').trim();
+ if (sanitized) {
+ parts.push(sanitized);
+ }
+ }
+ }
+ }
+ }
+ }
+
+ // If no parts selected or all parts failed, use cell address as default
+ if (parts.length === 0) {
+ return `${imageInfo.cellAddress}.${extension}`;
+ }
+
+ // Join parts with underscore
+ return `${parts.join('_')}.${extension}`;
+ }
+
async saveImages(images: ICellImageInfo[], config: IBatchSaveImagesConfig): Promise<void> {
// Request directory access using File System Access API
- // eslint-disable-next-line ts/no-explicit-any
- const dirHandle = await (window as any).showDirectoryPicker({ mode: 'readwrite' });
-
+ const dirHandle = await window.showDirectoryPicker({ mode: 'readwrite' });
// Track file names to handle duplicates
const fileNameCounts = new Map<string, number>();
@@ -427,6 +602,42 @@ export class BatchSaveImagesService extends Disposable implements IBatchSaveImag
}
}
+ async saveImagesWithContext(images: ICellImageInfo[], config: IBatchSaveImagesConfig, unitId: string, subUnitId: string): Promise<void> {
+ // Request directory access using File System Access API
+ const dirHandle = await window.showDirectoryPicker({ mode: 'readwrite' });
+
+ // Track file names to handle duplicates
+ const fileNameCounts = new Map<string, number>();
+
+ for (const imageInfo of images) {
+ let fileName = this.generateFileNameWithContext(imageInfo, config, unitId, subUnitId);
+
+ // Handle duplicate file names
+ const baseName = fileName.replace(/\.\w+$/, '');
+ const ext = fileName.match(/\.\w+$/)?.[0] || '.png';
+
+ const count = fileNameCounts.get(baseName) || 0;
+ if (count > 0) {
+ fileName = `${baseName}_${count}${ext}`;
+ }
+ fileNameCounts.set(baseName, count + 1);
+
+ try {
+ // Get image blob
+ const blob = await this._getImageBlob(imageInfo);
+
+ // Create file and write
+ const fileHandle = await dirHandle.getFileHandle(fileName, { create: true });
+ const writable = await fileHandle.createWritable();
+ await writable.write(blob);
+ await writable.close();
+ } catch (error) {
+ console.error(`Failed to save image ${fileName}:`, error);
+ throw error;
+ }
+ }
+ }
+
async downloadSingleImage(imageInfo: ICellImageInfo): Promise<void> {
const extension = getFileExtension(imageInfo.source, imageInfo.imageSourceType);
const fileName = `${imageInfo.cellAddress}.${extension}`;