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)

An app object is a member of the apps collection:

>>> 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>
参数:

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

  • spec (str | None) -- Mac-only, use the full path to the Excel application, e.g., /Applications/Microsoft Office 2011/Microsoft Excel or /Applications/Microsoft Excel. On Windows, if you want to change the version of Excel that xlwings talks to, go to Control Panel > Programs and Features and Repair the Office version that you want as default.

备注

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

activate(steal_focus=False)

激活让一个Excel应用程序

参数:

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

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

参数:

  • prompt (str) -- The message to be displayed.

  • title (str | None) -- The title of the alert.

  • buttons (str) -- Can be either "ok", "ok_cancel", "yes_no", or "yes_no_cancel".

  • mode (str | None) -- Can be "info" or "critical". Not supported by Google Sheets.

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

返回:

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

返回类型:

str | None

在 0.27.13 版本加入.

property api: Any

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

在 0.9.0 版本加入.

property books: Books

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

在 0.9.0 版本加入.

calculate()

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

在 0.3.6 版本加入.

property calculation: str

Returns or sets a calculation value that represents the calculation mode. Modes: 'manual', 'automatic', 'semiautomatic'

示例

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

在 0.9.0 版本发生变更.

property cut_copy_mode: str | None

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.

在 0.24.0 版本加入.

property display_alerts: bool

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

在 0.9.0 版本加入.

property enable_events: bool

True if events are enabled. Read/write boolean.

在 0.24.4 版本加入.

async get_selection()

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

Requires xlwings Lite.

在 0.35.0 版本加入.

property hwnd: int | None

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

在 0.9.0 版本加入.

property interactive: bool

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.

在 0.24.4 版本加入.

kill()

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

在 0.9.0 版本加入.

macro(name)

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

参数:

name (str) -- e.g., 'Module1.MyMacro' or 'MyMacro'

示例

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

See also: Book.macro

在 0.9.0 版本加入.

property path: str

Returns the path to where the App is installed.

在 0.28.4 版本加入.

property pid: int

返回app的PID。

在 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

在 0.24.4 版本加入.

quit()

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

在 0.3.3 版本加入.

range(cell1, cell2=None)

Range object from the active sheet of the active book, see Range.

在 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 | PathLike[str] | None) -- Path to your Excel template, e.g. r'C:\Path\to\my_template.xlsx'

  • output (str | PathLike[str] | None) -- Path to your Report, e.g. r'C:\Path\to\my_report.xlsx'

  • book_settings (dict[str, Any] | None) -- A dictionary of xlwings.Book parameters, for details see: xlwings.Book. For example: book_settings={'update_links': False}.

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

在 0.24.4 版本加入.

property screen_updating: bool

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

在 0.3.3 版本加入.

property selection: Range | None

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

在 0.9.0 版本加入.

property startup_path: str

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

在 0.19.4 版本加入.

property status_bar: str | bool

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

在 0.20.0 版本加入.

property version: VersionNumber

返回Excel版本号对象。

示例

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

在 0.9.0 版本发生变更.

property visible: bool

Gets or sets the visibility of Excel to True or False.

在 0.3.3 版本加入.