Range

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

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

参数:

• cell1 (str | tuple[int, int] | Range | None) -- 区域左上角的名字，可以是A1表示法、坐标元组、名字或者是xw.Range对象。也可用用区域操作符号(例如 ‘A1:B2’ )来表示。

• cell2 (str | tuple[int, int] | Range | 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)

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

参数:

• address (str) -- 超链接地址。

• text_to_display (str | None) -- 超链接的显示字符串，缺省为超链接地址本身。

• screen_tip (str | None) -- 当鼠标停留在超链接上方是显示的屏幕提示。缺省情况下设置为'<address> - 单击一次可跟踪超链接，单击并按住不放选择此单元格。'

在 0.3.0 版本加入.

property address: str

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

在 0.9.0 版本加入.

adjust_indent(amount)

Adjusts the indentation in a Range.

参数:

amount (int) -- Number of spaces by which the indent is adjusted. Can be positive or negative.

property api: Any

Returns the native object (pywin32 or appscript obj) of the engine being used.

在 0.9.0 版本加入.

autofill(destination, type_='fill_default')

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

参数:

• destination (Range) -- The origin.

• type -- 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

在 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.

在 0.26.2 版本加入.

property color: tuple[int, int, int] | None

获取指定区域的背景色。

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.

示例

>>> 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

在 0.3.0 版本加入.

property column: int

返回指定区域的第一列的值，只读。

在 0.3.5 版本加入.

property column_width: float | None

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

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

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

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

在 0.4.0 版本加入.

property columns: RangeColumns

Returns a RangeColumns object that represents the columns in the specified range.

在 0.9.0 版本加入.

copy(destination=None)

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

参数:

destination (Range | None) -- xlwings Range to which the specified range will be copied. If omitted, the range is copied to the clipboard.

copy_from(source_range, copy_type='all', skip_blanks=False, transpose=False)

A newer variant of copy that replaces copy/paste.

参数:

• source_range (Range)

• copy_type (str) -- One of "all", "formats", "formulas", "link", "values"

• skip_blanks (bool)

• transpose (bool)

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

Copies the range to the clipboard as picture.

参数:

• appearance (str) -- Either 'screen' or 'printer'.

• format (str) -- Either 'picture' or 'bitmap'.

在 0.24.8 版本加入.

property count: int

返回单元格数量。

property current_region: Range

This property returns a Range object representing a range bounded by (but not including) any combination of blank rows and blank columns or the edges of the worksheet. It corresponds to Ctrl-* on Windows and Shift-Ctrl-Space on Mac.

delete(shift=None)

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

参数:

shift (str | None) -- 使用 left 或 up 。如果省略，Excel根据区域的形状决定。

end(direction)

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

参数:

direction (str)

示例

>>> 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>

在 0.9.0 版本加入.

expand(mode='table')

Expands the range according to the mode provided. Ignores empty top-left cells (unlike Range.end()).

参数:

mode (str) -- 可以取 'down' , 'right' ,``'table'`` (=down + right)。

示例

>>> 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

在 0.9.0 版本加入.

property formula: str | list[str] | list[list[str]]

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

property formula2: str | list[str] | list[list[str]]

Gets or sets the formula2 for the given Range.

property formula_array: str | None

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

在 0.7.1 版本加入.

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

Returns the address of the range in the specified format. address can be used instead if none of the defaults need to be changed.

参数:

• row_absolute (bool) -- 设为 True 时，返回行部分的绝对引用。

• column_absolute (bool) -- 设为 True 时，返回列部分的绝对引用。

• include_sheetname (bool) -- 设为 True 时，返回的地址中包含工作表名。如果 external=True ，不管这里的设置如何，都带工作表名。

• external (bool) -- 设为 True 时，返回带有工作簿名和工作表名的外部引用地址。

示例

>>> 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'

在 0.2.3 版本加入.

async get_value()

Fetch values from Excel on demand.

Requires xlwings Lite.

group(by=None)

Group rows or columns.

参数:

by (str | None) -- "columns" or "rows". Figured out automatically if the range is defined as '1:3' or 'A:C', respectively.

