Plugin API使用指南

Plugin API 是酷大师插件前端 API，它包含三部分内容，分别是:

酷大师应用 API, 从全局对象 app 访问，利用它可以访问到酷大师提供的各种能力，如数据、视图、建模命令、交互信息等。
几何库 API，从全局对象 GeomLib 访问，它提供了一些基础的数学和几何计算能力，用于辅助插件编程。
其他辅助 API，目前主要用于手动关闭插件

要使用酷大师 Plugin API，必须先对酷大师的基本功能和基础概念有一个了解。建议开发者通过如下步骤依次进行：

先通过酷大师插件开发教程开头提供的教程，学会使用酷大师的基本功能
再阅读酷大师建模基本概念一文，掌握酷大师建模的基本概念
然后阅读本文的 API 简介，大致了解有哪些 API，以及它们的用途
开始编写代码。过程中可按需查阅 Plugin API 用户手册

1、酷大师应用 API

酷大师应用API提供了酷大师拥有的各种能力，如数据、视图、建模命令、交互信息等，是酷大师插件前端最主要的 API 接口。下面分别简述：

（1）KDesign：代表酷大师方案，可通过 app.getActiveDesign() 方法获得酷大师当前打开的方案。通过 KDesign 接口可以调用几乎所有建模命令，如连线成面、拉伸、扫掠、移动、旋转、缩放、偏移、倒角、布尔、删除、成组、解组等。执行这些建模命令，会修改酷大师方案中的顶层几何造型，或当前处于编辑态的成组中的几何造型。执行这些建模命令，和在 UI 上点击建模操作命令一样，会自动拥有 undo/redo 的能力。当然，如果不想使用这种缺省的 undo/redo 行为，也可以使用 startOperation/commitOperation/abortOperation 这三个 API 的组合，将多个建模命令的修改结果，打包到一个 undo/redo 步骤中。

（2）KView：代表酷大师视图窗口，可通过 app.getActiveView() 方法获取当前视图窗口对象。通过该对象可以获得相机等信息，也可以进行临时对象绘制，方便插件与酷大师交互。

（3）KPluginUI：代表沙盒环境操作插件UI的接口，可通过 app.getPluginUI() 获取该接口对象。通过该对象可以显示、关闭插件 UI ，也可以注册插件 UI 的消息响应函数。

（4）KTool：代表插件自定义工具。除了酷大师顶部工具栏提供的基本工具之外，我们可通过实现 KTool 接口自定义工具，并通过 app.activateCustomTool(...) 来激活该工具，一旦激活后，用户即可像使用酷大师顶部栏提供的基本工具一样来使用自定义工具。通过自定义工具，插件开发者可以响应各种鼠标和键盘事件，从而实现丰富的交互行为。注意，在运行 KTool 自定义工具时，酷大师会提供和原生命令一样的对象吸附能力。

（5）KClientStorage：代表插件与客户端存储交互的接口，可通过 app.getClientStorage() 方法获取该接口对象。通过该对象，插件可在客户端进行数据存取。客户端存储通过浏览器缓存机制提供的 sessionStorage 实现。

（6）KSelection：代表酷大师的选择集，可通过 app.getSelection() 方法获得选择集对象。通过该对象可以获得酷大师方案中当前被选中的造型对象；也可以通过对选择集进行增删改等操作，控制酷大师进行高亮对象显示；同时我们可以往选择集注册观察者，用于监听选择集变化事件，对其做出响应。

（7）KToast：代表酷大师提示信息接口，可以通过 app.getToast() 方法获取提示信息对象。通过该接口可以在酷大师进行提示信息展示，提示信息如下图所示。提示信息类型包括提示、警告、错误等。

（8）KGroupDefinition & KGroupInstance：代表酷大师中的“成组”。KGroupDefinition 是“组定义”，代表这个组长什么样子，相当于面向对象编程中的“类”；KGroupInstance 是“组实例”，代表这个组在酷大师方案中的一个实际存在，相当于面向对象编程中的“对象”。酷大师建模基本概念一文中，已经对“成组”做了详细解释。下面结合 API 接口，再详细解释一遍：

"成组“可以被复制。当“成组”被复制时，实际上我们创建除了一批新的“组实例”，它们和原来的“组实例”共享一份”组定义“数据，因此本质上是“一份数据在不同的地方引用了多次“。我们可通过 KGroupDefinition 中的 getAllReferenceGroupInstances() 方法获取所有由该“组定义”定义的“组实例”，我们也可通过 KGroupInstance 中的 getGroupDefinition() 方法获得“组实例”引用的“组定义”。引用相同“组定义”的“组实例”，其在方案中的位姿可能会不一样，我们可通过 KGroupInstance 中的 getTransform() 方法获得其变换矩阵。
”成组“可以嵌套。即在用户操作上，一个”成组“可以和其他的造型面或者”成组“再组合起来，形成一个新的“成组”。实际上，一个酷大师方案本身就是一个成组，我们将其称之为“顶层成组”。当我们打开一个酷大师方案并开始建模时，就是在编辑方案顶层成组的“组定义”，我们可通过 KDesign 中的 getTopGroupDefinition() 方法获得顶层成组的“组定义”。同样，当我们在酷大师中双击”组实例“进入某个成组的组编辑时，实际上我们是在编辑这个”组实例“对应的“组定义”，当退出组编辑时，引用该“组定义”的所有“组实例”都会发生变化，我们可通过 KDesign 中的 getActiveGroupDefinition() 方法获得激活的“组定义”，即正在编辑的“组定义”。目前，通过 KDesign 中的方法对酷大师方案进行的编辑，编辑的都是当前被激活的“组定义”。
"成组”的定义可以来源于外部。在酷大师用户界面下通过”成组“命令手工创建的，以及通过 Plugin API 的 KDesgin.makeGroup 接口创建的成组，我们都称之为”原生成组“。此时通过 KGroupDefinition 中的 getType() 方法获得的“组定义”类型是 “native” 。在酷大师插件开发中，我们也允许“成组”的定义由插件生成。如智能 3D 文字，智能模型，场景模型，他们插入到酷大师中的模型我们统一称之为外部模型。这些"外部模型"在酷大师中实际上是一个个特殊的“组实例”，但它们的“组定义”数据是由插件提供的，此时通过 KGroupDefinition 中的 getType() 方法获得的“组定义”类型是 “xref”。