worksheet.insert_image() 参考
insert_image
(row, col, image[, options])
Insert an image in a worksheet cell.
Parameters: | |
---|---|
Returns: | 0: Success. |
Returns: | -1: Row or column is out of worksheet bounds. |
This method can be used to insert a image into a worksheet. The image can be in PNG, JPEG, BMP, WMF or EMF format (see the notes about BMP and EMF below):
worksheet.insert_image('B2', 'python.png')
Both row-column and A1 style notation are supported. The following are equivalent:
worksheet.insert_image(1, 1, 'python.png')
worksheet.insert_image('B2', 'python.png')
See Working with Cell Notation for more details.
A file path can be specified with the image name:
worksheet1.insert_image('B10', '../images/python.png')
worksheet2.insert_image('B20', r'c:\images\python.png')
The insert_image()
method takes optional parameters in a dictionary to position and scale the image. The available parameters with their default values are:
{
'x_offset': 0,
'y_offset': 0,
'x_scale': 1,
'y_scale': 1,
'url': None,
'tip': None,
'image_data': None,
'positioning': None,
}
The offset values are in pixels:
worksheet1.insert_image('B2', 'python.png', {'x_offset': 15, 'y_offset': 10})
The offsets can be greater than the width or height of the underlying cell. This can be occasionally useful if you wish to align two or more images relative to the same cell.
The x_scale
and y_scale
parameters can be used to scale the image horizontally and vertically:
worksheet.insert_image('B3', 'python.png', {'x_scale': 0.5, 'y_scale': 0.5})
The url
parameter can used to add a hyperlink/url to the image. The tip
parameter gives an option mouseover tooltip for images with hyperlinks:
worksheet.insert_image('B4', 'python.png', {'url': 'https://python.org'})
See also write_url()
for details on supported URIs.
The image_data
parameter is used to add an in-memory byte stream in io.BytesIO
format:
worksheet.insert_image('B5', 'python.png', {'image_data': image_data})
This is generally used for inserting images from URLs:
url = 'https://python.org/logo.png'
image_data = io.BytesIO(urllib2.urlopen(url).read())
worksheet.insert_image('B5', url, {'image_data': image_data})
When using the image_data
parameter a filename must still be passed to insert_image()
since it is required by Excel. In the previous example the filename is extracted from the URL string. See also Example: Inserting images from a URL or byte stream into a worksheet.
The positioning
parameter can be used to control the object positioning of the image:
worksheet.insert_image('B3', 'python.png', {'positioning': 1})
Where positioning
has the following allowable values:
- Move and size with cells.
- Move but don’t size with cells (the default).
- Don’t move or size with cells.
Note
The scaling of a image may be affected if is crosses a row that has its default height changed due to a font that is larger than the default font size or that has text wrapping turned on. To avoid this you should explicitly set the height of the row using set_row()
if it crosses an inserted image.
Note
BMP images are only supported for backward compatibility. In general it is best to avoid BMP images since they aren’t compressed. If used, BMP images must be 24 bit, true color, bitmaps.
Note
EMF images can have very small differences in width and height when compared to Excel files. Despite a lot of effort and testing it wasn’t possible to match exactly Excel’s calculations for handling the dimensions of EMF files. However, the differences are are small (< 1%) and in general aren’t visible.