插件与设置

_images/ribbon.png

xlwings 插件是能够使用Run main按钮的首选方式，RunPython或UDFs。请注意，如果您只想通过运行 Python 脚本来操作 Excel，则不需要插件。

注意

插件的选项卡与 Windows 上的 Excel >= 2007 和 macOS 上的 >= 2016 兼容。在 macOS 上，所有与 UDF 相关的功能均不可用。

注意

插件受密码保护，密码为xlwings。为了调试或添加新扩展，您需要取消保护。

运行主程序

在版本 0.16.0 中新增。

The Run main按钮是运行您的 Python 代码的最简单方法：它会运行一个名为main的函数，该函数位于与您的工作簿同名的 Python 模块中。这使您可以将工作簿保存为xlsx而无需启用宏。命令xlwings quickstart将创建一个可以自动与Run按钮配合使用的工作簿。

安装

若要安装插件，请使用命令行客户端：

xlwings addin install

技术上讲，这会将插件从 Python 的安装目录复制到 Excel 的XLSTART文件夹中。然后，在工作簿中使用RunPython或UDFs功能时，您需要在 VBA 编辑器中引用xlwings，请参阅截图（Windows:Tools > References...，Mac: 它位于 VBA 编辑器左下角）。请注意，当您通过xlwings quickstart创建工作簿时，引用应该已经设置。

_images/vba_reference.png

用户设置

当您首次安装插件时，它会自动配置，因此quickstart项目应能直接使用。对于微调，以下是可用的设置：

  • Interpreter：这是 Python 解释器的路径。这也适用于 Mac 上的虚拟或 conda 环境。如果您在 Windows 上使用 conda 环境，则留空此字段并改用下方的Conda Path和Conda Env。示例："C:\Python39\pythonw.exe"或"/usr/local/bin/python3.9"。注意，在设置中，这被存储为Interpreter_Win或Interpreter_Mac，具体见下文！

  • PYTHONPATH：如果未找到代码的源文件，请在此处添加其目录的路径。

  • Conda Path：如果您在 Windows 上使用 Anaconda 或 Miniconda，请在此处输入您的安装路径，例如C:\Users\Username\Miniconda3或%USERPROFILE%\Anaconda。注意，您需要至少 conda 4.6！您还需要设置Conda Env，详见下一点。

  • Conda Env：如果您在 Windows 上使用 Anaconda 或 Miniconda，请在此处输入您的 conda 环境名称，例如base表示基础安装或myenv表示名为myenv.

  • UDF Modules的 conda 环境：导入 UDF 的 Python 模块名称（不带 .py 扩展名）。用“;”分隔多个模块。示例：UDF_MODULES = "common_udfs;myproject"默认情况下，导入与 Excel 电子表格位于同一目录下的文件，文件名与电子表格相同，但以.py.

  • Debug UDFs结尾：如果要在调试时手动运行 xlwings COM 服务器，请勾选此框，详见调试.

  • RunPython: Use UDF Server：为 RunPython 使用与 UDF 相同的 COM 服务器。这会更快，因为每次调用后解释器不会关闭。

  • Restart UDF Server：这将重启 UDF 服务器/Python 解释器。

  • Show Console：如果希望命令提示符弹出，请在选项卡中勾选此框或将配置设置为TRUE。目前这仅在 Windows 上有效。

  • ADD_WORKBOOK_TO_PYTHONPATH：取消勾选此框以避免自动将工作簿目录添加到 PYTHONPATH。如果遇到 OneDrive/SharePoint 问题，取消此框并通过 PYTHONPATH 设置手动提供源文件路径。

Anaconda/Miniconda

如果您在 Windows 上使用 Anaconda 或 Miniconda，则需要设置您的Conda Path和Conda Env设置，否则在使用NumPy等时会出现错误。反过来，留空Interpreter。

使用环境变量

通过环境变量，您可以设置动态路径，例如指向解释器或PYTHONPATH:

  • 在 Windows 上，您可以像这样使用所有环境变量：%USERPROFILE%\Anaconda.

  • 在 macOS 上，支持以下特殊变量：$HOME, $APPLICATIONS, $DOCUMENTS, $DESKTOP.

