Book¶

class Book(fullname=None, update_links=None, read_only=None, format=None, password=None, write_res_password=None, ignore_read_only_recommended=None, origin=None, delimiter=None, editable=None, notify=None, converter=None, add_to_mru=None, local=None, corrupt_load=None, impl=None, json=None, mode=None, engine=None, **kwargs)¶

A book object is a member of the books collection:

>>> import xlwings as xw
>>> xw.books[0]
<Book [Book1]>

The easiest way to connect to a book is offered by xw.Book: it looks for the book in all app instances and returns an error, should the same book be open in multiple instances. To connect to a book in the active app instance, use xw.books and to refer to a specific app, use:

>>> app = xw.App()  # or xw.apps[10559] (get the PIDs via xw.apps.keys())
>>> app.books['Book1']

	xw.Book	xw.books
新建工作簿	`xw.Book()`	`xw.books.add()`
未保存的工作簿	`xw.Book('Book1')`	`xw.books['Book1']`
带有全路径名的工作簿	`xw.Book(r'C:/path/to/file.xlsx')`	`xw.books.open(r'C:/path/to/file.xlsx')`

参数:

fullname (str | PathLike[str] | None) -- 已经存在的工作簿的文件名或全路径名(包括后缀 xlsx , xlsm 等)或者还未保存的工作簿的名字。没有全路径时，在当前工作目录中寻找该文件。
update_links (bool | None) -- 如果这个参数被省略，会提示用户确定更新链接的方式。
read_only (bool | None) -- 值为 True 时以只读方式打开工作簿
format (str | None) -- 如果打开的是文本文件，本参数指明分隔符。
password (str | None) -- 用于打开工作簿的密码。
write_res_password (str | None) -- 用于向工作簿写入数据时的密码。
ignore_read_only_recommended (bool | None) -- 设置为 True 时会关闭推荐只读的提示
origin (int | None) -- For text files only. Specifies where it originated. Use Platform constants.
delimiter (str | None) -- 如果参数format的值是6，这个参数指明分隔符。
editable (bool | None) -- 这个选择只用于老的Excel4.0的加载项。
notify (bool | None) -- 当一个文件暂时无法在读写模式中打开，在文件可以打开的时候提示用户。
converter (int | None) -- 打开文件时，首先尝试使用的文件转换器对应的索引
add_to_mru (bool | None) -- 把这个工作簿加到最近增加的工作簿列表中。
local (bool | None) -- If True, saves files against the language of Excel, otherwise against the language of VBA. Not supported on macOS.
corrupt_load (int | None) -- 可以是xlNormalLoad、xlRepairFile或xlExtractData中的一个，在macOS上不支持此参数。
json (dict[str, Any] | None) -- A JSON object as delivered by the MS Office Scripts or Google Apps Script xlwings module but in a deserialized form, i.e., as dictionary. New in version 0.26.0.
mode (str | None) -- Either "i" (interactive (default)) or "r" (read). In interactive mode, xlwings opens the workbook in Excel, i.e., Excel needs to be installed. In read mode, xlwings reads from the file directly, without requiring Excel to be installed. Read mode requires xlwings PRO. New in version 0.28.0.

activate(steal_focus=False)¶

激活工作簿

参数:: steal_focus (bool) -- 如果是True, 把窗口显示到最上层，并且把焦点从Python切换到Excel。

property api: Any¶: Returns the native object (pywin32 or appscript obj) of the engine being used.

在 0.9.0 版本加入.

property app: App¶: 返回创建工作簿的app对象。

在 0.9.0 版本加入.

classmethod caller()¶

References the calling book when the Python function is called from Excel via RunPython. Pack it into the function being called from Excel, e.g.:

import xlwings as xw

 def my_macro():
    wb = xw.Book.caller()
    wb.sheets[0].range('A1').value = 1

To be able to easily invoke such code from Python for debugging, use xw.Book.set_mock_caller().

在 0.3.0 版本加入.

close()¶

放弃保存直接关闭工作簿。

在 0.1.1 版本加入.

async flush()¶

Flushes all pending actions to Excel and the Output pane.

Requires xlwings Lite.

在 0.35.0 版本加入.

property fullname: str¶: 返回对象名称字符串，包括在磁盘上的路径。是只读字符串。

async get_selection()¶

Returns the selected cells as Range, fetched live from Excel.

Requires xlwings Lite.

