Range¶

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

返回一个表示单元格或单元格范围的 Range 对象。

参数¶

cell1str 或 tuple 或 Range: 左上角范围的名称，使用 A1 表示法或索引元组或名称或 xw.Range 对象。也可以使用范围运算符（冒号）指定范围，例如 ‘A1:B2’。
cell2str 或 tuple 或 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)¶

向指定的 Range（单个单元格）添加超链接。

参数¶

address字符串: 超链接的地址。
text_to_display字符串，默认值为 None: 超链接要显示的文本。默认为超链接地址。
screen_tip: str，默认值为 None: 当鼠标指针悬停在超链接上时要显示的屏幕提示。默认设置为 ‘<address> - 单击一次即可跳转。点击并按住以选择此单元格。’

添加于版本 0.3.0。

属性 address¶: 返回一个表示范围引用的字符串值。使用get_address()来提供参数。

在版本 0.9.0 中添加。

adjust_indent(amount)¶

调整 Range 中的缩进。

参数¶

amount整数: 缩进调整的空格数。可以是正数或负数。

属性 api¶: 返回所使用引擎的原生对象 (pywin32或appscriptobj) 使用的引擎的成员。

在版本 0.9.0 中添加。

autofill(目标位置, type_='fill_default')¶

自动填充目标范围。注意目标范围必须包含源范围。

参数¶

目标位置Range: 源范围。
type_字符串，默认值"fill_default": 以下字符串之一："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()¶

自动调整范围内所有单元格的宽度和高度。

若要仅自动调整列宽，请使用myrange.columns.autofit()
若要仅自动调整行高，请使用myrange.rows.autofit()

在版本 0.9.0 中更改。

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

clear_contents()¶: 清除 Range 的内容但保留格式。

clear_formats()¶: 清除 Range 的格式但保留内容。

添加于版本 0.26.2。

属性颜色¶

获取和设置指定 Range 的背景色。

若要设置颜色，可以使用 RGB 元组(0, 0, 0)或十六进制字符串如#efefef或 Excel 颜色常量。若要删除背景色，请将颜色设置为None，请参阅示例。

返回值¶

RGB : 元组

示例¶

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

属性 column¶: 返回指定范围中第一列的编号。只读。

返回值¶

整数

添加于版本 0.3.5。

属性 column_width¶

获取或设置 Range 的宽度（以字符为单位）。一单位列宽等于 Normal 样式下一个字符的宽度。对于比例字体，使用字符 0（零）的宽度。

如果 Range 中的所有列具有相同的宽度，则返回该宽度。如果列具有不同的宽度，则返回 None。

column_width 必须在范围内：0 <= column_width <= 255

注意：如果 Range 超出工作表的使用范围，并且 Range 中的列具有不同的宽度，则返回第一列的宽度。

返回值¶

浮点数

添加于版本 0.4.0。

属性列¶: 返回一个表示指定范围中行的对象。RangeColumns对象，表示指定范围中的列。

在版本 0.9.0 中添加。

copy(目标位置=None)¶

将范围复制到目标范围或剪贴板。

参数¶

目标位置xlwings.Range: 要复制到的目标 xlwings 范围。如果省略，则将范围复制到剪贴板。

返回值¶

None

copy_from(source_range, copy_type='all', 跳过空白单元格=False, 转置=False)¶

copy 的较新变体，取代了 copy/paste。

参数¶

source_range : xlwings.Range

copy_type字符串，默认为“all”: “all”、“formats”、“formulas”、“link”、“values”之一

skip_blanks : 布尔值，默认为 False

transpose : 布尔值，默认为 False

copy_picture(appearance='screen', 格式='picture')¶

将范围复制到剪贴板作为图片。

参数¶

appearance字符串，默认为‘screen’: ‘screen’ 或 ‘printer’。
格式字符串，默认为‘picture’: ‘picture’ 或 ‘bitmap’。

添加于版本 0.24.8。

属性计数¶: 返回单元格的数量。

属性 current_region¶: 此属性返回一个 Range 对象，代表由（但不包括）任何组合的空白行和空白列或工作表边缘限定的范围。它对应于 Mac 上的Ctrl-*在Windows上和Shift-Ctrl-Space。

返回值¶

范围对象

删除(移动=None)¶

删除单元格或单元格范围。

参数¶

移动字符串，默认值为 None: 使用left或up。如果省略，Excel 将根据范围的形状进行决定。

返回值¶

None

end(direction)¶

