绘图 API

提供给 JavaScript 用于读取和生成图纸的函数：图纸中的 JavaScript 函数和扩展（后处理器、设计规则、模板、报表和保存扩展）使用的函数相同。设计规则、报表、后处理器和保存扩展可以读取图纸，但不能更改图纸。

值

数字、字符串和 true/false 保持原样。位置为 {x, y}；列表为数组，字典为 Map。返回的值也按相同方式转换：带有数字 x 和 y 的对象是位置，其他对象是由其属性组成的字典。

点

函数返回的点为 {x, y, id}：其位置及其在图纸中的名称（"P4"）。这些点是正在处理的页面上的点（每个页面都有自己的点）；变量则属于整个图纸。在函数接受点的地方，可以给出：

点（{x, y, id}）、其名称（"P4"）或其编号（4）：即该点，因此生成的内容会随该点移动；
位置（{x: 10, y: 20} 或 [10, 20]）：在该处新建一个固定的点。

读取图纸

函数	含义
`vars.NAME`	变量：`vars.L` 即 `L`，`vars.GAP` 即 `GAP`。
`variable("NAME")`	同上，按名称获取：`variable("W")`。系统变量的名称可以带或不带 `#`：`variable("#DFS")`、`vars.DFS`。
`getPoint(p)`	已存在的点：`getPoint(4)`、`getPoint("P4")`。
`evaluate("…")`	图纸语言的表达式：`evaluate("DISTANCE(P0,P2)")`。

变量和点

函数	含义
`setVariable("NAME", value)`	设置变量：设为数字或表达式（`setVariable("H", "L/2")`）。
`newPoint("expression")`	由表达式定义的新点：`newPoint("[L,0]")`、`newPoint("P3+[0,GAP]")`。
`newPoint(position)`	位于某个位置的固定新点。
`offset(p, dx, dy)`	与另一个点相距指定距离的新点。
`polar(p, angle, distance)`	与另一个点成指定角度（从 x 轴逆时针起算，单位为度）和距离的新点。
`between(p, q, t)`	位于从一个点到另一个点之间某处的新点（0 为第一个点，1 为第二个点）。

尺寸（dx、dy、angle、distance、t 以及圆的半径）可以是数字，也可以是字符串形式的表达式（"W/2"）：表达式使新点保持基于其变量定义，因此变量变化时新点会移动。

图元

函数	含义
`line(p, q)`	直线。
`arc(start, centre, end, anticlockwise)`	圆弧（省略时为逆时针）。
`circle(centre, radius)`	圆；半径为数字或表达式。
`bezier(p0, c1, c2, p3)`	三次贝塞尔曲线。
`polyline([p, …], closed)`	经过这些点的多段线（省略时不闭合）。
`point(p)`	点图元。
`text(p, "text", height, rotation)`	文字（省略时高度为 10，不旋转）。
`layer(n)`	此后生成的图元所在的图层（`null`：当前图层）。
`command("…")`	图纸语言的任意语句：`command("FILLET(@1,@2,5)")`。

图纸是什么

函数	含义
`drawingInfo()`	有关图纸的所有已知信息，按当前状态计算（见下文）。
`classification()`	图纸是什么：`{category, style, product, tags, description, …}`。未设置的字段为 `""`；`tags` 是数组。
`classify("field", value)`	设置其中一个字段（`""` 或 `null` 表示删除）：`classify("style", "FEFCO 0201")`。数组按列表保存：`classify("tags", ["rsc", "shipping"])`。
`classify({…})`	一次设置多个字段：`classify({ category: "Corrugated box", tags: ["rsc"] })`。
`classificationStyles()`	参考列表中的样式，每个为 `{code, name, category, series}`：`{code: "FEFCO 0201", name: "Regular slotted container", category: "Corrugated box", series: false}`。
`classificationCategories()`	参考列表中的类别，按名称：`["Folding carton", "Corrugated box", …]`。
`notes()`	图纸的备注，按名称：`notes().Customer`。
`note("name")`	某条备注的值；没有该备注时为 `null`。
`setNote("name", value)`	设置一条备注（`""` 或 `null` 表示删除）。

drawingInfo() 返回的对象包含：

