Working with Pictures

Lavorare con le immagini

Lavorare con le Immagini

Aspose.Cells FOSS per Java consente di incorporare immagini direttamente nelle celle del foglio di lavoro e di recuperare o rimuovere le immagini esistenti. Le immagini sono gestite tramite il PictureCollection esposto da ciascun Worksheet, e ogni oggetto Picture fornisce l’accesso ai dati dell’immagine, alla sua posizione di ancoraggio, al tipo di immagine rilevato e al tipo MIME del contenuto.

Panoramica

Ogni foglio di lavoro espone le sue immagini tramite Worksheet.getPictures(), che restituisce un PictureCollection. È possibile aggiungere immagini da un array di byte, un InputStream, o un percorso file. La collezione fornisce metodi di supporto per rilevare il tipo di immagine da byte grezzi, determinare l’estensione del file dai dati dell’immagine e mappare l’estensione al tipo MIME del contenuto.

Accedere alle Immagini su un Foglio di Lavoro

Recupera il PictureCollection tramite Worksheet.getPictures(). Utilizza PictureCollection.getCount() per determinare quante immagini sono presenti. Le singole immagini sono accessibili tramite indice a base zero attraverso PictureCollection.get(index).

Aggiungere un’Immagine

Sono disponibili tre overload di PictureCollection.add(), ognuno dei quali restituisce l’indice a base zero dell’immagine appena aggiunta:

add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, imageData) da un array di byte
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, stream) da un InputStream
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, fileName) da un percorso file

// Embed an image from bytes into cells A1:C5
byte[] imgData = Files.readAllBytes(Paths.get("logo.png"));
int idx = ws.getPictures().add(0, 0, 4, 2, imgData);

Lettura delle proprietà dell’immagine

Una volta che possiedi un riferimento Picture, leggi la sua posizione di ancoraggio, i dati grezzi dell’immagine, il tipo di immagine rilevato e il tipo MIME del contenuto:

PictureCollection pics = ws.getPictures();
for (int i = 0; i < pics.getCount(); i++) {
    Picture p = pics.get(i);
    System.out.printf("Name=%s type=%s anchor=[%d,%d]-[%d,%d]%n",
        p.getName(), p.getImageType(),
        p.getUpperLeftRow(), p.getUpperLeftColumn(),
        p.getLowerRightRow(), p.getLowerRightColumn());
}

Rilevamento del tipo di immagine da byte grezzi

Usa PictureCollection.detectImageType(data) per determinare il valore enum ImageType di un array di byte senza prima incorporarlo.

PictureCollection pics = ws.getPictures();
byte[] data = Files.readAllBytes(Paths.get("chart.png"));
ImageType type = pics.detectImageType(data);
String ext  = pics.extensionFromData(data);
String mime = pics.contentTypeFromExtension(ext);
System.out.printf("type=%s ext=%s mime=%s%n", type, ext, mime);

Rimozione di un’immagine

Usa PictureCollection.removeAt(index) per eliminare un’immagine mediante il suo indice a zero:

ws.getPictures().removeAt(0);

Suggerimenti e migliori pratiche

Usa il overload add(..., imageData) quando hai già i byte in memoria; usa l’overload stream per evitare di caricare interamente file di grandi dimensioni.
Chiama PictureCollection.detectImageType(data) per convalidare il formato dell’immagine prima di incorporarla.
Le righe e le colonne di ancoraggio sono indici a zero.
Picture.getName() restituisce un identificatore interno, non il nome file originale.
Le immagini sono preservate nel round-trip XLSX.

Problemi comuni

Problema	Causa	Correzione
`getCount()` restituisce 0 dopo add	Lo stream è stato chiuso prima che l’add fosse completato	Assicurati che il InputStream sia aperto e leggibile
`ImageType.UNKNOWN` restituito	Dati immagine non supportati o corrotti	Verifica che il file sia un PNG, JPEG, GIF, BMP o TIFF valido
La posizione dell’immagine sembra errata	Gli indici di riga/colonna sono errati	Usa indici a base zero per tutti i parametri di ancoraggio

FAQ

Quali formati immagine sono supportati per l’incorporamento?

L’enumerazione ImageType copre PNG, JPEG, GIF, BMP, TIFF e EMF. Altri formati possono essere incorporati come dati binari ma hanno un ImageType di UNKNOWN.

Come ottengo l’estensione del file di un’immagine incorporata?

Chiama PictureCollection.extensionFromData(picture.getData()) con i byte grezzi dell’immagine.

Posso sostituire i dati immagine di una foto esistente?

Sì. Recupera il Picture tramite get(index) e chiama setData(bytes).

Come trovo un’immagine per nome?

Itera su tutte le immagini con getCount() e get(index) e confronta Picture.getName().

Le immagini vengono preservate quando si salva in altri formati?

La conservazione delle immagini dipende dal formato di destinazione. XLSX round-trip è pienamente supportato.

API Reference Riepilogo

Picture

Metodo	Tipo di ritorno	Descrizione
`getName()`	`String`	Nome interno dell’immagine.
`setName(name)`	`void`	Imposta il nome interno.
`getUpperLeftRow()`	`int`	Riga a indice zero dell’ancora in alto a sinistra.
`setUpperLeftRow(row)`	`void`	Imposta la riga di ancoraggio in alto a sinistra.
`getUpperLeftColumn()`	`int`	Colonna a indice zero dell’ancora in alto a sinistra.
`setUpperLeftColumn(col)`	`void`	Imposta la colonna di ancoraggio in alto a sinistra.
`getLowerRightRow()`	`int`	Riga a indice zero dell’ancora in basso a destra.
`setLowerRightRow(row)`	`void`	Imposta la riga di ancoraggio in basso a destra.
`getLowerRightColumn()`	`int`	Colonna a base zero dell’ancora in basso a destra.
`setLowerRightColumn(col)`	`void`	Imposta la colonna di ancoraggio in basso a destra.
`getImageType()`	`ImageType`	Valore enum del formato immagine rilevato.
`getData()`	`byte[]`	Byte dell’immagine grezzi.
`setData(data)`	`void`	Sostituisce i byte grezzi dell’immagine.
`getContentType()`	`String`	Stringa del tipo di contenuto MIME.

PictureCollection

Metodo	Tipo di ritorno	Descrizione
`getCount()`	`int`	Numero di immagini nel foglio di lavoro.
`get(index)`	`Picture`	Restituisce l’immagine all’indice basato su zero.
`add(...)`	`int`	Incorpora un’immagine; restituisce il suo indice basato su zero.
`removeAt(index)`	`void`	Rimuove l’immagine all’indice basato su zero.
`detectImageType(data)`	`ImageType`	Rileva il formato dell’immagine dai byte grezzi.
`extensionFromData(data)`	`String`	Restituisce l’estensione del file per i dati dell’immagine.
`contentTypeFromExtension(ext)`	`String`	Restituisce il tipo MIME per un’estensione di file.

Vedi anche

Aspose.Cells for Java — Enterprise Documentation