Methodox Wiki
产品文档
简体中文
English 简体中文 繁體中文
Methodox 首页

Python

Python 是 Methodox Office 中继 Lua 和 C# 之后的第三种脚本语言。它在编程模型中扮演相同的角色：Scripts 窗格中的 .py 脚本是一个 Command，functions.py 包含工作表 Function，智能对象的源可以是一个 Python 表达式。Python 在 SteelPython 上运行，SteelPython 是套件的一部分，因此无需安装其他任何内容。

第一个脚本

在 Scripts 窗格的语言列表中选择 Python，然后选择 New script；或者打开 Nu 示例 Circle of triangles.pptx，其中的 CircleOfTriangles.py 会绘制与 Lua 脚本相同的三角形圆环：

import colorsys
import math

COUNT = 24      # how many triangles
RADIUS = 170    # points from the centre of the ring to the centre of each triangle
SIZE = 34       # each triangle's width and height, in points

page = doc.active_page
cx, cy = page.center_x, page.center_y

old = page.shapes.find("Ring")
if old is not None:
    old.delete()

triangles = []
for i in range(COUNT):
    angle = 360 * i / COUNT
    t = math.radians(angle)
    triangle = page.shapes.add_shape("triangle", 0, 0, SIZE, SIZE)
    triangle.center_on(cx + RADIUS * math.cos(t), cy + RADIUS * math.sin(t))
    triangle.rotation = angle + 90
    r, g, b = colorsys.hsv_to_rgb(i / COUNT, 0.65, 0.95)
    triangle.fill = "#{:02X}{:02X}{:02X}".format(int(r * 255), int(g * 255), int(b * 255))
    triangles.append(triangle)

ring = page.shapes.group(triangles)
ring.name = "Ring"
print(f"Drew {COUNT} triangles on page {page.index}.")

这些名称就是对象模型中的名称，采用 snake_case 形式：doc.active_page、sheet.used_range.address、doc.sheets.add(...)。doc、app、session、param 和 host 与 Lua 中一样可用，位置从 1 开始计数（doc.sheets[1]）。与任何 Command 一样，一次运行是一个事务，也是 Edit ▸ Undo 中的一个步骤，失败时会回滚。从命令行运行：MethodoxNu --script CircleOfTriangles.py --save-as ring.pptx。

工作表函数

在名为 functions.py（或 anything.functions.py）的脚本中，每个名称为大写字母的顶层 def 都是一个工作表函数，以 =PY.NAME(...) 的形式调用：

def TAX(amount: float, rate: float = 0.2) -> float:
    """Tax on an amount, at 20% unless a rate is given."""
    return amount * rate

def SUMSQ(values: list) -> float:
    """The sum of the squares of a range."""
    return sum(v * v for row in values for v in row if isinstance(v, (int, float)))

文档字符串是 Insert Function 显示的说明；默认值使参数成为可选参数，*values 可接受任意数量的实参，注解为 list 的参数以行列表的形式接收整个区域，float、str 和 bool 则会转换实参。函数以 param.Name 读取文档的参数，通过 host 获取数据的函数是数据源 Function。关于函数如何重新计算、溢出和启用，请参阅工作表函数。

智能对象

在 Insert ▸ Smart Object 中选择 Python，然后编写一个基于其他智能对象的表达式，例如 smart.Revenue * 0.2 或 smart["Revenue"] * 0.2，或者编写一个返回值的函数体。它可以调用文档的 Python 函数脚本中的函数。参见智能对象。

文档的 Python 可以做什么

文档的 Python 可以使用什么取决于版本：

  • Standard： 对象模型、宿主授予的调用，以及一系列计算类模块（math、cmath、statistics、decimal、fractions、random、re、json、datetime、calendar、zoneinfo、time、collections、itertools、functools、textwrap、heapq、bisect、copy、enum、colorsys、difflib、unicodedata、base64、hashlib、struct、array、numbers）。没有 open、exec 或 eval，没有 .NET 桥接，也没有已安装的包；导入列表之外的模块会被拒绝，并显示指出该模块名称的消息。
  • Compute： 完整的 Python，包括文档环境中的包以及 SteelPython 与 .NET 之间的桥接。

即时模式（Tools ▸ Immediate）是你自己输入的内容，因此在两个版本中，其 Python 都拥有完全访问权限。

环境和包

包保存在 Python 环境中，每个文档都通过其 Python Environment 设置说明其 Python 从哪个环境导入。你发送给别人的工作簿携带的是其脚本和该设置，而不是包的副本，因此对方需要在自己的计算机上创建该环境。

只有完全受信任的 Python 才会使用环境：即时模式，以及在 Compute 版中你启用后的文档代码。在 Standard 版中，文档的脚本运行的是经过审核的 Python，无论设置如何，它只能导入上面列出的计算类模块。

Scripts 窗格工具条上的 Python environments and packages 按钮会打开 Python Environments 对话框。在对话框顶部，文档的 Python Environment 为以下之一：

  • Your environment：你自己的环境，按用户区分，保存在 %LOCALAPPDATA%\DivookaOffice\Python\environments 中，由所有未选择其他环境的文档共享。在它下方，你可以选择你的哪个环境处于活动状态，创建和删除环境，以及在某个环境中安装 pip。
  • .venv beside the document：文档文件旁边的 .venv 文件夹，在你第一次选择它时（连同 pip）自动为你创建。请先保存文档，因为该文件夹位于文档文件旁边。
  • A folder…：任何虚拟环境，即包含 pyvenv.cfg 的文件夹，无论是由 Python 的 venv、SteelPython 还是 Methodox Office 创建的。
  • An interpreter…：一个 python.exe 或 spy.exe。位于虚拟环境内的解释器代表该环境；不在任何虚拟环境中的解释器代表其安装的包，pip 会使用它运行。

位于文档旁边或其文件夹下的选择会以相对于文档的路径存储，因此包含工作簿及其 .venv 的文件夹可以作为一个整体移动或共享。做出选择会将文档标记为已更改；保存文档即可保留该选择。当你正在处理某个文档时，窗口会使用该文档的环境。

Standard 版中的 Python Environments 对话框：文档选择的环境及其脚本只能导入标准库的说明、用户的环境，以及用于安装包的输入框

在选择下方，对话框会列出环境中的包，并可以安装（requests，或指定版本的 numpy==2.1）、升级和卸载包，运行时会显示 pip 的输出。在 Standard 版中，对话框会在选择旁边说明文档自身的脚本只能导入标准库。

目前仅支持纯 Python 包。 无论由哪个解释器安装，包都由 Methodox Office 自己的 Python（即应用程序内部的 SteelPython 3.12）导入，因此脚本可以保留对象模型。用 Python 编写的包可以从任何环境导入。带有已编译扩展模块的包（例如 numpy、pandas 或 lxml）可以安装，但目前还无法在 Methodox Office 中导入。用其他 Python 版本创建的环境会被标记出来，因为其中的包可能无法导入。

对于 Methodox Office 创建的环境，pip 在其自己的进程 mos python 中运行，它也是命令行上的 Python；带有自己解释器的虚拟环境则使用该解释器运行 pip：

mos python -V
mos python -c "print(2 ** 10)"
mos python script.py
mos python --env "%LOCALAPPDATA%\DivookaOffice\Python\environments\<name>" -m pip install requests

使用 --env 时，该环境即为安装位置：-m pip install 会安装到其中，-m ensurepip 会把 pip 放入其中，与虚拟环境自己的解释器的行为相同。

另请参阅