属性	含义
`name`、`path`、`units`	图纸的名称和文件（未保存时为 `""`），以及 `"mm"` 或 `"in"`。
`classification`、`notes`	同上。
`variables`	图纸的变量（不含隐藏变量），按名称，已计算：`variables.L`。
`bounds`	图纸范围：`{minX, minY, maxX, maxY, width, height}`（未绘制任何内容时为 `null`）。
`elements`	当前页面的每个图元：其 `id`、`kind`、`layer`、`layerName`、`length`、`area`、`closed`、`start`、`end`、`bounds`、`radius`、`rule`、`minRadius`、`minRadiusAt`、`corners`、`bridges` 和 `tool`（参见设计规则）。
`layers`	每个图层：编号、`name`、是否为切割层（`cutting`），以及其中图元的数量（`count`）、长度（`length`）和面积（`area`）。
`totals`	`elements`、`length`、`width` 和 `height`；按图层名称的 `lengthByLayer` 和 `countByLayer`（`totals.lengthByLayer.Cut`）；`byKind`（`totals.byKind.LINE`）。
`page`、`pages`	当前页面，以及每个页面：其 `name`、是否为当前页面（`current`），以及图元数（`elements`）和点数（`points`）。
`nests`	所有页面上的排样，包括其板材、份数和损耗。
`frames`	当前页面上斜接画框线条的画框（斜接画框工具围绕画面生成的线条件，或按下料清单排布的线条件）：每个为 `{joined, whole, width, rebate, rebateFrom, outsideWidth, outsideHeight, pieces}`，图纸未给出裁口时其 `rebate` 为 `null`（`rebateFrom`：`"line"`，或变量 `"FRRB1"`），每个线条件为 `{side, longPoint, shortPoint}`（`side`：`"bottom"`、`"right"`、`"top"`、`"left"`；排布时为 `"width"` 或 `"height"`）。
`stone`	当前页面上的石材工件（切割图层上的闭合轮廓；位于工件内部的轮廓为其开孔）：`{pieces, slabs, edges, cutOuts, area, netArea}`。每个工件为 `{number, label, area, netArea, width, height, perimeter, slab, cutOuts, edges}`：其 `label` 为工件内部不指明开孔的文字，`slab` 为其所在大板的编号（或 `null`），每个开孔为 `{kind, width, height, area, round, from}`（`kind`：`"Sink"`、`"Hob"`、`"Tap hole"`、`"Socket"`、`"Cut-out"`、`"Round cut-out"`；`from`：`"label"`、`"layer"` 或 `"shape"`），`edges` 为标记了每种边型的边长（位于名称含 Edge 和该边型的图层上的线）。每块大板（Slab 图层上的轮廓）为 `{number, width, height, area, usedArea}`；`edges` 和 `cutOuts` 为按边型和按类型的合计。参见石材与瓷砖。
`accessories`	当前页面上放置的配件，按共享价格表（或零件自己的 `APRICE`）计价：`{list, items, cost, unpriced}`。`list` 中每一项为 `{item, kind, quantity, unit, price, cost, priced, x, y, id}`（`unit`：`"each"`、`"m"` 或 `"m²"`；没有价格时 `price` 为 `null`）；`items` 为按项目和价格汇总的同样内容 `{item, unit, quantity, price, cost, priced, count}`；`cost` 为全部费用；`unpriced` 为没有价格的项目。
`library`、`functions`	零件库中零件的名称和函数的名称。

设计规则、报表和保存扩展收到的 drawing 就是这个对象。图纸中的 JavaScript 函数可以读取备注和分类，但不能调用 drawingInfo()（它是作为图纸的一部分计算的），也不能更改备注和分类；设计规则、报表、后处理器和保存扩展同样不能更改。

显示值

print(…) 和 console.log(…) 在交互窗口中显示值，与 PRINT 相同，并附带函数或扩展的名称。

仅限扩展

函数	含义
`postProcessor({…})`	声明后处理器。
`designRule({…})`	声明设计规则。
`template({…})`	声明模板。
`drawingReport({…})`	声明报表。
`onSave({…})`	声明保存扩展。
`command({…})`	在扩展包中：声明一个命令，可从菜单、工具栏按钮、快捷键或运行命令… 运行；其所做的修改作为一步撤销。
`uiExtension({…})`	在扩展包中：其添加的菜单项、工具栏按钮和分组，以及其隐藏或移动的应用自带项。
`t("key", …)`	在扩展包中：该键对应的字符串，使用应用当前显示的语言（该语言没有时使用英语）。
`cameraRegistration({…})`	声明相机对位：相机在何处寻找作业的对位标记。
`httpRequest(url, {…})`	在相机对位中进行测量时：向其声明的某个服务发出请求。
`report(message, elements, at)`	在设计规则中：报告发现的问题。
`distanceBetween(a, b)`、`crossings(a, b)`	在设计规则或报表中：两个图元之间的最近距离，以及它们的交点。

对话框和拾取

在命令运行期间，ui 向用户提问；每个函数返回一个 promise，供 async run() 用 await 等待，用户作答期间应用仍可继续工作。

函数	含义
`await ui.form({ title, fields, validate })`	表单：按字段 id 给出各值（`number`、`integer`、`length`、`angle`、`text`、`choice`、`check`、`point` 字段），关闭前进行校验；取消时为 `null`。
`await ui.pick({ kind, prompt, filter })`	在图纸中拾取：一个位置（`{x, y}`，单击某个点时附带该点的 `id`），或按 `drawingInfo()` 的描述形式给出的一个或多个图元；按 Esc 时为 `null`。
`await ui.message(text, { title, kind })`	消息（`kind`：`"information"`、`"warning"`、`"error"`）。
`await ui.confirm(text, { title })`	提问：选择“是”时为 `true`。
`ui.progress({ title, cancellable })`	进度窗口：`await p.update(fraction, text)`（取消后为 `false`）、`p.cancelled()`、`p.close()`。
`await ui.runDesign(name, values)`	以给定的值将库中的设计打开为新图纸。

每个函数都需要在扩展包的清单中声明相应的权限。

仅限自动化脚本

自动化脚本可以对其当前图纸使用上述函数，还有自己的函数，用于打开、新建、导出和保存图纸（openDrawing、newDrawing、runDesign、图纸的 export 和 save …），以及读写其文件夹中的文件（readCsv、writeText …）。

另请参阅：JavaScript 函数、扩展、自动化脚本。