在 0.35.0 版本加入.

json()¶

Returns a JSON serializable object as expected by the MS Office Scripts or Google Apps Script xlwings module. Only available with book objects that have been instantiated via xw.Book(json=...).

在 0.26.0 版本加入.

async load()¶

Loads the book's current data from Excel on demand.

Requires xlwings Lite.

macro(name)¶

在Excel VBA中运行一个过程或者函数。

参数:: name (str) -- 'Module1.MyMacro' or 'MyMacro'

示例

Function MySum(x, y)
    MySum = x + y
End Function

可以这样调用:

>>> import xlwings as xw
>>> wb = xw.books.active
>>> my_sum = wb.macro('MySum')
>>> my_sum(1, 2)
3

See also: App.macro

在 0.7.1 版本加入.

property name: str¶: 返回工作簿名称字符串。

property names: Names¶: 返回一个指定工作簿中的定义过的所有命名区域的集合，包括那些和特定工作表有关的命名区域。

在 0.9.0 版本发生变更.

render_template(**data)¶

This method requires xlwings PRO.

Replaces all Jinja variables (e.g {{ myvar }}) in the book with the keyword argument of the same name.

在 0.25.0 版本加入.

参数:: data (Any) -- All key/value pairs that are used in the template.

示例

>>> import xlwings as xw
>>> book = xw.Book()
>>> book.sheets[0]['A1:A2'].value = '{{ myvar }}'
>>> book.render_template(myvar='test')

save(path=None, password=None)¶

Saves the Workbook. If a path is provided, this works like SaveAs() in Excel. If no path is specified and if the file hasn't been saved previously, it's saved in the current working directory with the current filename. Existing files are overwritten without prompting. To change the file type, provide the appropriate extension, e.g. to save myfile.xlsx in the xlsb format, provide myfile.xlsb as path.

参数:

path (str | PathLike[str] | None) -- Path where you want to save the Book.
password (str | None) -- Protection password with max. 15 characters New in version 0.25.1.

示例

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.save()
>>> wb.save(r'C:\path\to\new_file_name.xlsx')

在 0.3.1 版本加入.

property selection: Range | None¶: 把选中的单元格作为区域返回。

在 0.9.0 版本加入.

set_mock_caller()¶

Sets the Excel file which is used to mock xw.Book.caller() when the code is called from Python and not from Excel via RunPython.

示例

# This code runs unchanged from Excel via RunPython and from Python directly
import os
import xlwings as xw

def my_macro():
sht = xw.Book.caller().sheets[0]
sht.range('A1').value = 'Hello xlwings!'

if __name__ == '__main__':
xw.Book('file.xlsm').set_mock_caller()
my_macro()

在 0.3.1 版本加入.

property sheet_names: list[str]¶

返回:: List of sheet names in order of appearance.

在 0.28.1 版本加入.

property sheets: Sheets¶: 返回工作簿中所有工作表的集合。

在 0.9.0 版本加入.

async sync()¶

自 0.35.0 版本弃用: Use flush instead.

to_pdf(path=None, include=None, exclude=None, layout=None, exclude_start_string='#', show=False, quality='standard')¶

Exports the whole Excel workbook or a subset of the sheets to a PDF file. If you want to print hidden sheets, you will need to list them explicitely under include.

参数:

path (str | PathLike[str] | None) -- Path to the PDF file, defaults to the same name as the workbook, in the same directory. For unsaved workbooks, it defaults to the current working directory instead.
include (int | str | list[int | str] | None) -- Which sheets to include: provide a selection of sheets in the form of sheet indices (1-based like in Excel) or sheet names. Can be an int/str for a single sheet or a list of int/str for multiple sheets.
exclude (int | str | list[int | str] | None) -- Which sheets to exclude: provide a selection of sheets in the form of sheet indices (1-based like in Excel) or sheet names. Can be an int/str for a single sheet or a list of int/str for multiple sheets.
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). New in version 0.24.3.
exclude_start_string (str) -- Sheet names that start with this character/string will not be printed. New in version 0.24.4.
show (bool) -- Once created, open the PDF file with the default application. New in version 0.24.6.
quality (str) -- Quality of the PDF file. Can either be 'standard' or 'minimum'. New in version 0.26.2.

示例

>>> wb = xw.Book()
>>> wb.sheets[0]['A1'].value = 'PDF'
>>> wb.to_pdf()