返回一个表示源范围所在区域末端单元格的 Range 对象。相当于按下 Ctrl+向上、Ctrl+向下、Ctrl+向左或 Ctrl+向右。

参数¶

direction : ‘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>

在版本 0.9.0 中添加。

扩展(模式='table')¶

根据提供的模式扩展范围。忽略空的左上单元格（与Range.end())。

参数¶

模式字符串，默认为 ‘table’: 之一'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

在版本 0.9.0 中添加。

属性 formula¶: 获取或设置给定 Range 的公式。

属性 formula2¶: 获取或设置给定 Range 的 formula2。

属性 formula_array¶: 获取或设置给定 Range 的数组公式。

添加于版本 0.7.1。

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

返回指定格式的范围地址。address如果不需要更改任何默认值，可以使用它。

参数¶

row_absolute布尔值，默认为True: 设置为 True 以将引用的行部分作为绝对引用返回。
column_absolute布尔值，默认为True: 设置为 True 以将引用的列部分作为绝对引用返回。
include_sheetname布尔值，默认为False: 设置为 True 以在地址中包含工作表名称。如果 external=True，则忽略。
external布尔值，默认为False: 设置为 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。

group(按=None)¶

分组行或列。

参数¶

按字符串，可选: “列”或“行”。如果范围定义为‘1:3’或‘A:C’，则自动确定。

属性 has_array¶: True如果范围是遗留 CSE 数组公式的一部分，则返回 True；False否则返回 False。

属性高度¶: 返回 Range 的高度（以磅为单位）。只读。

返回值¶

浮点数

添加于版本 0.4.0。

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

添加于版本 0.3.0。

插入(移动, 复制原点='从左侧或上方格式化')¶

在表格中插入一个单元格或单元格范围。

参数¶

移动字符串: 使用right或down.
复制原点字符串，默认为 format_from_left_or_above: 使用format_from_left_or_above或format_from_right_or_below请注意，copy_origin 仅在 Windows 上受支持。

返回值¶

None

于版本 0.30.3 中更改：shift现在是必需参数。

属性最后单元格¶

返回指定范围的右下角单元格。只读。

返回值¶

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。

属性左侧¶: 返回从 A 列左边缘到指定范围左边缘的距离（以磅为单位）。只读。

返回值¶

浮点数

添加于版本 0.6.0。

合并(横向=False)¶

根据指定的 Range 对象创建一个合并单元格。

参数¶

横向布尔值，默认为False: 如果将指定范围中的每一行的单元格作为单独的合并单元格进行合并，则为 True。

属性合并区域¶: 返回一个表示包含指定单元格的合并范围的 Range 对象。如果指定的单元格不在合并范围内，则此属性返回指定的单元格。

属性合并单元格¶: 返回值True如果范围包含合并单元格，则为 True；否则为 False。False

属性名称¶: 设置或获取一个范围的名称。

添加于版本 0.4.0。

属性注释¶: 返回一个 Note 对象。在引入线程化评论之前，Note 被称为 Comment。

添加于版本 0.24.2。

属性数字格式¶

获取和设置一个 Range 的数字格式。

示例¶

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

偏移量(行偏移量=0, 列偏移量=0)¶: 返回一个表示相对于指定范围偏移的 Range 对象。

返回值¶

Range 对象 : 范围

添加于版本 0.3.0。

options(convert=None, **options)¶

允许你设置转换器及其选项。转换器定义了 Excel 范围及其值在读取和写入操作期间如何转换。如果没有指定明确的转换器，则应用基础转换器，详见转换器和选项.

参数¶

convert对象，默认为 None: 转换器，例如dict, np.array, pd.DataFrame, pd.Series默认为默认转换器

关键字参数¶

ndim整数，默认为 None: 维度数量
数字类型，默认为 None: 数字类型，例如int
日期类型，默认为 None: 例如datetime.date默认为datetime.datetime
空值对象，默认为 None: 空白单元格的转换
转置布尔值，默认为 False: 转置值
扩展字符串，默认值为 None: 之一'table', 'down', 'right'
分块大小整数: 使用分块大小，例如10000在读取或写入大量数据时防止超时或内存问题。适用于所有格式，包括 DataFrame、NumPy 数组和列表的列表。
错误转字符串布尔值，默认为 False: 如果True，将包括单元格错误如#N/A作为字符串。默认情况下，它们将被转换为None.

在版本 0.28.0 中添加。

=> 对于特定于转换器的选项，请参见转换器和选项.

返回值¶

范围对象

