Range¶

class Range(cell1=None, cell2=None, **options)¶

返回一个区域对象，可以代表一个单元格，也可以是一个区域。

Arguments¶

cell1str or tuple or Range: 区域左上角的名字，可以是A1表示法、坐标元组、名字或者是xw.Range对象。也可用用区域操作符号(例如 ‘A1:B2’ )来表示。
cell2str or tuple or Range, default None: 区域右下角角的名字，可以是A1表示法、坐标元组、名字或者是 xw.Range 对象。

示例¶

import xlwings as xw
sheet1 = xw.Book("MyBook.xlsx").sheets[0]

sheet1.range("A1")
sheet1.range("A1:C3")
sheet1.range((1,1))
sheet1.range((1,1), (3,3))
sheet1.range("NamedRange")

# Or using index/slice notation
sheet1["A1"]
sheet1["A1:C3"]
sheet1[0, 0]
sheet1[0:4, 0:4]
sheet1["NamedRange"]

add_hyperlink(address, text_to_display=None, screen_tip=None)¶

在指定的区域(单个单元格)中加一个超链接

Arguments¶

addressstr: 超链接地址。
text_to_displaystr, default None: 超链接的显示字符串，缺省为超链接地址本身。
screen_tip: str, default None: 当鼠标停留在超链接上方是显示的屏幕提示。缺省情况下设置为'<address> - 单击一次可跟踪超链接，单击并按住不放选择此单元格。'

Added in version 0.3.0.

property address¶: Returns a string value that represents the range reference. Use get_address() to be able to provide parameters.

Added in version 0.9.0.

adjust_indent(amount)¶

Adjusts the indentation in a Range.

Arguments¶

amountint: Number of spaces by which the indent is adjusted. Can be positive or negative.

property api¶: 返回正在使用的引擎的原生对象( pywin32 或 appscript 对象)。

Added in version 0.9.0.

autofill(destination, type_='fill_default')¶

Autofills the destination Range. Note that the destination Range must include the origin Range.

Arguments¶

destinationRange: The origin.
type_str, default "fill_default": One of the following strings: "fill_copy", "fill_days", "fill_default", "fill_formats", "fill_months", "fill_series", "fill_values", "fill_weekdays", "fill_years", "growth_trend", "linear_trend", "flash_fill

Added in version 0.30.1.

autofit()¶

使得区域内所有单元格的宽度和高度进行自适应。

To autofit only the width of the columns use myrange.columns.autofit()
To autofit only the height of the rows use myrange.rows.autofit()

在 0.9.0 版本发生变更.

clear()¶: 清除区域的内容和格式。

clear_contents()¶: 清除区域的内容，保留格式。

clear_formats()¶: Clears the format of a Range but leaves the content.

Added in version 0.26.2.

property color¶

获取指定区域的背景色。

To set the color, either use an RGB tuple (0, 0, 0) or a hex string like #efefef or an Excel color constant. To remove the background, set the color to None, see Examples.

返回¶

RGB : tuple

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = xw.sheets[0]
>>> sheet1.range('A1').color = (255, 255, 255)  # or '#ffffff'
>>> sheet1.range('A2').color
(255, 255, 255)
>>> sheet1.range('A2').color = None
>>> sheet1.range('A2').color is None
True

Added in version 0.3.0.

property column¶: 返回指定区域的第一列的值，只读。

返回¶

Integer

Added in version 0.3.5.

property column_width¶

获取或者设置区域的宽度(单位是字符数)。 Normal 风格中一个列宽单位就是一个字符宽度。对于等宽字体，用的单位宽度是字符0(数字0)的宽度。

如果区域中的列宽相同，返回宽度。如果各个列宽不同，返回 None 。

列宽必须在下列范围内: 0 <= 列宽 <= 255

注意: 如果区域不在工作表已经使用的区域内，并且区域内的各列的宽度不同，返回第一列的宽度。

返回¶

float

Added in version 0.4.0.

property columns¶: 返回一个 RangeColumns 对象，它代表指定区域内的列。

Added in version 0.9.0.

copy(destination=None)¶

把一个区域拷贝到目的区域或者剪贴板。

参数¶

destinationxlwings.Range: xlwings Range to which the specified range will be copied. If omitted, the range is copied to the clipboard.

返回¶

None

copy_picture(appearance='screen', format='picture')¶

Copies the range to the clipboard as picture.

参数¶

appearancestr, default 'screen': Either 'screen' or 'printer'.
formatstr, default 'picture': Either 'picture' or 'bitmap'.

Added in version 0.24.8.

property count¶: 返回单元格数量。

property current_region¶: 返回一个区域，这个区域由空行、空列或者工作表的边界围成的(不包含围绕区域的空行或空列)。这个和Windows中的 Ctrl-* 及Mac上的 shift-Ctrl-Space 一致。

返回¶

Range object

delete(shift=None)¶

删除一个单元格或者一个区域的单元格。

参数¶

shiftstr, default None: 使用 left 或 up 。如果省略，Excel根据区域的形状决定。

返回¶

None

end(direction)¶

