@jlceda/pro-api-types 0.2.65 → 0.2.67

package/index.d.ts

@@ -975,7 +975,7 @@ declare global {
 	 * 文档树 / 编辑器控制类
 	 *
 	 * @public
-	 * @remarks 此处编辑器控制基于当前已打开的工程设计下的图页，其它任何 `documentUuid` 都将被认为是不存在的文档页
+	 * @remarks 此处编辑器控制基于当前已打开的工程设计下��图页，其它任何 `documentUuid` 都将被认为是不存在的文档页
 	 */
 	class DMT_EditorControl {
 	    /**
@@ -1381,7 +1381,7 @@ declare global {
 	     */
 	    createPanel(): Promise<string | undefined>;
 	    /**
-	     * 修改面板���称
+	     * 修改面板名称
 	     *
 	     * @public
 	     * @param panelUuid - 面板 UUID
@@ -2391,7 +2391,7 @@ declare global {
 	     * @param targetLibraryUuid - 目标库 UUID
 	     * @param targetClassification - 目标库内的分类
 	     * @param newDeviceName - 新器件名称，如若目标库内存在重名器件将导致复制失败
-	     * @returns ���标库内新器件的 UUID
+	     * @returns 目标库内新器件的 UUID
 	     */
 	    copy(deviceUuid: string, libraryUuid: string, targetLibraryUuid: string, targetClassification?: ILIB_ClassificationIndex | Array<string>, newDeviceName?: string): Promise<string | undefined>;
 	    /**
@@ -4417,7 +4417,7 @@ declare global {
 	     * 停止飞线计算功能
 	     *
 	     * @public
-	     * @returns 操作��否成功
+	     * @returns 操作���否成功
 	     */
 	    stopCalculatingRatline(): Promise<boolean>;
 	    /**
@@ -5657,7 +5657,7 @@ declare global {
 	     * @beta
 	     * @remarks 可以使用 {@link SYS_FileSystem.saveFile} 接口将文件导出到本地文件系统
 	     * @param fileName - 文件名
-	     * @param colorSilkscreen - 是否生成彩色丝印制造��件（嘉立创专用文件）
+	     * @param colorSilkscreen - 是否生成彩色丝印制造���件（嘉立创专用文件）
 	     * @param unit - 单位
 	     * @param digitalFormat - 数字格式
 	     * @param other - 其它
@@ -7609,7 +7609,7 @@ declare global {
 	     *
 	     * @beta
 	     * @param primitiveIds - 文本的图元 ID，可以为字符串或字符串数组，如若为数组，则返回的也是数组
-	     * @returns 文本图��对象，`undefined` 表示获取失败
+	     * @returns 文本图���对象，`undefined` 表示获取失败
 	     */
 	    get(primitiveIds: string): Promise<IPCB_PrimitiveString | undefined>;
 	    /**
@@ -8790,7 +8790,7 @@ declare global {
 	     * 仅当 `ruleType` 为 {@link EPCB_PrimitiveRegionRuleType.FOLLOW_REGION_RULE} 时有效，用于匹配区域 DRC 规则
 	     *
 	     * 如若 `ruleType` 为 {@link EPCB_PrimitiveRegionRuleType.FOLLOW_REGION_RULE} 但 `regionName` 为空，则系统将会自动分配名称
-	     * @param regionName - ��域名称
+	     * @param regionName - ���域名称
 	     * @returns 区域图元对象
 	     */
 	    setState_RegionName(regionName?: string): IPCB_PrimitiveRegion;
@@ -9353,7 +9353,7 @@ declare global {
 	     */
 	    getState_PrimitiveId(): string;
 	    /**
-	     * 获取属性状态：网络名称
+	     * 获取属性状态��网络名称
 	     *
 	     * @public
 	     * @returns 网络名称
@@ -10455,7 +10455,7 @@ declare global {
 	     */
 	    setState_Layer(): IPCB_PrimitiveComponentPad;
 	    /**
-	     * 设��属性状态：焊盘编号
+	     * 设���属性状态：焊盘编号
 	     *
 	     * @internal
 	     * @remarks 本器件焊盘图元属性不支持修改，本接口调用将不会有任何效果
@@ -12138,7 +12138,7 @@ declare global {
 	 */
 	class PCB_SelectControl {
 	    /**
-	     * 查询所有已选中图元的图元 ID
+	     * ��询所有已选中图元的图元 ID
 	     *
 	     * @beta
 	     * @returns 所有已选中图元的图元 ID
@@ -13714,7 +13714,7 @@ declare global {
 	     *
 	     * @beta
 	     * @remarks 如若传入多个图元 ID，任意图元 ID 未匹配到不影响其它图元的返回，即可能返回少于传入的图元 ID 数量的图元对象
-	     * @param primitiveIds - 属性的图元 ID，可以为字符串或字符串数组，如若为数组，则��回的也是数组
+	     * @param primitiveIds - 属性的图元 ID，可以为字符串或字符串数组，如若为数组，则���回的也是数组
 	     * @returns 属性图元对象，空数组表示获取失败
 	     */
 	    get(primitiveIds: Array<string>): Promise<Array<ISCH_PrimitiveAttribute>>;
@@ -14281,7 +14281,7 @@ declare global {
 	     *
 	     * @beta
 	     * @param lineType - 线型
-	     * @returns 总线图元对象
+	     * @returns 总��图元对象
 	     */
 	    setState_LineType(lineType: ESCH_PrimitiveLineType | null): ISCH_PrimitiveBus;
 	    /**
@@ -14865,7 +14865,7 @@ declare global {
 	        [key: string]: string | number | boolean;
 	    } | undefined;
 	    /**
-	     * 设置��性状态：坐标 X
+	     * 设置���性状态：坐标 X
 	     *
 	     * @beta
 	     * @param x - 坐标 X
@@ -15920,7 +15920,7 @@ declare global {
 	        uuid: string;
 	    } | ILIB_DeviceItem | ILIB_DeviceSearchItem): Promise<boolean>;
 	    /**
-	     * 设置在扩展 API 中 AnalogGround 网络标识关联的���件 UUID
+	     * 设置在扩展 API 中 AnalogGround 网络标识关联的器件 UUID
 	     *
 	     * @beta
 	     * @param component - 关联库器件
@@ -19438,6 +19438,20 @@ declare global {
 	     * @returns 删除操作是否成功
 	     */
 	    deleteFileInFileSystem(uri: string, force?: boolean): Promise<boolean>;
+	    /**
+	     * 在文件系统内创建文件夹
+	     *
+	     * @beta
+	     * @remarks
+	     * 支持递归创建多层目录
+	     *
+	     * 注意 1：本接口仅客户端有效，在浏览器环境内调用将始终 `throw Error`
+	     *
+	     * 注意 2：本接口需要使用者启用扩展的外部交互权限，如若未启用将始终 `throw Error`
+	     * @param folderPath - 文件夹路径
+	     * @returns 创建操作是否成功
+	     */
+	    createDirectoryInFileSystem(folderPath: string): Promise<boolean>;
 	    /**
 	     * 获取 EDA 文档目录路径
 	     *
@@ -19536,7 +19550,7 @@ declare global {
 	     */
 	    convertAltiumDesignerLibrariesToEasyEDASingleFile(file: File | Array<File>): Promise<File | undefined>;
 	    /**
-	     * 转换 Altium Designer 库到多个嘉立创库文件（每个器件一个文件）
+	     * 转换 Altium Designer 库到多个嘉立创库文件���每个器件一个文件）
 	     *
 	     * @beta
 	     * @param file - Altium Designer 库文件
@@ -19967,7 +19981,7 @@ declare global {
 	     * @param height - 内联框架窗口的高度
 	     * @param id - 内联框架窗口 ID，用于关闭内联框架窗口
 	     * @param props - 其它参数
-	     * @returns 操作是否成功
+	     * @returns 操作是��成功
 	     */
 	    openIFrame(htmlFileName: string, width?: number, height?: number, id?: string, props?: {
 	        /** 是否显示最大化按钮 */
@@ -19978,12 +19992,24 @@ declare global {
 	        minimizeStyle?: 'collapsed' | 'constricted';
 	        /** 按钮点击回调 */
 	        buttonCallbackFn?: (button: 'close' | 'minimize' | 'maximize') => void | Promise<void>;
-	        /** 关闭前���调：回调返回 `false` 时阻止按钮触发 */
+	        /** 关闭前回调：回调返回 `false` 时阻止按钮触发 */
 	        onBeforeCloseCallFn?: () => boolean | undefined | Promise<boolean | undefined>;
 	        /** 是否背景置灰 */
 	        grayscaleMask?: boolean;
 	        /** IFrame 标题 */
 	        title?: string;
+	        /**
+	         * 窗口左上点所处页面视口 SVG 坐标 X（单位：像素）
+	         *
+	         * @remarks ADD since EDA v4
+	         */
+	        x?: number;
+	        /**
+	         * 窗口左上点所处页面视口 SVG 坐标 Y（单位：像素）
+	         *
+	         * @remarks ADD since EDA v4
+	         */
+	        y?: number;
 	    }): Promise<boolean>;
 	    /**
 	     * 关闭内联框架窗口
@@ -20173,6 +20199,225 @@ declare global {
 	    }>, types?: ESYS_LogType | Array<ESYS_LogType>): Promise<Array<ISYS_LogLine>>;
 	}
 
+	/**
+	 * 离散点
+	 *
+	 * @public
+	 */
+	interface ISYS_MathPoint {
+	    /** X 坐标 */
+	    x: number;
+	    /** Y 坐标 */
+	    y: number;
+	}
+	/**
+	 * BBox（最小外接矩形）
+	 *
+	 * @public
+	 */
+	interface ISYS_MathBBox {
+	    /** 最小 X 坐标 */
+	    minX: number;
+	    /** 最小 Y 坐标 */
+	    minY: number;
+	    /** 最大 X 坐标 */
+	    maxX: number;
+	    /** 最大 Y 坐标 */
+	    maxY: number;
+	}
+	/**
+	 * 多边形输入类型
+	 *
+	 * @public
+	 * @remarks 支持以下输入格式：
+	 * - 离散点数组：`[{x, y}, {x, y}, ...]`
+	 * - 单多边形源数组：{@link TPCB_PolygonSourceArray}
+	 * - 单多边形对象：{@link IPCB_Polygon}
+	 * - 复杂多边形对象：{@link IPCB_ComplexPolygon}
+	 */
+	type TSYS_MathPolygonInput = Array<ISYS_MathPoint> | TPCB_PolygonSourceArray | IPCB_Polygon | IPCB_ComplexPolygon;
+	/**
+	 * 系统 / 数学计算类
+	 *
+	 * @public
+	 * @remarks 提供多边形几何计算方法，支持离散点坐标和 {@link TPCB_PolygonSourceArray} 多边形数据
+	 */
+	class SYS_Math {
+	    /**
+	     * 判断点是否在多边形内部
+	     *
+	     * @public
+	     * @remarks 使用射线法（Ray Casting）判断点是否在多边形内部，边界上的点视为不在内部
+	     * @param polygon - 多边形
+	     * @param point - 待判断的点
+	     * @returns 是否在多边形内部
+	     */
+	    containsPoint(polygon: TSYS_MathPolygonInput, point: ISYS_MathPoint): boolean;
+	    /**
+	     * 计算点到多边形边界的最短距离
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @param point - 待计算的点
+	     * @returns 最短距离，如点在多边形内部则返回 `0`
+	     */
+	    distanceToPoint(polygon: TSYS_MathPolygonInput, point: ISYS_MathPoint): number;
+	    /**
+	     * 判断两个多边形是否相交
+	     *
+	     * @public
+	     * @remarks 判断两个多边形的区域是否有任何重叠（包括包含、部分相交、边界接触）
+	     * @param polygon1 - 多边形 1
+	     * @param polygon2 - 多边形 2
+	     * @returns 是否相交
+	     */
+	    intersects(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): boolean;
+	    /**
+	     * 判断 polygon1 是否完全包含 polygon2
+	     *
+	     * @public
+	     * @param polygon1 - 外部多边形
+	     * @param polygon2 - 内部多边形
+	     * @returns polygon1 是否完全包含 polygon2
+	     */
+	    contains(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): boolean;
+	    /**
+	     * 获取多边形的最小外接矩形（BBox）
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @returns BBox
+	     */
+	    getBBox(polygon: TSYS_MathPolygonInput): ISYS_MathBBox;
+	    /**
+	     * 快速判断两个 BBox 是否相交
+	     *
+	     * @public
+	     * @param bbox1 - BBox 1
+	     * @param bbox2 - BBox 2
+	     * @returns 是否相交
+	     */
+	    bboxIntersects(bbox1: ISYS_MathBBox, bbox2: ISYS_MathBBox): boolean;
+	    /**
+	     * 计算多边形面积
+	     *
+	     * @public
+	     * @remarks 使用 Shoelace 公式计算，结果为绝对值
+	     * @param polygon - 多边形
+	     * @returns 面积
+	     */
+	    calculateArea(polygon: TSYS_MathPolygonInput): number;
+	    /**
+	     * 计算多边形周长
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @returns 周长
+	     */
+	    calculatePerimeter(polygon: TSYS_MathPolygonInput): number;
+	    /**
+	     * 计算多边形质心
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @returns 质心坐标
+	     */
+	    getCentroid(polygon: TSYS_MathPolygonInput): ISYS_MathPoint;
+	    /**
+	     * 平移多边形
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @param dx - X 方向偏移量
+	     * @param dy - Y 方向偏移量
+	     * @returns 平移后的离散点数组
+	     */
+	    translate(polygon: TSYS_MathPolygonInput, dx: number, dy: number): Array<ISYS_MathPoint>;
+	    /**
+	     * 旋转多边形
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @param angle - 旋转角度（角度制，正值为逆时针）
+	     * @param centerX - 旋转中心 X 坐标，默认为质心
+	     * @param centerY - 旋转中心 Y 坐标，默认为质心
+	     * @returns 旋转后的离散点数组
+	     */
+	    rotate(polygon: TSYS_MathPolygonInput, angle: number, centerX?: number, centerY?: number): Array<ISYS_MathPoint>;
+	    /**
+	     * 缩放多边形
+	     *
+	     * @public
+	     * @param polygon - 多边形
+	     * @param scaleX - X 方向缩放比例
+	     * @param scaleY - Y 方向缩放比例，默认与 scaleX 相同
+	     * @param centerX - 缩放中心 X 坐标，默认为质心
+	     * @param centerY - 缩放中心 Y 坐标，默认为质心
+	     * @returns 缩放后的离散点数组
+	     */
+	    scale(polygon: TSYS_MathPolygonInput, scaleX: number, scaleY?: number, centerX?: number, centerY?: number): Array<ISYS_MathPoint>;
+	    /**
+	     * 计算两个多边形的并集
+	     *
+	     * @public
+	     * @param polygon1 - 多边形 1
+	     * @param polygon2 - 多边形 2
+	     * @returns 并集结果的离散点环数组，每个环为一个独立的多边形
+	     */
+	    union(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): Array<Array<ISYS_MathPoint>>;
+	    /**
+	     * 计算两个多边形的差集（polygon1 - polygon2）
+	     *
+	     * @public
+	     * @param polygon1 - 被减多边形
+	     * @param polygon2 - 减去的多边形
+	     * @returns 差集结果的离散点环数组
+	     */
+	    subtract(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): Array<Array<ISYS_MathPoint>>;
+	    /**
+	     * 计算两个多边形的交集
+	     *
+	     * @public
+	     * @param polygon1 - 多边形 1
+	     * @param polygon2 - 多边形 2
+	     * @returns 交集结果的离散点环数组，空数组表示无交集
+	     */
+	    intersection(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): Array<Array<ISYS_MathPoint>>;
+	    /**
+	     * 计算两个多边形的对称差集（异或）
+	     *
+	     * @public
+	     * @param polygon1 - 多边形 1
+	     * @param polygon2 - 多边形 2
+	     * @returns 对称差集结果的离散点环数组
+	     */
+	    xor(polygon1: TSYS_MathPolygonInput, polygon2: TSYS_MathPolygonInput): Array<Array<ISYS_MathPoint>>;
+	    /**
+	     * 将任意多边形输入归一化为离散点数组
+	     *
+	     * @internal
+	     * @param input - 多边形输入，支持离散点数组、{@link TPCB_PolygonSourceArray}、{@link IPCB_Polygon}、{@link IPCB_ComplexPolygon}
+	     * @returns 离散点数组
+	     */
+	    private normalizeToPoints;
+	    /**
+	     * 将任意多边形输入归一化为 d3-polygon 所需的坐标对数组 `[[x, y], ...]`
+	     *
+	     * @internal
+	     * @param input - 多边形输入
+	     * @returns d3-polygon 格式的坐标对数组
+	     */
+	    private normalizeToD3Polygon;
+	    /**
+	     * 将任意多边形输入归一化为 martinez 所需的多环格式 `[[[x, y], ...]]`
+	     *
+	     * @internal
+	     * @param input - 多边形输入
+	     * @returns martinez 格式的多环坐标数组
+	     */
+	    private normalizeToMartinez;
+	}
+
 	/**
 	 * 左侧面板标签页
 	 *
@@ -21187,6 +21432,16 @@ declare global {
 	     * @param url - URL
 	     */
 	    urlReplaceState(url: string): void;
+	    /**
+	     * 获取页面当前视口大小
+	     *
+	     * @public
+	     * @returns 视口宽高（单位：像素）
+	     */
+	    getViewportSize(): {
+	        width: number;
+	        height: number;
+	    };
 	}
 
 	/**
@@ -21274,6 +21529,7 @@ declare global {
 	    sys_IFrame: SYS_IFrame;
 	    sys_LoadingAndProgressBar: SYS_LoadingAndProgressBar;
 	    sys_Log: SYS_Log;
+	    sys_Math: SYS_Math;
 	    sys_Message: SYS_Message;
 	    sys_MessageBox: SYS_MessageBox;
 	    sys_MessageBus: SYS_MessageBus;

package/package.json

@@ -1 +1 @@
-{ "name": "@jlceda/pro-api-types", "type": "module", "version": "0.2.65", "description": "嘉立创EDA & EasyEDA 专业版扩展 API 接口类型定义", "typings": "index.d.ts", "author": "JLCEDA <support@lceda.cn>", "license": "Apache-2.0", "homepage": "https://pro.lceda.cn/", "keywords": ["jlceda", "pro-api"], "scripts": { "lint": "eslint", "fix": "eslint --fix", "build": "ts-node ./build/build.ts" }, "devDependencies": { "@antfu/eslint-config": "^5.4.1", "@types/fast-text-encoding": "^1.0.3", "@types/fs-extra": "^11.0.4", "dotenv": "^16.4.7", "eslint": "^9.37.0", "fast-text-encoding": "^1.0.6", "fs-extra": "^11.3.0", "lint-staged": "^16.2.3", "simple-git-hooks": "^2.13.1", "ts-node": "^10.9.2", "typescript": "^5.7.3" }, "simple-git-hooks": { "pre-commit": "npx lint-staged" }, "lint-staged": { "*": "eslint --fix" } }
+{ "name": "@jlceda/pro-api-types", "type": "module", "version": "0.2.67", "description": "嘉立创EDA & EasyEDA 专业版扩展 API 接口类型定义", "typings": "index.d.ts", "author": "JLCEDA <support@lceda.cn>", "license": "Apache-2.0", "homepage": "https://pro.lceda.cn/", "keywords": ["jlceda", "pro-api"], "scripts": { "lint": "eslint", "fix": "eslint --fix", "build": "ts-node ./build/build.ts" }, "devDependencies": { "@antfu/eslint-config": "^5.4.1", "@types/fast-text-encoding": "^1.0.3", "@types/fs-extra": "^11.0.4", "dotenv": "^16.4.7", "eslint": "^9.37.0", "fast-text-encoding": "^1.0.6", "fs-extra": "^11.3.0", "lint-staged": "^16.2.3", "simple-git-hooks": "^2.13.1", "ts-node": "^10.9.2", "typescript": "^5.7.3" }, "simple-git-hooks": { "pre-commit": "npx lint-staged" }, "lint-staged": { "*": "eslint --fix" } }