Divooka 图

Methodox Office 文档可以携带 Divooka 程序，即由节点和连线组成的图，作为 Lua 和 C# 之外的第三种语言。文档的图以 .dvj 文档的形式保存在其内部，这是 Divooka Compute 所打开的 .dvk 的文本形式；每个图都扮演编程模型中的某一个角色：

图	角色	用法
以大写字母命名的 Function 图	Function	在 Formula 中为 =DVK.LOANPAYMENT(B1, B2, B3)；作为 Impulse 智能对象时为 LOANPAYMENT(param.Principal, param.Rate, param.Years)
Routine	Command	在 Tools ▸ Scripts 中运行；在命令行中为 --script Report.dvj#StampRegion
Events 图	事件处理程序	在文档打开、保存、编辑、重新计算、刷新或放映时运行

图在 Divooka 的 No-Reflection Interpreter 上运行，它只准备一次图，之后按需多次调用，因此由两百个单元格组成的一列调用同一个图时，只准备一次。

图编辑器

Tools ▸ Scripts（Alt+F11）会在文档的 Lua、C# 和 Python 脚本旁边列出其图文档。选中一个 .dvj，图就会在原本是文本编辑器的位置以画布形式打开，每个图一个选项卡：Function 图显示 fx 图标，Routine 显示播放图标，Events 图显示铃铛图标。编辑器的工具会加入窗格的工具条。

• 移动视图。 用中键拖动，或按住 Alt 或 Space 拖动，即可平移；滚轮以指针位置为中心缩放；F 使图适应视图。较长的图打开时会以可读的大小显示其开头。
• 添加节点。 右键单击画布空白处，或使用 + 按钮，即可在该处打开一个可搜索的面板。它只列出文档的版本能够运行的内容：值节点（Number、Text Line、Text、Boolean、Comment），Routine 图和 Events 图中的 Branch，Events 图中该事件类型的事件，以及按名称列出的每个 Document Parameter——放置后即为其读取节点，并连线到图的 This Document。重载通过其输入加以区分。会更改文档的调用只在 Routine 图和 Events 图中提供，在 Function 中永远不提供。从引脚拖出连线并在画布空白处松开，会在该处打开面板，所选节点会自动与之连线。
• 了解节点。 将鼠标悬停在节点上，即可看到它调用的内容、它来自的工具箱和包（与 Divooka Compute 中的显示相同），以及它的文档：它的作用、每个输入的含义以及它返回什么。这样就能了解诸如 Loan Letter 中 Amortization Schedule 这样的节点是什么。
• 连线与编辑。 从一个引脚拖到另一个引脚即可连接；类型不匹配的连线会被拒绝，工具条会说明原因。按住 Alt 单击连线、在连线上划过，或右键单击连线并选择 Delete Wire，即可断开连接。字面量在引脚上编辑。
• 节点菜单。 右键单击节点可使用 Cut（Ctrl+X）、Copy（Ctrl+C）、Paste（Ctrl+V）、Duplicate（Ctrl+D）、Rename 和 Delete（Delete）。复制的节点会保留它们之间的连线，既可以粘贴到当前图，也可以粘贴到另一个图或另一个文档的图中。图的 Input 和 Output（或 Begin 和 Return）不能删除。
• 图的输入和输出。 在图已存在后，可通过图的 Input 或 Output 节点菜单中的 Edit Inputs、其选项卡菜单中的 Inputs and Outputs 或工具条上的接口按钮，更改 Function 的输入和输出或 Routine 的输入，格式与新建图时相同（Principal, Rate, Years=30）；名称保持不变的端口上的连线会保留。选项卡菜单中还有 Rename Graph 和 Delete Graph。
• 新建图。 图层按钮可添加一个 Function（及其输入和输出，例如 Principal, Rate, Years=30；其他类型的输入写作 name:text）、一个 Routine，或基于所选事件类型的文档 Events 图。
• 编辑会自动写入文档。 在画布上每次更改后片刻（绝不会在拖动过程中），图就会被写入文档，使用它的单元格和智能对象会立即重新计算：在 Graph Editor 示例中更改 Add 的 Summand1，B2 就会随之变化。每次更改都是窗口 Edit ▸ Undo 中的一个步骤，撤消时会撤回该更改，画布也会随之恢复。
• 错误会定位到其节点。 当某个单元格或事件处理程序的错误指明了某个节点时，文档上方的红色栏会有一个按钮，用于打开该图并选中该节点。在某个节点上失败的 Routine 会在运行后选中该节点。版本不支持运行的节点会在画布上标记出来，悬停时显示原因。

外部链接按钮 Open in Divooka Compute 会在已安装 Divooka Compute（完整的 Divooka 编辑器）时在其中打开图；否则该按钮处于禁用状态，其工具提示会说明未安装 Divooka Compute。版本说明了 Methodox Office 在何处查找它。文档的副本会随图一起发送，因此在 Compute 中，This Document 就是该副本，添加节点菜单会在 Office ▸ Parameters 下列出其参数；Methodox Office 还会发送它的 Office 节点，因此 Compute 无需安装任何内容就能提供这些节点。在 Compute 中保存后，图会作为一次可撤消的更改回到文档中；如果在此期间文档的副本已被更改，Methodox Office 会询问保留哪一个。使用了 Standard 版不支持运行的节点的图，会按 Compute 写入的样子保留，并显示其无法运行的原因。参见文档会话。

