【Python插件入门】第4篇：单据表单插件

往期回顾：

【Python插件入门】第1篇：Python插件入门讲解

【Python插件入门】第2篇：基本开发过程介绍

【Python插件入门】第3篇：插件中如何进行数据操作

    大家好，继续我们的Python插件入门学习，从这一篇开始我们将正式开始进入Python插件代码学习阶段。终于可以一起来写代码啦！前面的几篇介绍了Python插件开发的整个过程，以及一些非常重要的基础知识，不容忽视哦！

【温馨提醒】：有些小伙伴没有仔细看，没消化知识点就漫天问我问题，其实去消化了前面的知识，尤其是第3篇，只要理解了很多数据操作应该都会做了。大家如果真心想学会，又没有太多基础的话，不要急于求成，仔细阅读每一篇文章，一步一个脚印，理解好每一个知识点，最终才能灵活应用。

    言归正传，前面我们学习了Python插件代码的构成"三部曲"，其中比较重要的一部分就是【方法/函数】，再结合上一篇我们学习的插件中对单据的数据包进行操作，就可以实现具体功能了，后面我们将学习各类插件，其实就是学习如何使用【方法/函数】，当然，插件中更多的还是学习使用系统定义好的事件方法，今天我们先来看一看表单插件中的事件方法。

一、表单插件简介

    表单插件是Web服务层插件，需要依赖于单据维护界面(View)才能触发，单据列表不会触发，曾经有小伙伴多次遇到单据下推，下游单据某些数据不能自动生成，就是因为单据转换过程本身是不触发实体服务规则、值更新事件以及表单插件的，遇到一些特别的开发场景需要触发表单插件、实体服务规则、值更新时，有时也会在后台构建单据的界面对象View来进行触发使用(以后会做这方面的分享)，现在先讲一些表单插件的基本用法。

   那么那些业务对象可以使用表单插件呢？表单插件在单据、动态表单、基础资料中都可以注册。

   在熟知的C#插件中，表单插件的基类是AbstractBillPlugIn，C#插件开发时，需要建一个AbstractBillPlugIn的派生类，来实现表单插件，而在开发Python插件时，在注册表单插件的位置注册Python脚本系统就默认是表单插件了，不需要过多考虑基类，所以我们需要更关注需要实现的事件方法。

二、表单插件中的重要成员介绍

    插件基类为我们提供了许多重要的成员供开发时使用，下面介绍一下常用的一些属性和用法。

    在插件中可以通过this关键字来调用这些成员。

• Context:上下文对象

    this.Context.UserId;#当前用户ID
    this.Context.UserName;#当前用户名称
    this.Context.UserPhone;#当前用户手机号
    this.Context.CurrentOrganizationInfo.ID;#当前组织Id
    this.Context.CurrentOrganizationInfo.Name;#当前组织名称
    this.Context.DBId;#当前数据中心Id
    this.Context.DataCenterNumber;#当前数据中心编码
    this.Context.DataCenterName;#当前数据中心名称
    this.Context.IpAddress;#客户端本机网络信息:IP、MAC等

