自定义插件

在版本0.22.0中添加。

自定义加载项在 Windows 和 macOS 上运行，是白标签的 xlwings 加载项，包含所有你的RunPython函数和 UDF（如常，UDF 仅在 Windows 上工作）。你可以构建带有或不带 Excel 功能区的加载项。

加载项的一个有用之处在于，UDF 和 RunPython 调用将在所有工作簿中开箱即用，而无需通过 VBA 编辑器添加任何引用。Tools > References...你还可以使用标准的xlsx文件而不是xlsm文件。本教程假设你熟悉 xlwings 及其配置的工作方式。

快速入门

首先，在命令行上运行以下命令（若要创建一个没有功能区的加载项，你会省略--ribbon标志）：

$ xlwings quickstart myproject --addin --ribbon

这将创建熟悉的 quickstart 文件夹，其中包含一个 Python 文件和一个 Excel 文件，但这次，Excel 文件是xlam格式。

  • 双击 Excel 加载项以在 Excel 中打开它

  • 添加一个新的空白工作簿（Ctrl+N在 Windows 上或Command+N在 macOS 上）

你应该会看到一个新的功能区选项卡叫做MyAddin如此：

_images/custom_ribbon_addin.png

加载项和 VBA 项目目前总是被称为myaddin，无论你在 quickstart 命令中选择了什么名称。我们将在本教程的最后看到如何更改它，但现在我们将沿用这个名称。

与 xlwings 加载项相比，自定义加载项提供了额外一层配置：加载项本身的配置表，这是配置具有静态配置的简单加载项的最简单方法。

让我们通过点击Alt+F11（Windows）或Option+F11（macOS）打开 VBA 编辑器。在我们的项目中，选择ThisWorkbook，然后更改属性IsAddin来自True更改为。False，参见下图：

_images/custom_addin_vba_properties.png

这将使表格_myaddin.conf可见（再次，我们将在本教程的最后看到如何更改myaddin的名称）：

  • 通过将其重命名为_myaddin.conf更改为。myaddin.conf

  • 激活该配置表Interpreter_Win/_Mac或Conda设置你的

设置（你可能想暂时从 xlwings 设置中复制这些设置）ThisWorkbook完成后，切换回 VBA 编辑器，再次选择IsAddin并将其更改回True在保存加载项之前。切换回 Excel 并点击Run按钮在My Addin功能区选项卡下，如果你正确配置了 Python 解释器，它将在活动工作簿的单元格Hello xlwings!中打印。A1 of the active workbook.

配置

若要更改功能区菜单或后台视图中的按钮和项目，请下载并安装Office RibbonX 编辑器。尽管它只适用于 Windows，但创建的功能区也将在 macOS 上工作。用它打开你的加载项，以便可以更改定义按钮等的 XML 代码。你可以在这里找到一个很好的教程。演示. The callback function for the demo Run按钮的回调函数位于 VBA 编辑器中的RibbonMyAddinVBA 模块中。

配置

要将你的 UDF 导入到自定义加载项中，请运行ImportPythonUDFsToAddin子过程接近xlwings模块的结尾（点击进入子过程并按F5）。记住，只有当你更改函数名、参数或装饰器时才需要这样做，所以你的最终用户不必处理这个问题。

如果你仅通过加载项部署 UDF，则可能不需要功能区菜单，并且可以在--ribbon标志。quickstart命令中省略

重命名你的加载项

如前所述，配置与使用 xlwings 时相同，因此可以通过在他们的工作簿中添加myaddin.conf表单让你的用户覆盖上述默认配置，或者可以使用用户主目录中的myaddin.conf文件。有关详细信息，请参阅插件与设置.

安装

如果你想永久安装你的加载项，可以使用 xlwings CLI：

$ xlwings addin install --file C:\path\to\your\myproject.xlam

然而，这意味着你需要调整PYTHONPATH以找到你的 Python 代码（或将你的 Python 代码移动到 Python 查找的某个地方——下面在部署部分有更多介绍）。该命令会将你的加载项复制到XLSTART文件夹，这是一个特殊的文件夹，每次启动 Excel 时都会从这里打开所有文件。

Renaming your add-in

承认地讲，这部分目前有点麻烦。假设我们要将加载项从MyAddin更改为。Demo:

  • 重命名为xlwings在 VBA 模块中，更改为Public Const PROJECT_NAME As String = "myaddin"更改为。Public Const PROJECT_NAME As String = "demo"。你将在顶部找到这一行，紧随Declare语句之后。

  • 如果你依赖于myaddin.conf表单进行配置，请将其重命名为demo.conf

  • 右键单击 VBA 项目，选择MyAddin Properties...并重命名Project Name来自MyAddin更改为。Demo.

  • 如果你使用功能区，你可能想将RibbonMyAddinVBA 模块重命名为RibbonDemo。为此，请在 VBA 编辑器中选择该模块，然后在Properties窗口中重命名。如果看不到属性窗口，请按F4.

  • 在 Office RibbonX 编辑器中打开加载项（参见上方），并将所有出现的MyAddin替换为Demo在 XML 代码中。

最后，你可能想在 Windows 资源管理器中重命名你的myproject.xlam文件，但我假设你已经使用正确的名称运行了 quickstart 命令，所以这将没有必要。

部署

将你的加载项部署给最终用户的最简单方法是通过 xlwings PRO 提供构建安装程序。这将处理所有事情，你的最终用户只需双击安装程序即可（无需现有的 Python 安装，也无需手动安装加载项或调整设置）。

如果你想免费（但困难）的方式，你需要自己构建安装程序，或者让您的用户安装 Python 和加载项，并确保将 Python 代码放在正确的目录中。通常情况下，这涉及调整以下设置，例如在myaddin.conf表单中：

  • Interpreter_Win/_Mac：如果最终用户有一个可用版本的 Python，你可以使用环境变量动态解析到正确的路径。例如，如果他们将 Anaconda 安装在默认位置，你可以使用以下配置：

    Conda Path: %USERPROFILE%\anaconda3
Conda Env: base
Interpreter_Mac: $HOME/opt/anaconda3/bin/python

  • PYTHONPATH：由于你无法将 Python 源代码放在加载项旁边的文件夹中，你需要调整设置并将该文件夹添加到存放 Python 代码的位置。你可以将其指向共享驱动器，或者再次利用环境变量，以便用户可以将文件放入一个名为XLSTART的文件夹中，例如用户主目录中的文件夹。然而，你也可以将你的 Python 代码放置在 Python 查找的地方，例如通过将它们放置在PYTHONPATHPython 分发版本的目录中——实现这一目标的一个简单方法是构建一个可以通过MyAddin安装的 Python 包。不过，你也可以更改 Ribbon 菜单site-packages导入 UDFspip.