Function 图

名称为大写字母的 Function 图是工作表函数：工作簿 Loan.dvj 中的 LOANPAYMENT 以 =DVK.LOANPAYMENT(...) 的形式调用。返回表格的图会将其溢出，例如 =DVK.AMORTIZE(B1, B2, B3) 会溢出贷款的还款计划；返回图片的图会在其单元格中按比例适应显示图片，与 Excel 的 IMAGE 相同，单元格的值为 Image W×H。在 Impulse 和 Expo 中，同一个图是智能对象的源，按名称调用，可使用数字、带引号的文本、param.Name 和 smart.Name 作为实参；返回图片（例如图表）的图会填充图像智能对象。参见工作表函数和智能对象。

使用了获取数据节点的 Function 图是数据源 Function，它只在文档刷新时（在 Formula 中为 Data ▸ Refresh Data，Ctrl+Shift+F5；在 Impulse 和 Expo 中为 Refresh All，Ctrl+Shift+F9）或其读取的参数发生变化时获取数据，在此期间则以上次获取的内容作答。

Routine

Routine 图是一个 Command：当从 Tools ▸ Scripts 运行时（Run 旁边的列表用于选择运行图文档中的哪个 Routine），或从命令行运行时，它会更改文档，作为一个可撤消的步骤：

MethodoxFormula --script "Report.dvj#StampRegion" --open "Region Events.xlsx" --save-as Stamped.xlsx

图文档后面的 #Name 指定要运行的 Routine。

事件处理程序

Events 图实现某一种 Office 事件类型，当文档已启用且事件发生时，其处理程序就会运行：

事件类型	事件
所有文档	Opened、BeforeSave、Saved、ParameterChanged
工作簿	WorkbookOpened、RangeChanged（每次编辑时每个工作表一个区域）、Calculated
文本文档	SmartObjectsRefreshed
演示文稿	SlideShowStarted、SlideShowAdvanced、SlideShowEnded

每个处理程序在文档上作为一个事务运行。由处理程序自身更改引发的事件不会传回给它，撤消和重做不会引发事件，一秒钟内超过 64 个事件会暂停处理程序，因此处理程序不会陷入循环。

Office 节点

在 Standard 版中，图可以使用 Divooka 标准库中的纯例程（数字、文本、逻辑、日期、数组、列表、集合、字典、转换）以及以下 Office 节点：

分组	节点
Document	This Document（图自己的文档）；Open Office Document（在 Divooka Compute 中为文件；在 Office 中为图自己的文档）和 Save Office Document
Parameters	Parameter、Number Parameter、Text Parameter、Boolean Parameter、Has Parameter、Parameter Names，每个都接受文档并指定其读取的参数名；Set Parameter 仅用于 Command
Data	HTTP Get、HTTP Get Bytes、Read Text File（通过用户的授权）；按点分路径读取的 Json Number、Json Numbers、Json Text、Json Texts；Format Url
Tables	Columns、Sequence、Number Column、Row Count、Amortization Schedule
Images	Chart（由 Formula 的图表引擎绘制为图片的表格）、From Bytes
Document edits	用于 Command，每个都接受文档：Set Cell、Get Cell、Set Formula、Write Table、Add Sheet、Add Paragraph、Add Slide、Slide Count、Document Name、Document Path、Run Command；以及 Log

Divooka Compute 中也提供相同的节点，因此在那里制作的图就是 Methodox Office 运行的图。早期版本中的图（其 Parameter 节点会自行查找文档）在读取时会被转换为这种形式；参见 Document Parameter。

Methodox Office + Divooka Compute 还允许图使用其旁边已安装的 Divooka 包（参见版本）。使用了其版本不允许的节点的图会在运行之前被拒绝，消息中会指出该图和该节点；运行过程中的失败也同样如此，消息会显示在单元格的消息或 Scripts 窗格的输出中。

试一试

Examples\Automation 中包含：

• Loan Calculator.xlsx：=DVK.LOANPAYMENT 和溢出的 =DVK.AMORTIZE 还款计划，贷款条款作为 Document Parameter（Tools ▸ Parameters）。在 Divooka Compute 中打开其图，可以看到那里也提供相同的参数。
• Loan Letter.docx：在一封信函中作为智能对象使用的相同图；将鼠标悬停在 Loan.dvj 中的 Amortization Schedule 节点上，可以看到它的来源。
• Weather.xlsx：从 Open-Meteo 获取天气预报的数据源 Function。Weather Report 用一个图绘制其 24 小时图表，Market Dashboard 则通过一个 Events 图重新绘制自身。
• Region Events.xlsx：一个记录更改内容的 Events 图，以及 StampRegion Routine。
• Graph Editor.xlsx：可供编辑的 Pricing 图，B2 会随每次更改而变化；一个使用了 Standard 版会拒绝的节点的图；以及 B10 中一个以图片作为结果的 Function，图片绘制在其单元格中。
• Graphs\*.dvj：独立的图文件，供 Divooka Compute 使用。

请先启用每个文档；之后天气示例会要求你 Allow 它们对 api.open-meteo.com 的请求。