返回区域内的边界单元格，得到的结果与按 Ctrl+Up , Ctrl+down , Ctrl+left , 或 Ctrl+right 组合键得到的结果相同。

参数¶

direction : One of 'up', 'down', 'right', 'left'

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = xw.sheets[0]
>>> sheet1.range('A1:B2').value = 1
>>> sheet1.range('A1').end('down')
<Range [Book1]Sheet1!$A$2>
>>> sheet1.range('B2').end('right')
<Range [Book1]Sheet1!$B$2>

Added in version 0.9.0.

expand(mode='table')¶

根据要求的模式扩展单元格，不管左上角是否为空。(不像 Range.end() ).

参数¶

modestr, default 'table': 可以取 'down' , 'right' ,``'table'`` (=down + right)。

返回¶

Range

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range('A1').value = [[None, 1], [2, 3]]
>>> sheet1.range('A1').expand().address
$A$1:$B$2
>>> sheet1.range('A1').expand('right').address
$A$1:$B$1

Added in version 0.9.0.

property formula¶: 对于给定的区域，获取或者设置公式。

property formula2¶: Gets or sets the formula2 for the given Range.

property formula_array¶: 对于给定的区域，获取或者设置数组公式。

Added in version 0.7.1.

get_address(row_absolute=True, column_absolute=True, include_sheetname=False, external=False)¶

用指定的格式返回区域的地址。当所有参数都是缺省的时候，和用 address 属性得到的结果是相同的。

Arguments¶

row_absolutebool类型, 缺省值为True: 设为 True 时，返回行部分的绝对引用。
column_absolutebool类型, 缺省值为True: 设为 True 时，返回列部分的绝对引用。
include_sheetnamebool类型, 缺省值为False: 设为 True 时，返回的地址中包含工作表名。如果 external=True ，不管这里的设置如何，都带工作表名。
externalbool类型, 缺省值为False: 设为 True 时，返回带有工作簿名和工作表名的外部引用地址。

返回¶

str

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range((1,1)).get_address()
'$A$1'
>>> sheet1.range((1,1)).get_address(False, False)
'A1'
>>> sheet1.range((1,1), (3,3)).get_address(True, False, True)
'Sheet1!A$1:C$3'
>>> sheet1.range((1,1), (3,3)).get_address(True, False, external=True)
'[Book1]Sheet1!A$1:C$3'

Added in version 0.2.3.

group(by=None)¶

Group rows or columns.

Arguments¶

bystr, optional: "columns" or "rows". Figured out automatically if the range is defined as '1:3' or 'A:C', respectively.

property has_array¶: True if the range is part of a legacy CSE Array formula and False otherwise.

property height¶: 返回区域的高度，单位是点。只读。

返回¶

float

Added in version 0.4.0.

property hyperlink¶

返回指定区域的超链接(仅适合单个单元格)

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range('A1').value
'www.xlwings.org'
>>> sheet1.range('A1').hyperlink
'http://www.xlwings.org'

Added in version 0.3.0.

insert(shift, copy_origin='format_from_left_or_above')¶

在工作表中插入一个单元格或者一个区域。

参数¶

shiftstr: Use right or down.
copy_originstr, default format_from_left_or_above: Use format_from_left_or_above or format_from_right_or_below. Note that copy_origin is only supported on Windows.

返回¶

None

在 0.30.3 版本发生变更: shift is now a required argument.

property last_cell¶

返回指定区域的右下角单元格。只读。

返回¶

Range

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> myrange = sheet1.range('A1:E4')
>>> myrange.last_cell.row, myrange.last_cell.column
(4, 5)

Added in version 0.3.5.

property left¶: 返回A列的左边缘到区域的左边界的距离，单位点(point)，只读。

返回¶

float

Added in version 0.6.0.

merge(across=False)¶

Creates a merged cell from the specified Range object.

参数¶

acrossbool类型, 缺省值为False: True to merge cells in each row of the specified Range as separate merged cells.

property merge_area¶: Returns a Range object that represents the merged Range containing the specified cell. If the specified cell isn't in a merged range, this property returns the specified cell.

property merge_cells¶: Returns True if the Range contains merged cells, otherwise False

property name¶: 获取或者设置区域的名字。

Added in version 0.4.0.

property note¶: Returns a Note object. Before the introduction of threaded comments, a Note was called a Comment.

Added in version 0.24.2.

property number_format¶

获取或者设置区域的数字格式( number_format )。

示例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range('A1').number_format
'General'
>>> sheet1.range('A1:C3').number_format = '0.00%'
>>> sheet1.range('A1:C3').number_format
'0.00%'

Added in version 0.2.3.

offset(row_offset=0, column_offset=0)¶: 返回一个从指定单元格为起始点的区域对象。

返回¶

Range object : Range

Added in version 0.3.0.

options(convert=None, **options)¶

允许用户设定转换器和相关的选项。转换器定义了Excel的区域及其值在读写过程中如何转换。如果没有明确指定转换器，会使用基转换器(base converter)。参考：转换器及选项。

Arguments¶

convertobject, default None: 转换器名称，例如：dict, np.array, pd.DataFrame, pd.Series 等, 缺省时使用缺省转换器。

