kingscript-plugin-dev

name: kingscript-plugin-dev description: 金蝶苍穹 Kingscript 插件开发专家。当用户需要为金蝶苍穹/cosmic 平台编写 Kingscript/KS 脚本插件时使用此技能，包括但不限于：操作插件、表单插件、列表插件、转换插件、报表插件、工作流插件、调度任务等。涵盖插件生命周期、ORM 数据访问、BigDecimal 财务计算、界面交互控制、F7过滤、页面弹窗传参、消息通知、DataSet统计报表。即使用户只提到"苍穹插件"、"kingscript"、"KS脚本"、"cosmic插件"、"单据插件"、"保存校验"、"字段联动"、"下推转换"、"单据下推"、"ORM查询"、"F7过滤"、"审批流"、"定时任务"、"入库出库"、"金蝶二开"、"苍穹二开"、"苍穹脚本"、"单据联动"、"列表过滤"、"报表取数"、"金蝶低代码"、"自定义操作"、"单据校验"等关键词，也应触发此技能。

Kingscript 插件开发专家

为金蝶苍穹平台 Kingscript 插件开发提供全面指导。

插件类型速查

开发时先确定插件类型，再阅读对应的参考文档获取完整事件列表和示例代码。

文件命名与结构

命名规范

格式：{entity}_{type}_{operation}.ts

• 实体名：小写，如 pm_purorderbill, ap_paybill
• 类型标识：op(操作)、form(表单)、list(列表)、conv(转换)、rpt(报表)
• 操作类型：save, submit, audit, delete

示例：ap_paybill_op_save.ts、pm_purorderbill_form.ts、pm_to_im_conv.ts

文件路径：src/@cosmic/{MODULE}/{SUBMODULE}_ext/

插件骨架

所有插件遵循相同的结构模式：

import { 基类 } from "导入路径";

class MyPlugin extends 基类 {
  // 重写生命周期方法
  someEvent(e: any): void {
    super.someEvent(e);
    // 业务逻辑（使用局部变量）
  }
}

let plugin = new MyPlugin();
export { plugin };

完整模板见 scripts/form-plugin-template.ts 和 scripts/operation-plugin-template.ts。

生命周期速查

操作插件生命周期（按执行顺序）

表单插件生命周期（按执行顺序）

关键原则

1. 无状态设计（最重要）

插件实例被所有表单共享，界面关闭后实例会被缓存复用。因此：

• 禁止在类中定义属性，所有数据必须使用方法内的局部变量
• 通过 this.getModel() / this.getView() 获取当前上下文

// 错误：类属性会被所有表单实例共享，导致数据串扰
class MyPlugin extends AbstractBillPlugIn {
  private currentBillNo: string;  // 禁止
}

// 正确：使用局部变量
class MyPlugin extends AbstractBillPlugIn {
  afterLoadData(e: any): void {
    const currentBillNo = this.getModel().getValue("billno") as string;
  }
}

2. 字段预加载

操作插件中使用 get(field) 或 set(field) 前，必须在 onPreparePropertys 中声明字段：

onPreparePropertys(e: any): void {
  super.onPreparePropertys(e);
  const props = e.getFieldKeys();
  props.add("billno");
  props.add("supplier");
  props.add("supplier.name");        // 基础资料关联属性
  props.add("billentry.payamount");   // 分录字段需加前缀
}

3. 查询接口选择

详见 data-service.md。

4. 事务处理

• 耗时操作（数据计算、格式转换）放在 beforeExecuteOperationTransaction（事务外）
• beginOperationTransaction 内只做数据库操作，不支持跨库
• 第三方系统同步需在 rollbackOperation 中做补偿
• 日志、通知放在 afterExecuteOperationTransaction（事务后）

5. 财务计算

金额、数量、单价等财务数据必须使用 BigDecimal，禁止使用 number 类型。详见 bigdecimal.md。

SDK 限流规范

禁止直接使用 DB 或 ORM 操作数据库，必须通过 ServiceHelper。

常用导入

// 插件基类（按需选择一个）
import { AbstractOperationServicePlugIn } from "@cosmic/bos-core/kd/bos/entity/plugin";
import { AbstractBillPlugIn } from "@cosmic/bos-core/kd/bos/bill";
import { AbstractListPlugin } from "@cosmic/bos-core/kd/bos/list/plugin";
import { AbstractConvertPlugIn } from "@cosmic/bos-core/kd/bos/entity/botp/plugin";

// 数据类型与服务（最常用）
import { DynamicObject, DynamicObjectCollection } from "@cosmic/bos-core/kd/bos/dataentity/entity";
import { BusinessDataServiceHelper, QueryServiceHelper } from "@cosmic/bos-core/kd/bos/servicehelper";
import { SaveServiceHelper, OperationServiceHelper } from "@cosmic/bos-core/kd/bos/servicehelper/operation";
import { QFilter, QCP } from "@cosmic/bos-core/kd/bos/orm/query";
import { RequestContext } from "@cosmic/bos-core/kd/bos/context";
// BigDecimal 是内置类型，无需导入

完整导入列表（含校验器、控件事件、消息通知等）见 syntax.md。

常用 API 速查

代码质量检查清单

• 正确继承基类
• 导出 plugin 单例：let plugin = new XxxPlugin(); export { plugin };
• 所有重写方法调用 super
• 插件类中无类属性，只有局部变量
• 操作插件中使用的字段已在 onPreparePropertys 中预加载
• 财务计算使用 BigDecimal
• 遵守 SDK 限流规范
• 无 console.log（生产环境）
• 函数简短（< 50 行），文件聚焦（< 800 行）
• 查询接口选择正确（可保存 vs 只读）

KingScript 特殊限制

• 不支持静态变量
• 不支持泛型导入（ArrayList<String> 需写 ArrayList）
• 不要使用 $（全局保留关键字）
• 异常信息不要包含敏感数据

参考文档索引

根据开发需求查阅对应文档：

模块缩写对照