From cbfaa3cda51732daff03bf55323498a9edbf3da7 Mon Sep 17 00:00:00 2001 From: unknown Date: Mon, 21 Dec 2020 14:54:10 +0800 Subject: [PATCH] jsdoc --- .../source/o2_core/o2/xScript/Environment.js | 219 +++++++++++++++++- .../x_component_process_Xform/$Module.js | 40 ++-- .../x_component_process_Xform/Address.js | 14 +- .../x_component_process_Xform/Attachment.js | 16 ++ .../x_component_process_Xform/Checkbox.js | 2 +- .../x_component_process_Xform/Combox.js | 53 ++++- .../source/x_component_process_Xform/Form.js | 58 ++++- 7 files changed, 374 insertions(+), 28 deletions(-) diff --git a/o2web/source/o2_core/o2/xScript/Environment.js b/o2web/source/o2_core/o2/xScript/Environment.js index 04ff7b4b57..710268be3c 100644 --- a/o2web/source/o2_core/o2/xScript/Environment.js +++ b/o2web/source/o2_core/o2/xScript/Environment.js @@ -1,3 +1,186 @@ +/** + * Work 数据结构，流程实例对象 + * @typedef {Object} Work + * @example + * { + "id": "854e2c22-718e-48bb-98db-96f4b43e7ee8", //流程实例ID + "splitValue": "xxxxxxxxxxxxxx", //流程拆分后的拆分依据 + "title": "xx7月北京出差报销审批", //流程实例名称 + "startTime": "2018-09-07 14:03:22", //流程启动时间 + "startTimeMonth": "2018-09", //流程启动的月份 + "creatorPerson": "xx@huqi@P", //流程实例创建人 + "creatorIdentity": "xx@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //流程实例创建人身份 + "creatorUnit": "xx@c448d8bb-98b8-4305-9d3f-12537723cfcc@U", //流程实例创建人所在组织 + "creatorUnitLevelName": "浙江兰德纵横/开发部", //流程实例创建人所在组织层次 + "application": "1dc23336-6be6-402b-bed6-36e707a1dd17", //流程应用ID + "applicationName": "财务管理", //流程应用名称 + "applicationAlias": "finance", //流程应用别名 + "process": "2207db11-dddf-4ebd-864d-3819f3e173c6", //流程ID + "processName": "报销审批流程", //流程名称 + "processAlias": "", //流程别名 + "activity": "13d15daf-2ac5-4c1b-a669-1607a0e5ed15", //当前活动ID + "activityType": "manual", //当前活动类型 + "activityName": "部门领导审核", //当前活动名称 + "activityAlias": "", //当前活动别名 + "activityDescription": "", //当前活动描述 + "activityArrivedTime": "2018-09-27 22:49:21", //当前活动到达时间 + "serial": "", //编号 + "workStatus": "processing", //流程实例状态 + "errorRetry": 0, //流转失败重试次数 + "splitting": false, //流程是否拆分 + "form": "db3b2766-93a1-4058-b522-0edb922bd84f", //流程展现所使用的表单 + "manualTaskIdentityList" : "张三@db3b2766-93a1-4058-b522-0edb922bd84f@I", //预期的处理人 + "manualTaskIdentityText" : "张三" //当前处理人身份合并文本,用','分割,超长截断,此字段仅用于显示当前工作的处理人,不索引. +} + */ + +/** + * WorkCompleted 数据结构，已结束流程实例对象 + * @typedef {Object} WorkCompleted + * @example + * { + "id": "be0195f1-f2e2-4eac-911c-99897a43ff8f", //流程实例ID + "title": "xx7月北京出差报销审批", //流程实例名称 + "startTime": "2018-09-19 16:14:16", //流程启动时间 + "startTimeMonth": "2018-09", //流程启动的月份 + "completedTime": "2018-09-19 16:15:28", //流程完成时间 + "completedTimeMonth": "2018-09", //流程完成的月份 + "creatorPerson": "xx@huqi@P", //流程实例创建人 + "creatorIdentity": "xx@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //流程实例创建人身份 + "creatorUnit": "xx@c448d8bb-98b8-4305-9d3f-12537723cfcc@U", //流程实例创建人所在组织 + "creatorUnitLevelName": "浙江兰德纵横/开发部", //流程实例创建人所在组织层次 + "application": "1dc23336-6be6-402b-bed6-36e707a1dd17", //流程应用ID + "applicationName": "财务管理", //流程应用名称 + "applicationAlias": "finance", //流程应用别名 + "process": "2207db11-dddf-4ebd-864d-3819f3e173c6", //流程ID + "processName": "报销审批流程", //流程名称 + "processAlias": "", //流程别名 + "serial": "", //编号 + "form": "320be1ca-ee49-478f-a751-f65ab67cf818", //流程展现所使用的表单 +} + */ + +/** + * Task数据结构，待办任务对象 + * @typedef {Object} Task + * @example + * { + "id": "dd476045-7c79-44f7-9dba-f51d322de40f", //待办ID + "title": "XX7月北京出差报销审批", //流程实例标题 + "startTime": "2018-09-27 22:49:22", //待办到达时间 + "startTimeMonth": "2018-09", //待办到达的月份 + "work": "854e2c22-718e-48bb-98db-96f4b43e7ee8", //流程实例ID + "application": "1dc23336-6be6-402b-bed6-36e707a1dd17", //流程应用ID + "applicationName": "财务管理", //流程应用名称 + "applicationAlias": "finance", //流程应用别名 + "process": "2207db11-dddf-4ebd-864d-3819f3e173c6", //流程ID + "processName": "报销审批流程", //流程名称 + "processAlias": "", //流程别名 + "serial": "", //流程编号 + "person": "XXX@huqi@P", //待办人名称 + "identity": "XX@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //待办人身份 + "unit": "XX@c448d8bb-98b8-4305-9d3f-12537723cfcc@U", //待办人所在组织 + "activity": "13d15daf-2ac5-4c1b-a669-1607a0e5ed15", //当前活动的ID + "activityName": "部门领导审核", //当前活动的名称 + "activityAlias": "", //当前活动的别名 + "activityDescription": "", //当前活动描述 + "activityType": "manual", //当前活动类型 + "creatorPerson": "XX@huqi@P", //流程实例创建人 + "creatorIdentity": "XX@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //流程实例创建人的身份 + "creatorUnit": "XX@c448d8bb-98b8-4305-9d3f-12537723cfcc@U", //流程实例创建人所在组织 + "expired": false, //是否已超时 + "urged": false, //是否进行催办 + "routeList": [ //可选的路由ID + "89b58fe0-6dcb-4fe7-8c2e-3f77204df6d4", + "f3105b7a-2929-4682-aab8-15fef5ea0f23" + ], + "routeNameList": [ //可选的路由名称 + "退回申请人", + "送财务部门复审" + ], + "routeOpinionList": [ //可选路由的默认意见 + "", + "" + ], + "first" : true, //是否是第一条待办. + "properties": { //属性对象存储字段 + "prevTaskIdentity": "张三@903dbb04-085c-4bb1-9c24-3009bd5f7372@I", //提交的处理人 + "prevTaskIdentityList": [ //上一步处理人 + "张三@903dbb04-085c-4bb1-9c24-3009bd5f7372@I" + ], + "prevTaskList": [ //上一步任务信息 + { + "routeName": "送办理", + "unit": "产品研发组@320189216@U", + "identity": "张三@903dbb04-085c-4bb1-9c24-3009bd5f7372@I", + "person": "张三@zhangsan@P", + "opinion": "", + "startTime": "2020-09-29 17:03:14", + "completedTime": "2020-09-29 17:04:38" + } + ], + "prevTask": { //提交的任务信息 + "routeName": "送办理", + "unit": "产品研发组@320189216@U", + "identity": "张三@903dbb04-085c-4bb1-9c24-3009bd5f7372@I", + "person": "张三@zhangsan@P", + "opinion": "", + "startTime": "2020-09-29 17:03:14", + "completedTime": "2020-09-29 17:04:38" + } + } + * } + */ + +/** + * Read 数据结构，待阅任务对象 + * @typedef {Object} Read + * @example + * { + "id": "dd476045-7c79-44f7-9dba-f51d322de40f", //待阅ID + "title": "XX7月北京出差报销审批", //流程实例标题 + "startTime": "2018-09-27 22:49:22", //待阅产生时间 + "startTimeMonth": "2018-09", //待阅产生的月份 + "work": "854e2c22-718e-48bb-98db-96f4b43e7ee8", //流程实例ID + "application": "1dc23336-6be6-402b-bed6-36e707a1dd17", //流程应用ID + "applicationName": "财务管理", //流程应用名称 + "applicationAlias": "finance", //流程应用别名 + "process": "2207db11-dddf-4ebd-864d-3819f3e173c6", //流程ID + "processName": "报销审批流程", //流程名称 + "processAlias": "", //流程别名 + "completed": false, //流程是否已完成 + "serial": "", //流程编号 + "person": "XXX@huqi@P", //待阅人名称 + "identity": "XX@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //待阅人身份 + "unit": "XX@c448d8bb-98b8-4305-9d3f-12537723cfcc@U", //待阅人所在组织 + "activity": "13d15daf-2ac5-4c1b-a669-1607a0e5ed15", //当前活动的ID + "activityName": "部门领导审核", //当前活动的名称 + "activityAlias": "", //当前活动的别名 + "activityDescription": "", //当前活动描述 + "activityType": "manual", //当前活动类型 + "creatorPerson": "XX@huqi@P", //流程实例创建人 + "creatorIdentity": "XX@481c9edc-5fb5-41f1-b5c2-6ea609082cdb@I", //流程实例创建人的身份 + "creatorUnit": "XX@c448d8bb-98b8-4305-9d3f-12537723cfcc@U" //流程实例创建人所在组织 +} + */ + +/** +* Activity 数据结构，流程实例所在的活动节点对象 + * @typedef {Object} Activity + * @example + * + { + "id": "801087c5-a4e6-4b91-bf4d-a81cdaa04471", //节点ID + "name": "办理", //节点名称 + "description": "", //节点描述 + "alias": "", //节点别名 + "resetRange": "department", //重置处理人范围 + "resetCount": 0, //重置处理人数字 + "allowReset": true, //是否允许重置 + "manualMode": "single" //处理方式 单人single, 并行parallel, 串行queue, grab抢办 + } + */ + MWF.xScript = MWF.xScript || {}; MWF.xScript.Environment = function(ev){ var _data = ev.data; @@ -58,11 +241,37 @@ MWF.xScript.Environment = function(ev){ * @summary 获取当前流程与当前用户相关的待办对象：task对象。 * @method getTask * @static - * @return {string} The blended color. + * @return {(Task|Null)} 当前用户的待办任务对象：task。当前用户没有对此流程实例的待办时，或流程实例已经流转结束，返回null. + * @example + * var task = this.workContext.getTask(); */ "getTask": function(){return ev.task || null;}, + /** + * 获取当前流程实例对象：work对象或workCompleted对象。 + * @method getWork + * @static + * @return {(Work|WorkCompleted)} 流程实例对象；如果流程已结束，返回已结束的流程实例对象. + * @example + * var work = this.workContext.getWork(); + */ "getWork": function(){return ev.work || ev.workCompleted;}, + /** + * 获取当前流程实例所在的活动节点对象：activity对象。 + * @method getActivity + * @static + * @return {(Activity|Null)} 当前流程实例所在的活动节点对象，如果当前流程实例已流转完成，则返回null. + * @example + * var activity = this.workContext.getActivity(); + */ "getActivity": function(){return ev.activity || null;}, + /** + * 获取当前流程实例的所有待办对象。如果流程实例已流转完成，则返回一个空数组。 + * @method getTaskList + * @static + * @return {(Task[])} 待办任务列表. + * @example + * var taskList = this.workContext.getTaskList(); + */ "getTaskList": function(callback, error){ var cb = (callback && o2.typeOf(callback)==="function") ? callback : null; var ecb = (error && o2.typeOf(error)==="function") ? error : null; @@ -73,6 +282,14 @@ MWF.xScript.Environment = function(ev){ }, ecb, !!cb); return list; }, + /** + * 根据当前工作的job获取当前流程实例的所有待办对象。如果流程实例已流转完成，则返回一个空数组。 + * @method getTaskListByJob + * @static + * @return {(Task[])} 待办任务列表. + * @example + * var taskList = this.workContext.getTaskListByJob(); + */ "getTaskListByJob": function(callback, error){ var cb = (callback && o2.typeOf(callback)==="function") ? callback : null; var ecb = (error && o2.typeOf(error)==="function") ? error : null; diff --git a/o2web/source/x_component_process_Xform/$Module.js b/o2web/source/x_component_process_Xform/$Module.js index b8c6169095..b4360c7dfb 100644 --- a/o2web/source/x_component_process_Xform/$Module.js +++ b/o2web/source/x_component_process_Xform/$Module.js @@ -8,28 +8,24 @@ MWF.xApplication.process.Xform.$Module = MWF.APP$Module = new Class( { Implements: [Events], options: { - // /** - // * 组件加载前事件。
- // * 平台执行queryLoad事件的时候，组件还没有开始加载，这个时候可以根据条件修改组件的配置信息 - // * @event MWF.xApplication.process.Xform.$Module#queryLoad - // * @example - // * var field = this.form.get("fieldName"); - // * field.addEvent("queryLoad", function(){ - // * - // * }; - // */ - // /** - // * Event reporting that a snowball has been hurled. - // * - // * @event MWF.xApplication.process.Xform.$Module#load - // * @property {number} velocity - The snowball's velocity, in meters per second. - // */ - // /** - // * Event reporting that a snowball has been hurled. - // * - // * @event MWF.xApplication.process.Xform.$Module#postLoad - // * @property {number} velocity - The snowball's velocity, in meters per second. - // */ + /** + * 组件加载前事件。
+ * 平台执行queryLoad事件的时候，组件还没有开始加载，这个时候可以根据条件修改组件的配置信息以改变加载细节。 + * @event MWF.xApplication.process.Xform.$Module#queryLoad + * @example + * var field = this.form.get("fieldName"); + * field.addEvent("queryLoad", function(){ + * + * }; + */ + /** + * 组件加载事件. + * @event MWF.xApplication.process.Xform.$Module#load + */ + /** + * 组件加载后事件. + * @event MWF.xApplication.process.Xform.$Module#postLoad + */ "moduleEvents": ["load", "queryLoad", "postLoad"] }, initialize: function(node, json, form, options){ diff --git a/o2web/source/x_component_process_Xform/Address.js b/o2web/source/x_component_process_Xform/Address.js index 940a92acbd..0d2a774747 100644 --- a/o2web/source/x_component_process_Xform/Address.js +++ b/o2web/source/x_component_process_Xform/Address.js @@ -1,6 +1,18 @@ //MWF.require("MWF.widget.PinYin", null, false); MWF.xDesktop.requireApp("process.Xform", "Combox", null, false); -MWF.xApplication.process.Xform.Address = MWF.APPAddress = new Class({ +/** @class Address 地址选择组件。 + * @example + * //可以在脚本中获取该组件 + * //方法1： + * var address = this.form.get("name"); //获取组件 + * //方法2 + * var address = this.target; //组件本身的事件和脚本中获取 + * @extends MWF.xApplication.process.Xform.Combox + * @hideconstructor + */ +MWF.xApplication.process.Xform.Address = MWF.APPAddress = new Class( + /** @lends MWF.xApplication.process.Xform.Address# */ + { Implements: [Events], Extends: MWF.APPCombox, options: { diff --git a/o2web/source/x_component_process_Xform/Attachment.js b/o2web/source/x_component_process_Xform/Attachment.js index 7ea82b022a..c9bc46bedf 100644 --- a/o2web/source/x_component_process_Xform/Attachment.js +++ b/o2web/source/x_component_process_Xform/Attachment.js @@ -1051,7 +1051,23 @@ MWF.xApplication.process.Xform.AttachmentController = new Class({ * @property {String} createTime - 创建时间. * @property {String} updateTime - 修改时间. * @property {String} extension - 附件扩展名. + * @example + * { + "id": "56c4e86f-a4c8-4cc2-a150-1a0d2c5febcb", //附件ID + "name": "133203a2-92e6-4653-9954-161b72ddb7f9.png", //附件名称 + "extension": "png", //附件扩展名 + "length": 43864, //附件大小 + "person": "xx@huqi@P", //附件上传人 + "lastUpdateTime": "2018-09-27 15:50:34", //最后的修改时间 + "lastUpdatePerson": "xx@huqi@P", //最后的修改人 + "activity": "e31ad938-c495-45a6-8d77-b8a9b61a165b", //附件上传的活动ID + "activityName": "申请人", //附件上传的活动名称 + "activityType": "manual", //附件上传的活动类型 + "site": "$mediaOpinion", //附件存储位置（一般用于区分附件在哪个表单元素中显示） + "type": "image/png" //附件类型（contentType） +} */ + /** @class Actionbar 附件组件。 * @example * //可以在脚本中获取该组件 diff --git a/o2web/source/x_component_process_Xform/Checkbox.js b/o2web/source/x_component_process_Xform/Checkbox.js index 8563dfe533..6658b73e5b 100644 --- a/o2web/source/x_component_process_Xform/Checkbox.js +++ b/o2web/source/x_component_process_Xform/Checkbox.js @@ -110,7 +110,7 @@ MWF.xApplication.process.Xform.Checkbox = MWF.APPCheckbox = new Class( * @summary 获取选择项数组. * @example * var array = this.form.get('fieldName').getOptions(); - * @return {Array} 选择项数组，如果是脚本返回计算结果. + * @return {Array} 选择项数组，如果配置为脚本返回计算结果. */ getOptions: function(){ if (this.json.itemType == "values"){ diff --git a/o2web/source/x_component_process_Xform/Combox.js b/o2web/source/x_component_process_Xform/Combox.js index cf2598400f..e9654713d0 100644 --- a/o2web/source/x_component_process_Xform/Combox.js +++ b/o2web/source/x_component_process_Xform/Combox.js @@ -1,5 +1,17 @@ MWF.xDesktop.requireApp("process.Xform", "$Input", null, false); -MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class({ +/** @class Combox 组合框组件。 + * @example + * //可以在脚本中获取该组件 + * //方法1： + * var field = this.form.get("fieldName"); //获取组件对象 + * //方法2 + * var field = this.target; //在组件本身的脚本中获取，比如事件脚本、默认值脚本、校验脚本等等 + * @extends MWF.xApplication.process.Xform.$Input + * @hideconstructor + */ +MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class( + /** @lends MWF.xApplication.process.Xform.Combox# */ +{ Implements: [Events], Extends: MWF.APP$Input, iconStyle: "selectIcon", @@ -80,6 +92,12 @@ MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class({ return null; } }, + /** + * @summary 获取选择项数组. + * @example + * var array = this.form.get('fieldName').getOptions(); + * @return {Array} 选择项数组，如果配置为脚本返回计算结果. + */ getOptions: function(){ var list = []; if (this.json.itemType === "values"){ @@ -126,6 +144,20 @@ MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class({ } return []; }, + /** + * 当表单上没有对应组件的时候，可以使用this.data[fieldName] = data赋值。 + * @summary 为组件赋值。 + * @param value{String} . + * @example + * this.form.get("fieldName").setData("test"); //赋文本值 + * @example + * //如果无法确定表单上是否有组件，需要判断 + * if( this.form.get('fieldName') ){ //判断表单是否有无对应组件 + * this.form.get('fieldName').setData( data ); + * }else{ + * this.data['fieldName'] = data; + * } + */ setData: function(value){ this._setBusinessData(value); this._setValue(value); @@ -166,13 +198,24 @@ MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class({ }.bind(this)); } }, + /** + * @summary 重新计算下拉选项，该功能通常用在下拉选项为动态计算的情况. + * @example + * this.form.get('fieldName').resetOption(); + */ resetOption: function(){ if (this.combox){ var list = this.getOptions(); this.combox.setOptions({"list": list}); } }, - + /** + * @summary 添加下拉选项. + * @param text {String} 下拉选项文本 + * @param value {String} 下拉选项值 + * @example + * this.form.get('fieldName').addOption("秘密","level1"); + */ addOption: function(text, value){ if (this.combox){ var list = this.getOptions(); @@ -195,6 +238,12 @@ MWF.xApplication.process.Xform.Combox = MWF.APPCombox = new Class({ if (this.combox) return this.combox.getData(); return this._getBusinessData(); }, + /** + * @summary 获取选中的值和文本. + * @example + * var array = this.form.get('fieldName').getTextData(); + * @return {Object} 返回选中项值和文本，格式为 { 'value' : value, 'text' : text }. + */ getTextData: function(){ var v = this.getData(); return {"value": v, "text": v}; diff --git a/o2web/source/x_component_process_Xform/Form.js b/o2web/source/x_component_process_Xform/Form.js index a5a6576568..73b05b15cd 100644 --- a/o2web/source/x_component_process_Xform/Form.js +++ b/o2web/source/x_component_process_Xform/Form.js @@ -5,7 +5,17 @@ MWF.xApplication.process.Xform = MWF.xApplication.process.Xform || {}; MWF.xDesktop.requireApp("process.Xform", "lp." + MWF.language, null, false); //MWF.xDesktop.requireApp("process.Xform", "Package", null, false); -MWF.xApplication.process.Xform.Form = MWF.APPForm = new Class({ +/** @class Form 表单。 + * @example + * //可以在脚本中获取表单 + * //方法1： + * var form = this.form.getApp().appForm; //获取表单 + * //方法2 + * var form = this.target; //在表单本身的事件脚本中获取 + */ +MWF.xApplication.process.Xform.Form = MWF.APPForm = new Class( + /** @lends MWF.xApplication.process.Xform.Form# */ +{ Implements: [Options, Events], Extends: MWF.widget.Common, options: { @@ -41,10 +51,27 @@ MWF.xApplication.process.Xform.Form = MWF.APPForm = new Class({ initialize: function (node, data, options) { this.setOptions(options); + /** + * @summary 表单容器 + * @see https://mootools.net/core/docs/1.6.0/Element/Element + * @member {Element} + * @example + * //可以在脚本中获取表单容器 + * var formContainer = this.form.getApp().appForm.container; + */ this.container = $(node); this.container.setStyle("-webkit-user-select", "text"); if (Browser.firefox) this.container.setStyle("opacity", 0); this.data = data; + + /** + * @summary 表单的配置信息，比如表单名称，提交方式等等. + * @member {JsonObject} + * @example + * //可以在脚本中获取表单配置信息 + * var json = this.form.getApp().appForm.json; //表单配置信息 + * var name = json.name; //表单名称 + */ this.json = data.json; this.html = data.html; @@ -53,7 +80,36 @@ MWF.xApplication.process.Xform.Form = MWF.APPForm = new Class({ this._loadCss(); this.sectionListObj = {}; + + /** + * @summary 表单中的所有组件数组. + * @member {Array} + * @example + * //下面的样例对表单组件进行循环，并且判断是输入类型的组件 + * var modules = this.form.getApp().appForm.modules; //获取所有表单组件 + * for( var i=0; i + * 需要注意的是，在子表单中嵌入不绑定数据的组件（比如div,common,button等等），系统允许重名。
+ * 在打开表单的时候，系统会根据重名情况，自动在组件的标识后跟上 "_1", "_2"。 + * @summary 表单中的所有组件对象. + * @member {Object} + * @example + * var moduleAll = this.form.getApp().appForm.all; //获取组件对象 + * var subjectField = moduleAll["subject"] //获取名称为subject的组件 + */ this.all = {}; this.allForName = {}; this.forms = {}; -- GitLab