property has_array: bool

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

property height: float

返回区域的高度，单位是点。 只读。

在 0.4.0 版本加入.

property hyperlink: str

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

示例

>>> 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'

在 0.3.0 版本加入.

insert(shift, copy_origin='format_from_left_or_above')

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

参数:

• shift (str) -- Use right or down.

• copy_origin (str) -- Use format_from_left_or_above or format_from_right_or_below. Note that copy_origin is only supported on Windows.

在 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)

在 0.3.5 版本加入.

property left: float

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

在 0.6.0 版本加入.

merge(across=False)

Creates a merged cell from the specified Range object.

参数:

across (bool) -- True to merge cells in each row of the specified Range as separate merged cells.

property merge_area: Range

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: bool

Returns True if the Range contains merged cells, otherwise False

property name: Name | None

获取或者设置区域的名字。

在 0.4.0 版本加入.

property note: Note | None

Returns a Note object. Before the introduction of threaded comments, a Note was called a Comment.

在 0.24.2 版本加入.

property number_format: str

获取或者设置区域的数字格式( 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%'

在 0.2.3 版本加入.

offset(row_offset=0, column_offset=0)

返回一个从指定单元格为起始点的区域对象。

在 0.3.0 版本加入.

options(convert=None, **options)

Allows you to set a converter and their options. Converters define how Excel Ranges and their values are being converted both during reading and writing operations. If no explicit converter is specified, the base converter is being applied, see converters.

参数:

convert (Any) -- A converter, e.g. dict, np.array, pd.DataFrame, pd.Series, defaults to default converter.

:keyword ndim: Number of dimensions. :keyword numbers: Type of numbers, e.g. int. :keyword dates: E.g. datetime.date, defaults to datetime.datetime. :keyword empty: Transformation of empty cells. :keyword transpose: Transpose values. :keyword expand: One of 'table', 'down', 'right'. :keyword chunksize: 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. :keyword err_to_str: If True, will include cell errors such as #N/A as strings. By default, they will be converted to None. New in version 0.28.0.

For converter-specific options, see converters.

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

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

参数:

• paste (str | 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.

• operation (str | None) -- 可以取下列值： "add", "divide", "multiply", "subtract"。

• skip_blanks (bool) -- 设为 True 时忽略空白单元格

• transpose (bool) -- 设为 True 时对行列转置

property raw_value: Any

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)

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

参数:

• row_size (int | None) -- 新的区域的行数(如果为 None , 区域保持原来的行数不变)。

• column_size (int | None) -- 新的区域的列数(如果为 None , 区域保持原来的列数不变)。

在 0.3.0 版本加入.

property row: int

返回区域第一行的行号。只读。

在 0.3.5 版本加入.

property row_height: float | None

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

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

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

在 0.4.0 版本加入.

property rows: RangeRows

Returns a RangeRows object that represents the rows in the specified range.

在 0.9.0 版本加入.

select()

选中区域。只能在活动的工作簿中选。

在 0.9.0 版本加入.

property shape: tuple[int, int]

表示区域范围的元组。

在 0.3.0 版本加入.

property sheet: Sheet

返回区域所属的工作表对象。

在 0.9.0 版本加入.

property size: int

区域内的单元格数量。

在 0.3.0 版本加入.

property table: Table | None

Returns a Table object if the range is part of one, otherwise None.

在 0.21.0 版本加入.

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

Exports the range as PDF.

参数:

• path (str | PathLike[str] | 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.

• layout (str | PathLike[str] | 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).

• show (bool | None) -- Once created, open the PDF file with the default application.

• quality (str) -- Quality of the PDF file. Can either be 'standard' or 'minimum'.

在 0.26.2 版本加入.

to_png(path=None)

Exports the range as PNG picture.

参数:

path (str | PathLike[str] | 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.

在 0.24.8 版本加入.

property top: float

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

在 0.6.0 版本加入.

ungroup(by=None)

Ungroup rows or columns

参数:

by (str | None) -- "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: Any

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.

property width: float

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

在 0.4.0 版本加入.

property wrap_text: bool | None

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.

在 0.23.2 版本加入.