关键词参数¶

ndimint, default None: 维数
numberstype, default None: 数字类型，如 int
datestype, default None: 例如 datetime.date ，缺省时是 datetime.datetime 。
emptyobject, default None: 空白单元格的转换
transposeBoolean, default False: 是否转置
expandstr, default None: 可以取下列值： 'table' , 'down' , 'right' 。
chunksizeint: Use a chunksize, e.g. 10000 to prevent timeout or memory issues when reading or writing large amounts of data. Works with all formats, including DataFrames, NumPy arrays, and list of lists.
err_to_strBoolean, default False: If True, will include cell errors such as #N/A as strings. By default, they will be converted to None.

Added in version 0.28.0.

=> 与转换器有关的选项，参考：转换器及选项。

返回¶

Range object

paste(paste=None, operation=None, skip_blanks=False, transpose=False)¶

从剪贴板里拷贝一个区域到指定区域

参数¶

pastestr, default None: 可以取下列值： all_merging_conditional_formats, all, all_except_borders, all_using_source_theme, column_widths, comments, formats, formulas, formulas_and_number_formats, validation, values, values_and_number_formats.
operationstr, default None: 可以取下列值： "add", "divide", "multiply", "subtract"。
skip_blanksbool类型, 缺省值为False: 设为 True 时忽略空白单元格
transposebool类型, 缺省值为False: 设为 True 时对行列转置

返回¶

None

property raw_value¶: Gets and sets the values directly as delivered from/accepted by the engine that s being used (pywin32 or appscript) without going through any of xlwings' data cleaning/converting. This can be helpful if speed is an issue but naturally will be engine specific, i.e. might remove the cross-platform compatibility.

resize(row_size=None, column_size=None)¶

重新调整指定区域的大小。

Arguments¶

row_size: int > 0: 新的区域的行数(如果为 None , 区域保持原来的行数不变)。
column_size: int > 0: 新的区域的列数(如果为 None , 区域保持原来的列数不变)。

返回¶

Range object: Range

Added in version 0.3.0.

property row¶: 返回区域第一行的行号。只读。

返回¶

Integer

Added in version 0.3.5.

property row_height¶

取得或者设置区域的行高，单位是 point 。如果区域内所有的行高度都一样，就返回这个高度。如果不一样，就返回 None 。

row_height必须在下列范围内: 0 <= row_height <= 409.5

注意：如果区域不在工作表已用区域内并且行高不同，返回第一行的高度。

返回¶

float

Added in version 0.4.0.

property rows¶: 返回一个代表指定区域内的行的 RangeRows 对象。

Added in version 0.9.0.

select()¶: 选中区域。只能在活动的工作簿中选。

Added in version 0.9.0.

property shape¶: 表示区域范围的元组。

Added in version 0.3.0.

property sheet¶: 返回区域所属的工作表对象。

Added in version 0.9.0.

property size¶: 区域内的单元格数量。

Added in version 0.3.0.

property table¶: Returns a Table object if the range is part of one, otherwise None.

Added in version 0.21.0.

to_pdf(path=None, layout=None, show=None, quality='standard')¶

Exports the range as PDF.

参数¶

pathstr or path-like, default None

Path where you want to store the pdf. Defaults to the address of the range in the same directory as the Excel file if the Excel file is stored and to the current working directory otherwise.

layoutstr or path-like object, default None

This argument requires xlwings PRO.

Path to a PDF file on which the report will be printed. This is ideal for headers and footers as well as borderless printing of graphics/artwork. The PDF file either needs to have only 1 page (every report page uses the same layout) or otherwise needs the same amount of pages as the report (each report page is printed on the respective page in the layout PDF).

showbool类型, 缺省值为False

Once created, open the PDF file with the default application.

qualitystr, default 'standard'

Quality of the PDF file. Can either be 'standard' or 'minimum'.

Added in version 0.26.2.

to_png(path=None)¶

Exports the range as PNG picture.

参数¶

pathstr or path-like, default None: Path where you want to store the picture. Defaults to the name of the range in the same directory as the Excel file if the Excel file is stored and to the current working directory otherwise.

Added in version 0.24.8.

property top¶: 返回从第一行的边缘到区域边缘的距离，单位是 point ，只读。

返回¶

float

Added in version 0.6.0.

ungroup(by=None)¶

Ungroup rows or columns

Arguments¶

bystr, optional: "columns" or "rows". Figured out automatically if the range is defined as '1:3' or 'A:C', respectively.

unmerge()¶: Separates a merged area into individual cells.

property value¶

Gets and sets the values for the given Range. See xlwings.Range.options() about how to set options, e.g., to transform it into a DataFrame or how to set a chunksize.

返回¶

objectreturned object depends on the converter being used,: see xlwings.Range.options()

property width¶: 返回一个区域的宽度，单位是 point ，只读。

返回¶

float

Added in version 0.4.0.

property wrap_text¶: Returns True if the wrap_text property is enabled and False if it's disabled. If not all cells have the same value in a range, on Windows it returns None and on macOS False.

Added in version 0.23.2.