粘贴(粘贴=None, 操作=None, 跳过空白单元格=False, 转置=False)¶

将剪贴板中的范围粘贴到指定范围中。

参数¶

粘贴字符串，默认值为 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.
操作字符串，默认值为 None: 之一“add”、“divide”、“multiply”、“subtract”。
跳过空白单元格布尔值，默认为False: 设置为True跳过空白单元格
转置布尔值，默认为False: 设置为True转置行和列。

返回值¶

None

属性原始值¶: 获取和设置直接由/接受所使用引擎传递的值（xlwings 不进行任何数据清理/转换）。如果速度是一个问题，这可能会有所帮助，但自然会是引擎特定的，即可能去除跨平台兼容性。pywin32或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.

调整大小(行高=None, 列宽=None)¶

调整指定范围的大小

参数¶

行数：大于 0 的整数: 新范围中的行数（如果为 None，则范围中的行数不变）。
列数：大于 0 的整数: 新范围中的列数（如果为 None，则范围中的列数不变）。

返回值¶

范围对象：范围

添加于版本 0.3.0。

属性行¶: 返回指定范围中第一行的编号。只读。

返回值¶

整数

添加于版本 0.3.5。

属性行高¶

获取或设置范围的高度（以磅为单位）。如果范围中的所有行高度相同，则返回高度。如果范围中的行高度不同，则返回 None。

行高必须在范围内：0 <= 行高 <= 409.5

注意：如果范围超出工作表的已用范围，并且范围中的行高度不同，则返回第一行的高度。

返回值¶

浮点数

添加于版本 0.4.0。

属性行¶: 返回一个表示指定范围中行的对象。RangeRows object that represents the rows in the specified range.

在版本 0.9.0 中添加。

选择范围。仅在活动书中有效。()¶: Selects the range. Select only works on the active book.

在版本 0.9.0 中添加。

属性形状¶: 范围维度的元组。

添加于版本 0.3.0。

属性表格中设置部署密钥¶: 返回包含该范围的工作表对象。

在版本 0.9.0 中添加。

属性大小¶: 范围中的元素数量。

添加于版本 0.3.0。

属性表格¶: 如果范围属于某个表，则返回一个 Table 对象；否则返回 None。None.

添加于版本 0.21.0。

导出为 PDF(路径=None, 布局=None, 显示=None, 质量='标准')¶

导出范围为 PDF。

参数¶

路径字符串或路径类似对象，默认为 None

存储 pdf 的路径。如果 Excel 文件已保存，则默认为同一目录下的范围地址；否则为当前工作目录。

布局字符串或路径类似对象，默认为 None

此参数需要 xlwingsPRO.

用于打印报告的 PDF 文件路径。这是理想的选择页眉和页脚以及无边框打印图形/艺术品。PDF 文件要么需要只有一页（每页报告页面使用相同的布局），或者需要与报告相同的页数（每页报告页面打印在相应的布局 PDF 页面上）。

显示布尔值，默认为False

创建后，使用默认应用程序打开 PDF 文件。

质量字符串，默认值'standard'

PDF 文件的质量。可以是'standard'或'minimum'.

添加于版本 0.26.2。

导出为 PNG(路径=None)¶

导出范围为 PNG 图片。

参数¶

路径字符串或路径类似对象，默认为 None: 存储图片的路径。如果 Excel 文件已保存，则默认为同一目录下的范围名称；否则为当前工作目录。

添加于版本 0.24.8。

属性顶部¶: 返回从第 1 行顶端到指定范围顶端的距离（以磅为单位）。只读。

返回值¶

浮点数

添加于版本 0.6.0。

解组(按=None)¶

解组行或列

参数¶

按字符串，可选: “列”或“行”。如果范围定义为‘1:3’或‘A:C’，则自动确定。

取消合并()¶: 将合并区域拆分为单独的单元格。

属性值¶

获取和设置给定范围的值。请参阅xlwings.Range.options()了解如何设置选项，例如将其转换为 DataFrame 或如何设置分块大小。

返回值¶

对象返回的对象取决于所使用的转换器，: 请参阅xlwings.Range.options()

属性宽度¶: 返回范围的宽度（以磅为单位）。只读。

返回值¶

浮点数

添加于版本 0.4.0。

属性自动换行¶: 返回值True如果启用了 wrap_text 属性，则为 True；False如果未启用，则为 False。如果范围中的所有单元格值不一致，在 Windows 上返回None，在 macOS 上返回False.

添加于版本 0.23.2。