• View:视图层对象,可理解为当前界面,界面类插件特有，服务类的插件没有这个，View能为开发提供很多特有的功能。

    ①View的常用属性

    this.View.BillBusinessInfo;#单据的业务逻辑元数据，元数据包含的信息很多,下面列了一下常用的信息
    this.View.BillBusinessInfo.GetBillNoField().FieldName;#单据编号字段名
    this.View.BillBusinessInfo.GetBillStatusField().FieldName;#单据状态字段名
    this.View.BillBusinessInfo.GetBillTypeField().FieldName;#单据类型字段名
    this.View.BillBusinessInfo.GetForm().Id;#单据FormId
    this.View.BillBusinessInfo.MainOrgField.FieldName;#主业务组织字段名
    this.View.BillBusinessInfo.GetEntity("FBillHead").TableName;#单据头表名
    this.View.BillBusinessInfo.GetEntity("实体标识").TableName;#实体主表名
    this.View.BillBusinessInfo.GetEntity("实体标识").SplitTables;#实体所有拆分表

    #****************************************************************************************************

    this.View.OpenParameter;#表单入口参数
    this.View.OpenParameter.Status;#当前界面状态:0,新增;1,查看;2,修改;
    this.View.OpenParameter.GetCustomParameter("参数标识");#获取单据打开传入的参数

    #****************************************************************************************************

    this.View.ParentFormView;#获取父页面的View
    this.View.ParentFormView.BillBusinessInfo.GetForm().Id;#父页面的FormId,用来判断单据是从哪里进来的

    ②View的常用方法

    this.View.GetFormTitle();#获取单据标题
    this.View.SetFormTitle(LocaleValue("新标题"));#修改单据标题

    this.View.GetFormOperation("操作代码");#获取单据的一个操作实例对象
    this.View.InvokeFormOperation("操作代码");#触发单据的某个操作:保存、提交、审核、关闭 等!
    this.View.GetControl[控件类]("控件标识");#获取单据上的控件:按钮、菜单等,可用来设置控件的状态(可见性，锁定性等)
    this.View.InvokeFieldUpdateService("字段标识",行号);#触发字段值更新，单据头字段行号填0
    #触发实体服务规则，下面2行代码
    obj=BOSActionExecuteContext(this.View);
    this.View.RuleContainer.RaiseDataChanged("字段标识", 字段所在实体行数据包,obj);#触发实体服务规则

    #显示3种提示信息
    this.View.ShowMessage("绿色背景提示信息");#显示正常提示信息
    this.View.ShowWarnningMessage("黄色背景提示信息");#显示警告提示信息
    this.View.ShowErrMessage("红色背景提示信息");#显示错误提示信息

    #刷新界面数据，修改实体数据包后需要刷新重新读取，必须传标识，不建议粗暴刷新整个单据

    this.View.UpdateView("字段标识/单据体标识");#刷新界面数据

• Model:单据数据模型,很重要，单据的实体数据包获取从这里开始，结合上1篇所讲的实体数据包。

    this.View.Model;#单据数据模型,很重要，单据的实体数据包获取从这里开始，结合上文
    this.View.Model.DataObject;#单据的完整数据包，相当于前面讲的单据头实体数据包

    this.View.Model.GetEntryCurrentRowIndex("单据体标识");#获取单据体当前焦点行号
    this.View.Model.GetEntryRowCount("单据体标识");#获取单据体行数
    this.View.Model.CreateNewEntryRow("单据体标识");#为单据体新增一行
    this.View.Model.BatchCreateNewEntryRow("单据体标识",x);#批量为单据体新增x行
    this.View.Model.InsertEntryRow("单据体标识", i);#在第i行前插入1行
    this.View.Model.DeleteEntryRow("单据体标识", i);#删除第i行
    this.View.Model.DeleteEntryData("单据体标识");#清空整个单据体数据

    #获取第x行(单据头不传x)某字段的值，不同字段类型返回不同类型数据，参考第3篇讲解

    this.View.Model.GetValue("字段标识",x);

    #更新第x行(单据头不传x)某字段的值，不同字段类型赋值不同类型数据，参考第3篇讲解

    this.View.Model.SetValue("字段标识","字段值",x);
    this.View.Model.SetItemValueByID("字段标识","内码id",x);#用资料内码id更新第x行资料字段的值
    this.View.Model.SetItemValueByNumber("字段标识","编码",x);#用资料编码更新第x行资料字段的值

上面对表单插件常用的一些属性和方法做了一下介绍，其实还有很多，这里篇幅有限，也列举不完，用得最多的基本就在这里了，我们可以发现，除了第3篇将的实体数据包操作之外，在表单插件中，我们有另外的方法对单据的数据进行操作，需要注意的是，表单插件中的这些方法使用的都是标识，而不是绑定实体属性名了，当然，在表单插件中实体数据包操作同样适用，并且用的时候也很多，不要觉得表单插件这些方法便捷好理解，就"捡了芝麻丢了西瓜哦！"。

三、新建一个表单插件

    我们先新建一个Python表单插件，然后就可以进行下面讲解的内容进行测试验证啦！

• 注意：我这里提供一个引用比较全的Python插件示例模板，在附件中可以下载示例代码，复制到BOS里面注册！