配置层次结构检查 xlwings 的配置

xlwings 按照以下顺序和位置查找设置：

  • 工作簿配置

    首先，xlwings 查找一个名为xlwings.conf的工作表。这是为部署配置工作簿的推荐方法，因为您无需处理额外的配置文件。运行 quickstart 命令时，它会在一个名为_xlwings.conf的工作表上创建示例配置：删除名称中的前导下划线以激活它。如果不打算使用，可以随时删除工作表。

  • 目录配置

    接下来，xlwings 查找与您的 Excel 工作簿位于同一目录下的名为xlwings.conf的文件。

  • 用户配置

    最后，xlwings 查找用户主目录中的名为xlwings.conf的顶部检查.xlwings的文件。通常，您不会直接编辑此文件——而是每当更改设置时由插件创建和编辑。

您将在下面找到每种配置类型的更多详细信息。

来源：章节“Config Hierarchy”摘自 Felix Zumstein (O’Reilly) 的《Python for Excel》，版权 2021 Zoomer Analytics LLC，978-1-492-08100-5。

用户配置：Ribbon/配置文件

xlwings 功能区中的设置存储在一个也可以外部操作的配置文件中。位置为

  • Windows:.xlwings\xlwings.conf在您的用户目录中，通常是C:\Users\<username>

  • macOS:~/Library/Containers/com.microsoft.Excel/Data/xlwings.conf

格式如下（目前键必须全部大写）——注意特定于操作系统的解释器设置！

"INTERPRETER_WIN","C:\path\to\python.exe"
"INTERPRETER_MAC","/path/to/python"
"PYTHONPATH",""
"ADD_WORKBOOK_TO_PYTHONPATH",""
"CONDA PATH",""
"CONDA ENV",""
"UDF MODULES",""
"DEBUG UDFS",""
"USE UDF SERVER",""
"SHOW CONSOLE",""
"ONEDRIVE_CONSUMER_WIN",""
"ONEDRIVE_CONSUMER_WIN",""
"ONEDRIVE_COMMERCIAL_WIN",""
"ONEDRIVE_COMMERCIAL_MAC",""
"SHAREPOINT_WIN",""
"SHAREPOINT_MAC",""

注意

The ONEDRIVE_WIN/_MAC设置必须直接在文件中编辑，目前无法通过功能区进行编辑。通常，只有当您在 macOS 上，或者 Windows 上的环境变量设置不正确，或者您有私人和企业位置且不想使用默认位置时，才需要此设置。ONEDRIVE_WIN/_MAC必须指向本地 OneDrive 文件夹的根目录。

目录配置：配置文件

通过在工作簿目录中创建一个文件，可以为一个或多个工作簿覆盖Ribbon/配置文件的全局设置。xlwings.conf在工作簿目录中创建一个文件。

注意

如果您的工作簿存储在SharePoint或OneDrive上，则不支持工作簿目录配置文件。

工作簿配置：xlwings.conf工作表

工作簿特定的设置将覆盖全局（Ribbon）和工作簿目录配置文件设置：通过在名为的工作表中列出配置键/值对来设置工作簿特定的设置。xlwings.conf当您使用创建一个新项目时。xlwings quickstart，它已经包含这样一个工作表，但您需要将其名称从重命名。_xlwings.conf更改为。xlwings.conf才能使其生效。

_images/workbook_config.png

替代方案：独立VBA模块

有时，可能需要在无需先安装加载项的情况下运行xlwings代码。为此，您需要在创建新项目时使用选项。standalone这将把加载项的内容添加为单个VBA模块，因此您不再需要引用该加载项。xlwings quickstart myproject --standalone.

它还将包括因为这是macOS所必需的。Dictionary.cls它仍然会从您的读取设置，除非您使用名为的工作表覆盖它们。xlwings.conf if you don’t override them by using a sheet with the name xlwings.conf.