App

class App(visible=None, spec=None, add_book=True, impl=None)

An app corresponds to an Excel instance and should normally be used as context manager to make sure that everything is properly cleaned up again and to prevent zombie processes. New Excel instances can be fired up like so:

import xlwings as xw

with xw.App() as app:
    print(app.books)

一个app对象是apps集合中的一员:

>>> xw.apps
Apps([<Excel App 1668>, <Excel App 1644>])
>>> xw.apps[1668]  # get the available PIDs via xw.apps.keys()
<Excel App 1668>
>>> xw.apps.active
<Excel App 1668>

参数

visiblebool, default None

返回或设置一个决定app是否可见的布尔值。缺省情况下保持状态不变，或者对象还不存在的情况下设置visible=True。

specstr, default None

仅用于Mac系统, 使用Excel程序的全路径，例如： /Applications/Microsoft Office 2011/Microsoft Excel 或 /Applications/Microsoft Excel

在Windows系统中, 如果想改变xlwings调用的Excel版本，到 控制面板 > 程序和功能 把Office 修复 到需要用的那个版本。

备注

在Mac系统里, 虽然xlwings允许多个Excel同时运行，但这不是Mac版的Excel官方支持的功能：不像在Windows系统里，当文件已经在另外一个Excel实例中打开的时候，不会要求你打开一个只读版本。就是说你得自己小心注意，避免同样的文件被不同的Excel实例重写。

activate(steal_focus=False)

激活让一个Excel应用程序

参数

steal_focusbool类型, 缺省值为False

如果为True, 让Excel程序变为最前台的应用，并且把焦点从Python切换到Excel。

Added in version 0.9.0.

alert(prompt, title=None, buttons='ok', mode=None, callback=None)

This corresponds to MsgBox in VBA, shows an alert/message box and returns the value of the pressed button. For xlwings Server, instead of returning a value, the function accepts the name of a callback to which it will supply the value of the pressed button.

参数

promptstr, default None

The message to be displayed.

titlestr, default None

The title of the alert.

buttonsstr, default "ok"

Can be either "ok", "ok_cancel", "yes_no", or "yes_no_cancel".

modestr, default None

Can be "info" or "critical". Not supported by Google Sheets.

callbackstr, default None

Only used by xlwings Server: you can provide the name of a function that will be called with the value of the pressed button as argument. The function has to exist on the client side, i.e., in VBA or JavaScript.

返回

button_value: str or None

Returns None when used with xlwings Server, otherwise the value of the pressed button in lowercase: "ok", "cancel", "yes", "no".

Added in version 0.27.13.

property api

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

Added in version 0.9.0.

property books

当前打开的所有工作簿对象的集合。

Added in version 0.9.0.

calculate()

把所以打开的工作簿中的公式重新计算一遍。

Added in version 0.3.6.

property calculation

返回或设置calculation的值，这个值表示了工作簿的计算模式，有: 'manual'(手动) , 'automatic'(自动) , 'semiautomatic'(半自动)

示例

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.app.calculation = 'manual'

在 0.9.0 版本发生变更.

property cut_copy_mode

Gets or sets the status of the cut or copy mode. Accepts False for setting and returns None, copy or cut when getting the status.

Added in version 0.24.0.

property display_alerts

缺省值为True。通过设置为False可以关闭正在运行的代码的报警信息；如果报警信息是需要响应的，Excel会选择默认的响应方式。

Added in version 0.9.0.

property enable_events

True if events are enabled. Read/write boolean.

Added in version 0.24.4.

property hwnd

返回Window句柄(仅用于Windows)。

Added in version 0.9.0.

property interactive

True if Excel is in interactive mode. If you set this property to False, Excel blocks all input from the keyboard and mouse (except input to dialog boxes that are displayed by your code). Read/write Boolean. NOTE: Not supported on macOS.

Added in version 0.24.4.

kill()

通过杀掉进程强制Excel app退出。

Added in version 0.9.0.

macro(name)

运行一个不属于特定工作簿但是属于加载项的Excel VBA的过程(sub)或函数。

Arguments

nameName of Sub or Function with or without module name,

e.g., 'Module1.MyMacro' or 'MyMacro'

示例

下面这个VBA函数:

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

可以这样调用:

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

Types are supported too:

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

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

However typed arrays are not supported. So the following won’t work

Function MySum(arr() as integer)
    ' code here
End Function

参考: Book.macro()

Added in version 0.9.0.

property path

Returns the path to where the App is installed.

Added in version 0.28.4.

property pid

返回app的PID。

Added in version 0.9.0.

properties(**kwargs)

Context manager that allows you to easily change the app’s properties temporarily. Once the code leaves the with block, the properties are changed back to their previous state. Note: Must be used as context manager or else will have no effect. Also, you can only use app properties that you can both read and write.

示例

import xlwings as xw
app = App()

# Sets app.display_alerts = False
with app.properties(display_alerts=False):
    # do stuff

# Sets app.calculation = 'manual' and app.enable_events = True
with app.properties(calculation='manual', enable_events=True):
    # do stuff

# Makes sure the status bar is reset even if an error happens in the with block
with app.properties(status_bar='Calculating...'):
    # do stuff

Added in version 0.24.4.

quit()

退出应用，不保存任何工作簿。

Added in version 0.3.3.

range(cell1, cell2=None)

活动工作簿中活动工作表的区域对象, 参考 Range() 。

Added in version 0.9.0.

render_template(template=None, output=None, book_settings=None, **data)

This function requires xlwings PRO.

This is a convenience wrapper around mysheet.render_template

Writes the values of all key word arguments to the output file according to the template and the variables contained in there (Jinja variable syntax). Following variable types are supported:

strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, pictures and Matplotlib/Plotly figures.

参数

template: str or path-like object

Path to your Excel template, e.g. r'C:\Path\to\my_template.xlsx'

output: str or path-like object

Path to your Report, e.g. r'C:\Path\to\my_report.xlsx'

book_settings: dict, default None

A dictionary of xlwings.Book parameters, for details see: xlwings.Book. For example: book_settings={'update_links': False}.

data: kwargs

All key/value pairs that are used in the template.

返回

wb: xlwings Book

Added in version 0.24.4.

property screen_updating

关掉屏幕刷新(设置为 False )来加速脚本运行。虽然看不到脚本的运行情况，但是会让它运行更快。脚本运行完毕之后，记住把screen_updating属性值改回 True。

Added in version 0.3.3.

property selection

把选中的单元格作为区域返回。

Added in version 0.9.0.

property startup_path

Returns the path to XLSTART which is where the xlwings add-in gets copied to by doing xlwings addin install.

Added in version 0.19.4.

property status_bar

Gets or sets the value of the status bar. Returns False if Excel has control of it.

Added in version 0.20.0.

property version

返回Excel版本号对象。

示例

>>> import xlwings as xw
>>> xw.App().version
VersionNumber('15.24')
>>> xw.apps[10559].version.major
15

在 0.9.0 版本发生变更.

property visible

取得或者设置Excel的visible属性值，可以为 True 或 False 。

Added in version 0.3.3.