• Python表单插件注册方法：如下图所示，还是以采购订单为例，其他单据类似

四、表单插件常用事件介绍

    有了前面讲解的这些单据数据操作方法是不是想赶紧验证一下呢，要在插件中触发这些代码，我们需要通过插件事件来作为入口，表单插件的事件也很多，这里介绍一下表单插件中最常用的一些事件，用来实现常见的需求场景够用啦！

• 表单插件中的基本事件：自动触发，一定会触发，按顺序触发。

  插件中的事件在单据运行过程中产生的，所以一些事件有固定执行顺序，且在不同阶段才能获取到特定的数据。

  单据新增界面打开	单据修改/查看打开	事件描述
  PreOpenForm	PreOpenForm	准备单据打开
  OnInitializeService	OnInitializeService	加载单据插件等，这里可以动态调整插件执行顺序等
  OnSetBusinessInfo	OnSetBusinessInfo	绑定单据元数据
  OnSetLayoutInfo	OnSetLayoutInfo	设置单据界面显示信息，如布局等
  OnCreateDataBinder	OnCreateDataBinder	创建数据源绑定对象
  OnInitialize	OnInitialize	单据初始化完毕，在这里可以获取一些控件备用
  OnBillInitialize	OnBillInitialize	单据初始化完毕
  CreateNewData		构建新单据初始实体数据，新增才会触发
  AfterCreateNewData		新单据初始实体数据构建完毕,在此可修改单据默认数据
  AfterCreateModelData		新单据实体数据构建到Model
  	LoadData	开始加载单据实体数据
  	AfterLoadData	加载完单据数据
  OnLoad	OnLoad
  BeforeBindData	BeforeBindData	开始绑定实体数据到界面控件
  AfterBindData	AfterBindData	绑定实体数据到界面控件完毕，尽量不要在此事件中修改数据，仅修改控件的状态(可见性、锁定性、颜色等)

• Python插件中如何使用事件

    ①事件就是定义好的方法，所以使用def关键字，后面跟上方法名称、参数列表即可，表单插件的事件一般没有返回值。

    ②事件方法参数：在参数中我们能获取到当前事件应该提供信息，表单插件事件一般只有1个参数，在BOS写会提示。

    ③参数名，用"e"即可。

    ④示例：def AfterCreateModelData(e): ，注意最后有英文冒号":"结尾，如果忘记Python的语法要点，看第2篇。

• 表单插件中的常用事件用法介绍：下面列出的事件中都可以获取到单据数据包

#单据新增界面打开时触发，可以获取到单据初始化之后的数据
#通常用于对单据新增进行默认值填充，例如，设置默认日期，填充单据体默认数据等

#应用案例:Python获取当前用户对应的员工
def AfterCreateModelData(e):
    billObj = this.Model.DataObject;#单据完整数据包,如需通过实体数据包操作读写数据,可从这里开始取
    this.View.Model.SetValue("FDate", "2022-7-1");#设置默认日期
    #msg=("{0}").format(this.View.BillBusinessInfo.GetEntity("FBillHead").TableName);
    #this.View.ShowMessage(msg);

#界面数据绑定完毕后触发，通常在这里对字段控件状态进行设置
#例如,设置颜色、设置字段锁定性/可见性、设置下拉列表动态枚举选项等
def AfterBindData(e):
    this.View.GetControl("FDate").Enabled=False;#False:锁定,True:解锁
    #this.View.GetControl("控件标识").Visible=False;#False:隐藏,True:显示

#单据头菜单点击事件，从参数e中获取菜单标识，来判断是哪个菜单发生了点击
#这里一定要加判断，只需要监听需要的菜单,多个菜单的话，使用if elif结构,Python中没有Switch结构

#应用案例:点击菜单弹出动态表单传递参数到子页面
def BarItemClick(e):
    key=e.BarItemKey.ToUpperInvariant();#菜单标识大写
    if(key=="TESTBTN1".ToUpperInvariant()):
        msg=("菜单[{0}]点击事件捕捉到了，可以继续菜单的功能啦！").format(key);
        this.View.ShowMessage(msg);
    elif(key=="TESTBTN2".ToUpperInvariant()):
        msg