moqui从入门到精通--组件简介

逃离我推掉我的手 2023-02-21 11:54 50阅读 0赞

一，Entity    2

1，定义实体    2

2，实体字段的定义    3

3，定义索引 4

4，定义外键    5

4.1 relationship    5

4.2 key-map    5

5，添加数据    6

5.1 seed-data    6

5.2 entity-facade-xml    6

6，实体的类型    7

7，实体的CrUD操作    7

7.1 entity-find-one：    8

7.2 entity-find：    8

7.3 entity-find-count：    11

7.4 entity-make-value：    11

7.5 entity-create：    11

7.6 entity-update：    12

7.7 entity-delete：    12

7.8 entity-delete-by-condition：    12

7.9 entity-set：    12

7.10 entity-sequenced-id-primary：    12

7.11 entity-sequenced-id-secondary：    12

8，实体的扩展    12

9，视图实体    13

二，service    14

1，service定义    14

1.1 in-parameters    17

1.2 out-parameters    17

1.3 parameters    17

1.4 actions    19

2，服务实现    21

2.1 内联动作实现服务    21

2.2 groovy脚本服务实现    22

2.3 实体的自动服务    23

3,服务的调用    24

三，xml表单    24

1，单个表单    25

2，列表表单    27

3，表单字段    29

3.1 字段组件    30

一，Entity  
实体相当于数据库中的表，并主要被定义在 XML 文件中。 这些定义包含了罗列实体中的字段，实体间的关系，指定索引等。实体门面用于普通的数据库交互，例如新增/修改/删除以及查找操作。

1，定义实体  
实体定义的xml文件放在组件的entity目录下，定义的语法如下：

<entity entity-name="ExampleItem" package="moqui.example" short-alias="exampleItems">  
    <field name="exampleId" type="id" is-pk="true"/>  
    <field name="exampleItemSeqId" type="id" is-pk="true"><description>secondary sequenced ID</description></field>  
    <field name="description" type="text-medium"/>  
    <field name="amount" type="number-float"/>  
    <field name="amountUomId" type="id"/>  
    <relationship type="one" title="Amount" related="moqui.basic.Uom">  
        <key-map field-name="amountUomId"/></relationship>  
    <relationship type="one" related="moqui.example.Example"/>  
</entity>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
实体就像一个Java类，有包名+实体名，格式为package−name. \{package-name\}.package−name.\{entity-name\}

entity用来定义一个实体，里面的属性有：

entity-name:实体名称

package:实体所在的包名

authorize-skip: 用来设置实体的操作权限，可以有以下的值：

true：略过实体的所有权限校验

false：不略过权限校验

create:为新建操作略过权限校验

view:为查询和只读操作略过权限校验

view-create:为查询和新建操作略过权限校验

cache：为实体设置缓存，可选的值有：

true: 使用缓存查找（代码可覆盖）

false: 不用缓存查找（代码可覆盖）

never: 不用缓存查找（代码不可覆盖）

create-only：boolean类型，为true时，该实体只可以被创建，不可以修改和删除

short-alias：实体的别名，主要用于REST URL，但可能会被这个引用。在所有定义的体中必须是唯一的。 如果找到重复的稍后加载实体将被使用。应该简短，以小写字母开头，并且是所选单词的复数形式。

use:实体的预期用途，按照我的理解是该实体的操作是否采用事物，

默认值是transactional，可选的值有：

transactional：采用事物， 需要原子操作的实体，直接一致性等; 通常不会被缓存。

nontransactional：一般不需要采用事物的实体，最终的一致性是足够的。可能被缓存; 非事物并不意味着事物不被使用，但严格的一致性并不重要。

configuration：框架和应用程序来配置数据，最终的一致性是可以保证的，通常会被缓存。

analytical：分析实体与数据，通常来自事物的数据。

group-name: 实体门面（Entity Facade） 用来将一个实体为某个数据库放入分组中，所有数据库都可用。这个值应当匹配 Moqui XML 配置文件中的 moquiconf.entity-facade.datasource.group-name 元素。 如果没有值被指定，那么将默认使用 moqui-conf.entity-facade.default-group-name 元素的值。 配置默认可用的值包括： transactional (默认的)， analytical， tenantcommon 以及 nosql 。

sequence-primary-prefix：应用于此实体的主要排序ID值的前缀。可以是当前值添加到上下文中的表达式（字符串扩展）。

sequence-bank-size:保存在内存中的序列储库的大小。每当在SequenceValueItem 记录中的序列号 seqNum 被内存中的储库消耗完了，将按照这个数量进行增加。

sequence-primary-stagger: 最大数量的交错就是序列 ID。如果增长序列为 1则会增加 1，此外，当前的序列号 ID 还以按照一个 1 和最大间隔之间的随机数来进行增长。

sequence-secondary-padded-length: 如果指定了前垫部分，后面都以零进行填充到本属性指定的长度，默认长度为2。

optimistic-lock: 当设置为 true，实体门面（Entity Facade） 在更新记录时，会比较在内存中的 lastUpdatedStamp 字段和数据库中相同的字段。如果时间戳不相匹配那么会产生一个错误。默认为” false”（无时间戳锁机制）。

no-update-stamp: 实体门面（Entity Facade） 默认的为每个实体添加一个字段（lastUpdatedStamp） 用于乐观锁机制以及数据同步。如果你不想要为实体创建这个标记字段这可以设置这个属性为” false” 。

2，实体字段的定义  
定义完实体之后，开始定义实体字段，

<field name="exampleId" type="id" is-pk="true"><description>primary sequenced ID</description></field>  
1  
采用entity.field元素，其中包含的属性有：

name:实体字段名称，必要属性

type:字段对应数据类型，必要属性，常见的值有：id,text-medium,text-long,text-very-long,number-integer,date-time,date,time,Integer, Long, Float, Double, BigDecimal, BigInteger, Boolean ,List, Map, Set ,string等

is-pk:表示该字段为主键字段

not-null:该字段不允许为空

encrypt: 当设置为 true 时，在数据库中加密该字段。默认为 false（不加密）。

enable-audit-log: 设置为 true 时， 将日志记录本字段的所有变化以及变化时间和修改人。 日志数据记录在 EntityAuditLog 实体中。默认为 false 。

enable-localization: 当该属性被设置为 true， 获取本字段值时将会同时查看LocalizedEntityField 实体， 如果其中有匹配的记录， 那么将返回本地化的记录而不是原始记录。 由于展现的原因默认为 false，只有当字段属性设置为true时才会进行翻译。

default:字段默认值

create-only:字段的值不可变，只能在创建时设置而不能更新。在实体的create-only定义为true时，可以显式设置某些字段的create-only为false以允许更新某些字段。

description:字段的说明，备注

3，定义索引

当然，实体内部也可以定义索引来达到快速查询的效果，定义索引的语法如下：

<index name="NAP\_Be\_INDEX3" unique="true">  
    <index-field name="beRtnCd"/>  
    <index-field name="epccRtnCd"/>  
    <index-field name="rpFlg"/>  
</index>  
1  
2  
3  
4  
5  
用enity.index来声明索引

name:指定创建的索引名称

unique:索引是否唯一

index-field来声明创建索引的字段，name属性为字段名称，可以采用单个字段或者多个字段组合索引。

4，定义外键  
实体中除了主键之外，还有外键的关联，关联的格式为：

<relationship type="one" title="Amount" related="moqui.basic.Uom">  
    <key-map field-name="amountUomId"/>  
</relationship>  
1  
2  
3  
4.1 relationship  
type:外键关联字段的类型，可以是one，一个字段关联，也可以是many,多个字段互相关联，如：

<relationship type="many" related="nap.chk.NapChkSumFileReg" short-alias="CHKITEMFILEREG">  
    <key-map field-name="begnBtchId"/>  
    <key-map field-name="endBtchId"/>  
</relationship>  
1  
2  
3  
4  
related:关联的实体名称，加上包名

short-alias:外键别名

本例中有一个 key-map 元素位于 relationship 元素下面， 这仅对于这个实体的字段名称和相应的关联实体的字段名称不匹配才需要（进行手动映射）

4.2 key-map  
元素下的属性有：

field-name:主实体外键的字段名，必要属性

related:外键关联实体的字段名称

related没有写出来的情况下，框架会自动关联关联实体的主键

很多情况下，你可以不使用 key-map 元素， 简单的如下使用：

<relationship type="one" title="Example" related="moqui.basic.StatusItem"/>  
1  
这种方式表明主实体的外键字段与关联实体的一致，不需要再手动映射，但是建议在两个实体的主外键关联中，采用key-map来把关联关系清晰的标识出来，除了关联一般实体外，还可以关联枚举实体，如：

<relationship type="one" title="ExampleType" related="moqui.basic.Enumeration" short-alias="type">  
    <key-map field-name="exampleTypeEnumId"/>  
</relationship>  
1  
2  
3  
其关键点大致相同，需要注意的是relationship.title 属性需要与Enumeration中的enumTypeId 保持一致，在moqui框架中对于枚举来说这里有个约定relationship.title 的值就是枚举类型的 ID 用来过滤下拉列表 。

5，添加数据  
5.1 seed-data  
在实体的声明中，还有一个常用的标签seed-data，seed-data 元素允许你定义使用实体时必要的一些基本数据， 并且这也是定义数据模型的一个方面。

seed-data的用法大致分为两种，第一种就是简单的为实体注入一些基本数据，如：

<seed-data>

<nap.be.NapBeCoreHoldTransAcct seqId="000000006" trxCtgy="140" holdTransAcctId="990115626220190500010" description="清算户"/>

</seed-data>  
1  
2  
3  
4  
5  
包括了实体的全称，实体对应字段以及每个字段对应的值

第二种就是为实体关联的枚举实体列出相应的枚举值，如：

<seed-data>  
    <moqui.basic.EnumerationType description="对账结果" enumTypeId="ChkResult"/>  
    <moqui.basic.Enumeration description="未对账" enumId="CHK\_RESULT\_NONE" enumTypeId="ChkResult"/>  
    <moqui.basic.Enumeration description="对账平" enumId="CHK\_RESULT\_MATCH" enumTypeId="ChkResult"/>  
    <moqui.basic.Enumeration description="对账不平" enumId="CHK\_RESULT\_NOT\_MATCH" enumTypeId="ChkResult"/>  
</seed-data>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
在这里也可以看出relationship.title与enumTypeId是一致的，chkResult对应的枚举值在seed-data中被列出来

5.2 entity-facade-xml  
除了能在seed-data中添加数据之外，还可以通过创建一个实体门面的xml文件来为实体增加数据，这类xml文件一般放置在组件的data目录下，格式为：

<entity-facade-xml type="seed">  
    <Tutorial tutorialId="TestOne" description="Test one description."/>  
    <Tutorial tutorialId="TestTwo" description="Test two description."/>  
</entity-facade-xml>  
1  
2  
3  
4  
实体的字段与值一一对应即可

6，实体的类型  
主实体：主实体是独立于其他实体的，并通常只有单一主键字段。

明细实体：明细实体是为了主实体的字段添加明细信息并和主实体有个一对多的关联关系。明细实体的主键通常是两个字段，并且其中一个是主实体的单一主键字段。 第二个字段是一个特殊的排序序列 ID， 而不是一个绝对的序列值，它存在于主实体主键的上下文中。

关联实体：关联实体用于主实体之间的关联，通常为两个主实体。 关联实体是一个用于表示实体间多对多关系逻辑模型的物理呈现。关联实体追踪实体之间的关联记录十分的有用，并且其中任意数据都是两个实体之间的关系而不仅仅只是其中之一。 举个例子，如果你想要在另外一个主实体上下文的记录中去指定一个主实体记录的序列号，那么这个序列号字段应该存在关联实体上而不是其中任意的主实体上。关联实体可能有单一的主键生成，或者一个自然的由每个主实体的唯一主键字段构成的复合主键， 并且还有可选的 fromDate 和 thruDate 字段。

依赖实体：API 和工具应用的一部分支持“依赖”实体的概念。任何实体都会发现有依赖实体， 但是这个概念对于主实体的依赖来说最为重要 。

枚举：枚举是一个简单预配置的可能的数据集合。枚举用于描述单个记录或者记录间的关系。一个实体可以有多个枚举字段。Moqui框架中存储所有枚举值的实体名为Enumeration并且其中的值按照EnumerationType 实体中的类别记录进行隔离.当一个字段有一组可能的枚举值时，它应该有“EnumId”后缀， 就像 Example 实体上的exampleTypeEnumId 字段。对于这里的每个字段都应该有一个关系元素去描述从当前实体到Enumeration 实体的关系。relationship 元素上的 title 属性应当和 Enumeration 记录中的enumTypeId 字段有相同的值。通常 title属性应当和“EnumId”后缀的枚举字段名相同。例如exampleTypeEnumId 字段的关系标题是ExampleType。

7，实体的CrUD操作  
实体的CrUD操作大致有如下几个动作：entity-find-one，entity-find，entity-update，entity-set，entity-create，entity-make-value，entity-delete，entity-delete-by-condition，entity-find-count，entity-sequence-id-primary，entity-sequence-id-secondary，下面将对这些操作做一个详细的解释

7.1 entity-find-one：  
为entity-name 指定的实体查找单条记录并将其放入到一个EntityValue 对象

中，

<entity-find-one entity-name="moqui.example.Example" value-field="example"/>  
1  
对应的属性有：

entity-name:查找实体的名称。

value-field:将查找到的结果放入其中，必要属性。

auto-field-map:默认为true,上下文中按名称查找所有主键字段,除非找到字段映射子元素，否则这将不起作用。除了boolean类型的值以外，也可以用entity-find-one的子元素field-map，select-field指定的字段来查找。

cache:在查找之前会先在缓存里面查找数据。

for-update:为查找到的实体开启一个事物，但是没有必要设置为true,一旦设置为true，缓存就不可以使用，不管你在cache属性中如何设置的。

7.2 entity-find：  
为 entity-name 指定的实体查找多条记录并将其放入到一个 EntityList 对象中

<entity-find entity-name="nap.sgn.NapAuth" list="napAuth">  
    <econdition field-name="instgId" from="instgId"/>  
    <econdition field-name="sgnAcctId" from="sgnAcctId"/>  
    <econdition field-name="sgnAcctIssrId" from="sgnAcctIssrId"/>  
    <econdition field-name="idTp" from="idTp"/>  
    <econdition field-name="idNo" from="idNo"/>  
     <econdition field-name="mobNo" from="mobNo"/>  
</entity-find>  
1  
2  
3  
4  
5  
6  
7  
8  
对应的属性有：

entity-name:查找实体的名称

list:将查找到的实体集合放入list中

cache:在查找之前会先在缓存里面查找数据

for-update:为查找到的实体开启一个事物，但是没有必要设置为true,一旦

设置为true，缓存就不可以使用，不管你在cache属性中如何设置的。

distinct:根据所有字段的组合，去除重复的数据

offset:从指定的偏移量开始查找数据

limit:返回的最大记录行数

entity-find的子元素包括：search-form-inputs，econditions，having-econditions，econdition，econdition-object，select-field，order-by，limit-range，limit-view，use-iterator，下面将详细介绍这些子元素的用法

7.2.1 searchFormInputs ：

为 inputFieldsMapName 标识的 Map 中的字段添加条件。 这些字段指定的方

式和XML 表单中支持的-find 后缀结尾的字段一样。 这意味着你可以通过这种方式去处理 XML 表单中生成的各种输入数据。字段后缀包括像\_op 代表操作符， \_ic 代表忽略项。

<entity-find entity-name="moqui.example.Example" list="exampleList">  
    <search-form-inputs default-order-by="^exampleName"/>  
</entity-find>  
1  
2  
3  
searchFormInputs元素下的属性有：

default-parameters:如果搜索参数中没有约束，则此元素的属性是默认参数

input-fields-map:在表单字段中获取的map,为空时，如果Web门面可用，则从ec.web.parameters映射，否则为当前上下文。

default-order-by：如果没有orderByField参数，则按此顺序

skip-fields：在处理输入字段时，用逗号分开要跳过的实体字段名称列表

paginate：指出是否应该设置分页选项，即使这里没有pageSize和pageIndex参数，会在上下文中生成一个$\{entity-find.@list\}Count的字段，会自动计算出匹配结果的总数量，默认为true。

7.2.2 econditions：

按照指定的字段来查找

<econditions combine="or">  
    <econdition field-name="trxCtgy" from="trxCtgy"/>  
    <econdition field-name="trxCtgy" value="0100"/>  
</econditions>  
1  
2  
3  
4  
对应的属性combine,combine的值有：

or：表示所指定的字段用或者连接，满足其中一个即可

and：指定字段用并且连接，必须全部满足

7.2.3 having-econditions：

与econdition类似，但需要在分组功能完成后执行，属性也与econdition一样。

7.2.4 econdition：

为查询添加条件,将字段名称与上下文字段进行比较，

<econdition field-name="idTp" from="idTp"/>  
1  
对应的属性有：

field-name：用来查询实体的限制字段

from:在上下文的字段中获取对应值与指定字段进行比较

value：将对应的值与指定字段的值进行比较

operator：比较操作符，默认为EQUALS,可选的值有EQUALS,NOT\_EQUAL, LESS\_THAN, GREATER\_THAN, LESS\_THAN\_EQUAL\_TO, GREATER\_THAN\_EQUAL\_TO,IN, NOT\_IN, BETWEEN, LIKE 或者 NOT\_LIKE

to-field-name：将指定字段与实体上另一个字段进行比较

ignore-case：boolean类型，为true，进行比较时忽略大小写，默认false

ignore-if-empty：如果比较值为空或者null时，忽略此查询条件，boolean

类型，默认为false

or-null：为true时，将比较值为null时作为有效匹配，默认为false

ignore：为true时，忽略此查询条件

7.2.5 econdition-object：

约定每个映射 Map 条目的键值都必须匹配实体的字段名。 如果一个字段被设置为和 Map 中键相同的名字， 那么这个字段的值将被相应的Map 值替换。 在查询前，字段按照这种方式进行设置并和其他条件（如果适用的话）进行结合。 如果有必要将字符串转换为要求的字段类型，这里有一个转换并且只将获得匹配实体字段的键。对应的属性field：匹配上下文中字段或map集合。

7.2.6 select-field：

用于指定查询实体返回的字段名，如果没有设置该元素，则返回实体全部字段对应属性field用来指定返回字段名称

7.2.7 order-by ：

查询实体的排序字段。 可选择在最后添加”ASC”或者前面添加“+”进行升序，或者最后添加“DESC”或者前面添加”-”来进行降序。如果还有其他 的字段排序被指定，将会被添加到列表的最后 这个 String 字符串可能是一个逗号分隔的字段名列表。只有实体中实际存在的字段才可以被添加到这个排序列表中。对应属性field-name用来指定排序的字段名称。

7.2.8 limit-range：

通过起始偏移量和size来限定返回结果数量

start：查询起始位置

size：返回的结果数量

7.2.9 limit-view：

使用参数来限制显示在用户界面的结果，如分页参数

view-index：需要显示数据的位置索引

view-size：要查看的记录数量，也就是用户界面显示的结果数量。

7.2.10 use-iterator：

指定执行查询时是否使用EntityListIterator，boolean类型，默认为false

7.3 entity-find-count：  
找出符合限定条件的实体数量，查找条件和其他限定选项与entity-find中的子元素一样，这里就不在介绍，下面列出该元素具备的属性：

<entity-find-count entity-name="NapSgnPay" count-field="iNum">  
    <econdition field-name="trxId" from="trxId"/>  
    <econdition field-name="rpFlg" from="rpFlg"/>  
    <econdition field-name="pyeeAcctIssrId" from="pyeeAcctIssrId"/>  
</entity-find-count>  
1  
2  
3  
4  
5  
entity-name：查找实体名称

count-field：指定一个变量来存放查询的结果

cache：在查找数据源之前查看缓存，boolean类型

distinct：是否去除重复的结果，boolean类型，默认为false

7.4 entity-make-value：  
对于给定的实体名 entity-name，新建一条 value-field 实体值对象，并可选的基于map 去设置字段。

<entity-make-value entity-name="nap.trx.NapSgnPay" value-field="napSgnPay"/>  
1  
entity-name：创建实体的名称

map：将集合中存放的与实体字段一致的key-value值映射到所创建的实体对象中

value-field：指定一个变量来指代当前创建的实体

7.5 entity-create：  
为 value-field 实体值新建（or-update）一条记录，也就是将value-field指代的实体对象持久化到数据库中

<entity-create value-field="napSgnPay"/>  
1  
value-field：需要持久化的实体名称

or-update：如果数据库中已经存在该对象，就执行更新而不是返回错误，boolean类型，默认为false

7.6 entity-update：  
为 value-field 实体值更新一条记录，如

<entity-update value-field="napSgnPay"/>  
1  
7.7 entity-delete：  
删除相应的 value-field 实体值的记录，如

<entity-delete value-field="napSgnPay"/>  
1  
7.8 entity-delete-by-condition：  
删除符合条件的实体值，限定条件的规则同entity-find类似，如

<entity-delete-by-condition entity-name="nap.sgn.NapAuth">  
    <econdition field-name="instgId" from="instgId"/>  
    <econdition field-name="sgnAcctId" from="sgnAcctId"/>  
</entity-delete-by-condition>  
1  
2  
3  
4  
7.9 entity-set：  
在 EntityValue 对象上设置来源于 map（默认为 context） 的 value-field 字段包含include（pk, nonpk 或 all），可选 prefix 以及 set-if-empty。

<entity-set value-field="newNapPay" include="all"/>  
1  
7.10 entity-sequenced-id-primary：  
对于单一主键字段的实体 value-field，使用一个序列值（序列名称是实体的全称）填充主键字段，如

<entity-sequenced-id-primary-dynamic value-field="makeReqSeq"/>  
1  
7.11 entity-sequenced-id-secondary：

对于双主键字段的实体 value-field 并且其中一个字段已经被填充， 使用一个次要主键填充另外一个字段。次要主键的值为已存在的、匹配设置字段的记录中最高次要主键值加 1。

8，实体的扩展  
实体可以无需修改原来的实体定义 XML 文件来进行扩展，尤其当你想在不同的组件中扩展。你可以在实体定义 XML 文件中使用 extend-entity 元素并可以混合使用 entity 元素去达到效果。 这个元素拥有和 entity 元素很多相同的属性去定义扩展原来的实体。 简单的保证entity-name 以及 package-name 属性和原来的 entity 实体元素的属性一致，那么你指定的任何内容都会添加或者覆盖原有实体的定义 ，如

<extend-entity entity-name="Example" package="moqui.example">  
    <field name="auditedField" type="text-medium" enable-audit-log="true"/>  
    <field name="encryptedField" type="text-medium" encrypt="true"/>

</extend-entity>  
1  
2  
3  
4  
5  
9，视图实体  
很多情况下，我们不仅仅只查询一个实体，你可以使用 XML 定义创建一个静态的视图实体并用一个实体名称命名，去进行多个关联在一起的实体间的查询，其他普通实体定义一起存放。一个视图实体由多个关联在一起的实体通过键值映射以及成员实体的别名字段使用可选的功能关联在一起。 视图实体同样可以有关联的条件去封装一些视图中的数据约束。

就像实体一样，视图实体使用 view-entity 元素上的 entity-name 和 package-name 属性定义了名称和所在的包名。 每个成员实体通过 member-entity 元素进行表示并且在 entity-alias 属性中使用别名唯一定义它们。这么做的部分原因是在一个视图实体中同一个实体可能会使用不同的别名出现多次。

注意第二个 member-entity 元素还有个 join-from-alias 属性去指定其关联于第一个成员实体。 只有第一个成员实体没有 join-from-alias 属性。 如果你想要当前实体在关联（SQL 中的左外连接）中是可选的， 那么只要设置 join-optional 属性为 true。

使用 member-entity 元素下的一个或者多个 key-map 元素来描述两个实体之间是如何进 行互相关联的。 key-map 元素有两个属性： field-name 和 related-field-name。注意当当前成员实体的主键字段匹配时，related- field-name属性是可选的。

使用 alias-all 元素可以对所有的字段进行别名标识，就像上面的例子一样，或者使用 alias元素去单独的设置别名。 如果你想在一个字段上使用函数那么就使用 alias 元素单独去设置别名。 注意在 SQL 数据库中，如果任何别名的字段有一个函数同时其他所有的字段没有函数但是在查询中被选中了，那么将会被添加到 group by 子句中以免出现无效 SQL。

二，service  
Moqui 框架中业务逻辑的单元是服务。 Moqui 框架是一个面向服务的架构， 它是一个内部细粒度化逻辑单元和外部粗粒度化逻辑单元的聚合体。 Moqui 服务有：

1，事务处理

2，安全机制（鉴权和授权， 加上为了速度限制的伺服器）

3，验证（数据类型以及输入参数的各种约束）

4，各种语言和工具的实现，包括脚本语言，Java方法甚至Apache Camel终点

5，本地或者远程调用

6，同步运行，异步运行或者任务调度运行

7，通过服务事件-条件-动作（SECA）规则，在各种阶段的执行中运行其他服务的来源

8，可选的通过数据库信号去限制单个运行中的实例

服务使用服务元素定义在服务 XML 文件中，xml文件一般放置在组件的service目录下服务的名称由一个路径，一个动词和一个名词按照"$\{path.verb\#noun\}"结构组成。注意服务定义中的名词是可选的，并且在服务名称中动词和名词之间的井号（\#）也是可选的，下面来看一下如何定义一个简单的服务

1，service定义

<service verb="consume" noun="ExampleMessage">  
        <implements service="org.moqui.impl.SystemMessageServices.consume\#SystemMessage"/>  
        <actions>  
            <entity-find-one entity-name="moqui.service.message.SystemMessage" value-field="systemMessage"></entity-find-one>  
            <set field="exampleMap" from="new groovy.json.JsonSlurper().parseText(systemMessage.messageText)"/>  
            <service-call name="store\#moqui.example.Example" in-map="exampleMap"/>  
        </actions>  
    </service>  
</services>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
在services元素下，可以使用service 元素同时定义多个服务

service 元素的属性有：

verb: 它可以是任意的动词并通常是这些之一： create, update, store, delete 或者 find。服务的全名是："path. \{path\}.path.\{verb\}\#$\{noun\}"。动词是必须的并且名词是可选的，所以如果没有名词，那么服务名就只有动词。

noun: 对于实体自动服务来说必须是有效的实体名称。在很多其他的情况下，实体名称是最好的方式去描述当前操作的是什么， 但是这个名词确实可以是任何东西。

type: 指定服务如何实现的服务类型。默认可用的选项包括： inline, entity-auto, script, java,interface, remote-xml-rpc,remote-json-rpc 以及camel。额外的类型可以通过实org.moqui.impl.service.ServiceRunner 接口和在Moqui XMl配置文件中添加一个servicefacade.service-type元素来进行添加。默认值inline表示服务实现在 service.actions 元素下。

location: 服务的位置。对于脚本来说，这是脚本文件的资源门面位置。对于 Java 类方法来说，这是全类名。对于远程服务来说，这是远程服务的 URL 地址。 还可以参照一个 Moqui XML 配置文件中 service-facade.service-location 元素预定义的位置来替代一个真实的位置。 这对于远程服务URLs来说特别有用。

method: 如果服务类型可用，表示路径里指定的方法。

authenticate: 如果不设置为 false（默认是 true）， 那么必须由一个登录用户去运行服务。 如果服务运行在可执行上下文中是通过一个登录用户的话，那么是有资格的。如果不是， 那么不管是”授权用户帐号“（authUserAccount） 参数还是”授权用户名“（authUsername）和”授权密码“（authPassword） 参数都必须被指定， 并且都必须包含系统中用户的有效数据。 ”授权租户 ID”（authTenantId） 参数也可能需要被指定，用于鉴定这个用户存在于指定的租户实例中。 如果这个参数指定了，那么该租户将作为上下文租户去运行服务。服务参数也可以设置给匿名所有操作（anonymous-all）和匿名查看（anonymous-view），这样不仅无需进行服务权限鉴定，并且服务也将为所有动作或者仅查看去运行， 就像被认证过了一样（使用\_NA\_ UserAccount）。

allow-remote: 默认为 false， 意味着这个服务不能被远程接口类似 JSON-RPC 和 XML-RPC 进行调用。如果设置为 true，那么就可以。 在设置为 true 之前，确保服务被充分的保护了（授权和鉴权）。

validate: 默认为 true。设置为 false 去取消入参校验以及不自动删除未指定的参数。

transaction:事物，对应的值有  
² ignore: 不进行任何事务处理（如果有人正好在使用它， 那么不要开启一个事务）  
² use-or-begin: 使用活跃的事务或者如果没有活跃的事务则开启一个。 这是默认配置。  
² force-new: 总是开启一个新的事务，如果当前存在一个则暂停或者重新开始活跃的事务  
² cache: 类似 use-or-begin， 但是当前每个事务连续写入缓存（甚至当前有活跃的 TX 都这样工作）。 查看 JavaDoc 文档中 TransactionCache 类的说明获取更多注意事项和警告的细节。  
² force-cache: 类似 force-new，在当前有一个事务缓存使用 cache 选项 。

transaction-timeout: 事务超时时间，单位：秒。这个值仅用于服务开启一个事务（force-new,force-cache, use-or-begin 或者 cache，并且当前没有其他的事务存在）。

semaphore: 特用于长时间运行的服务（通常为任务调度）。使用数据库中的一条记录去锁住服务，这样在任何给定的时间段内对于指定的数据库只有一个服务实例。选项包括 none（默认的），fail 和 wait。

semaphore-timeout: 服务超时等待时间，单位：秒。默认为 120s。

semaphore-sleep: 检查服务信号的休眠间隔，单位：秒。默认为 5s。

semaphore-ignore: 本次服务之后忽略已存在的信号，单位： 秒。默认为 3600s（1 小时）。

以上为service元素的属性，service下面常用的子元素有：in-parameters，out-parameters，implements，actions，服务的输入和输出都是一个名称/数值条目的 Map。入参通过 in-parameters 元素指定，出参通过 out-parameters 元素指定。 在这些元素下使用 parameter 元素去定义单个的参数，并且 auto-parameters 元素用于自动定义基于主键（pk）， 非主键（nonpk） 或者实体所有字段的参数。 下面来详细介绍一下这些子元素的用法：

1.1 in-parameters  
服务传入的参数，参数指定采用parameter 子元素

<in-parameters>  
    <parameter name="mm" required="true"/>  
</in-parameters>  
1  
2  
3  
1.2 out-parameters  
服务执行结束返回的参数

<out-parameters>  
    <parameter name="msgTp"/>  
    <parameter name="bizStsCd"/>

</out-parameters>  
1  
2  
3  
4  
5  
1.3 parameters  
个体的 parameter 元素有如下属性去定义它，包括：

name: 参数名称， 匹配服务传入和返回的参数 Map 条目的键。

type: 属性类型，一个 Java 类的全名称或者一个普通的 Java API 类型（包括 String, Timestamp,Time, Date, Integer, Long, Float, Double, BigDecimal, BigInteger, Boolean, Object, Blob, Clob, Collection,List, Map, Set, Node）。

required: 默认为 false，如果参数为必要参数则为 true。 也可以设置为 disabled，用于展现类似参数不存在一样的情况， 当覆盖一个预定义的参数时十分有用。

allow-html: 仅适用于 String 字符串字段。仅仅检查入参（意味着校验来源于用户， 其他系统等的输入）。 默认为 none，表示不允许 HTML（将会导致出现错误信息）。 如果期望有一些 HTML使用 safe， 它将遵循 antisamy-esapi.xml 文件中定义的安全规则。这对于内部和公开的用户来说都是安全的。 当用户是可信任的或者非敏感字段这种罕见场景时， any 选项可以使用于一点都不检查 HTML 内容。

format: 仅用于参数是作为 String 类型传入的，但是需要进行类型转换。 对于日期/时间类型来说，使用标准的 Java SimpleDateFormat 字符串。

default: 当参数没有数值传入时，指定的默认使用的字段或者表达式（仅用于 required=false 的情况）。类似于默认值，但这里是一个字段名称或者表达式，而不是一个文本值。如果这个属性和 default-value 属性都被指定了， 那么将首先进行评估计算，并只有 default 属性的值为空时才使用 default-value 属性值。

default-value: 当参数没有数值传入时，指定的默认文本值（仅用required=false 的情况）。如果本属性和 default 属性都被指定了，默认首先进行 default 属性值的计算，并且本属性仅在default 属性值计算结果为一个空值时才使用。

entity-name: 可选项， 实体的名称， 并且参数和该实体上的某个字段有关联。

field-name: 可选项，字段名称，是已设置实体名的实体字段， 并且和参数关联。对于通过表单字段定义自动生成的服务参数来说最有用。当参数定义使用 auto-parameters 元素时， 相应传递的参数会被自动填充数值。

除了required属性之外，每个参数的校验还可以通过这些子元素进行指定，如

<in-parameters>  
    <parameter name="mm" required="true"/>  
    <parameter name="mmm">  
        <text-email />                   
    </parameter>  
</in-parameters>  
1  
2  
3  
4  
5  
6  
matches: 验证当前的参数和 regexp 属性指定的普通表达式是否匹配

number-range: 验证数字是否在 min 和 max 范围内

number-integer: 验证数字是否为整数

number-decimal: 验证数字是否为小数

text-length: 验证文本长度是否在 min 和 max 范围内

text-email: 验证文本是否是一个有效的 email 地址

text-url: 验证文本是否是一个有效的 URL

text-letters: 验证文本是否只包含字母

text-digits: 验证文本是否只包含数字

time-range: 通过指定的 format 去验证日期/时间是否在 before 和 after 范围内

credit-card: 如果指定了给定的卡类型 types， 验证文本是否是一个有效的使用 Luhn MOD-10规则的信用卡号

1.4 actions  
在service中的type设置为in-line时，所有的服务实现都在actions元素中完成，actions 元素包含了一个 XML 动作脚本的服务实现 。在moqui中有一个xml-actions-$\{version\}.xsd详细的注释文档，可以去查看，这里列出几个重要的xml动作元素：

set：设置一个字段 field， 既可以来源于（from）另一个字段也可以来源于一个 value 数值，可选的指定 type 类型，default-value 默认值以及空时是否设置 set-if-empty。如

<set field="bizStsCd" value="PB500018"/>  
1  
if:有条件的运行直接位于 if 元素下的元素部分， 或者 if.then 元素内的元素。 约束条件可以放在 if.condition属性中或者位于 if.condition 元素下的 compare 以及 expression元素中（结合 and 或 or 元素使用，用 not 元素表示否定）。交替的动作间使用 else if 和 else 子元素.

<if condition="sgnAcctTp=='00'">  
    <set field="xykFlg" value="0"/>  
</if>  
1  
2  
3  
while：重复子元素直到条件为真。 就像 if 元素一样，约束条件可以if.condition 属性内，或者也可以在 if.condition 元素中。

iterate：在给定的 list 属性中遍历元素， 并使用 entry 属性指定的名字在上下文中创建一个字段。 如果 list 属性命名的字段是一个 Map 类型， 遍历所有的 map 条目，并且将每个条目的键值使用 key 属性指定的名称命名，存放在上下文中。 同样创建上下文字段entryindex和 \{entry\}\_index 和entry   
i  
      
 ndex和\{entry\}\_has\_next。

script:运行本元素下通过 location 指定的任意资源门面能够运行的各种脚本或者 Groovy脚本文本（内联脚本）。如：

service-call:调用 name 属性指定的服务， 在 in-map 属性（这是个 Groovy 表达式， 所以可以为内联 Map 使用中括号\[ \]语法） 或 field-map 子元素中使用输入参数， 在 out-map 属性中放置输出参数。 可选属性有 async 和 include-user-login。如果服务运行出错，则将立即返回简单的方法，除非 ignore-error 属性等于 true。

<service-call name="nap.be.NapBEServices.accounting\#Customer" out-map="context"  in-map="context"/>  
1  
entity-find-one，entity-find，entity-find-count，entity-make-value，entity-create，entity-update，entity-set，entity-delete，entity-delete-by-condition，entity-sequencedid-primary，entity-sequencedid-secondary 这些动作在entity的7.1-7.11都有详细的介绍。

entity-data：对于给定的 mode，加载（load）或asset指定位置location 的实体门面 XML 文件。

filter-map-list:过滤 list 列表， 并如果指定的话， 将结果放入 to-list 中;如果未指定，则返回到 list中。 使用一个或多个 field-map 或 date-filter 子元素去指定如何过滤列表。

order-map-list：按照 order-by 子元素指定的字段， 去对一个 Map 对象的 list 列表进行排序。

message：如果 error=true， 添加 message 元素下的文本到消息门（Message Facade）的错误列表中；否则添加到消息列表中。

check-errors：检查消息门面（Message Facade） 的错误信息列表（ec.message.errors），如果列表非空则返回一条错误信息，否则啥都不用做。

return：立即返回。可选操作：指定一个 message，如果 error=true， 添加到消息门面错误列表中；否则添加到消息列表中。

<return error="false"/>  
1  
log：使用指定的级别（level） 去记录消息（message）。

<log level="info" message="开始执行"/>  
1  
2，服务实现  
通常脚本是实现服务最好的方式，除非是一个自动实现的实体 CrUD 操作的服务。当脚本缓存被清理时，脚本会被自动重载，并且在开发模式中这些缓存默认在一个很短的时间内期满以便于自动更新。

脚本能够高效率的运行，特别是 Groovy 脚本，可以在运行时编译成 Java classes 并以编译后的形式进行缓存，所以它们可以很快的运行。XML 动作脚本先被转换成 Groovy 脚本，然后编译和缓存，所以其性能概要和一个普通的 Groovy 脚本一样 。

任何资源门面能够运行的脚本都可以被用于服务的实现,默认支持的脚本有Groovy，XML动作以及JavaScript。任何脚本语言都可以通过javax.script 或者 Moqui 指定的接口实现去得到支持。

2.1 内联动作实现服务  
首先定义一个创建实体Tutorial的服务。 将服务定义 XML 文件放在下面的位置：

runtime/component/tutorial/service/tutorial/TutorialServices.xml

内容为：

<service verb="create" noun="Tutorial" type="inline" authenticate="false" >  
    <in-parameters>  
        <auto-parameters include="all"/>  
    </in-parameters>  
    <out-parameters>  
        <auto-parameters include="pk" required="true"/>  
    </out-parameters>  
    <actions>  
        <entity-make-value entity-name="Tutorial" value-field="tutorial"/>  
        <entity-set value-field="tutorial" include="all"/>  
        <if condition="!tutorial.tutorialId">  
            <entity-sequenced-id-primary value-field="tutorial"/>  
        </if>  
        <entity-create value-field="tutorial"/>  
    </actions>  
</service>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
service的type属性为inline ，服务的具体实现在service.actions 元素中使用xml动作来完成。

2.2 groovy脚本服务实现  
这里有一个使用 Groovy 脚本的服务实现，定义在TutorialServices.xml 文件中：

<service verb="create" noun="Tutorial" type="script" authenticate="false"        location="component://tutorial/script/tutorial/createTutorial.groovy">  
    <in-parameters>  
        <auto-parameters include="all"/>  
    </in-parameters>  
    <out-parameters>  
        <auto-parameters include="pk" required="true"/>  
    </out-parameters>  
</service>  
1  
2  
3  
4  
5  
6  
7  
8  
注意这里服务的 type 属性已经变为"script"，并且现在有个 location 属性去指定脚本的位置。

下面是这个 Groovy 脚本的内容：

EntityValue tutorial = ec.entity.makeValue("Tutorial")tutorial.setAll(context)if (!tutorial.tutorialId) tutorial.setSequencedIdPrimary()tutorial.create()    
1  
当你使用 Groovy 或者其他语言时，你将会用到基于可执行上下文（ExecutionContext class）这个类去调用 Moqui 的 Java API,通常这个类在脚本里会用"ec"这个名称。注意一下，脚本有一个单独的上下文环境， 独立于使用 ContextStack.pushContext() 和popContext()方法调用它的上下文。 这意味着在服务运行创建字段后，不仅上下文中不持久化数据，而且服务不访问调用它的上下文，尽管它在本地运行并在相同的调用服务的可执行上下文 ExecutionContext中。为了方便起见，这里上下文环境中有一个 result 字段，类型为 Map<String, Object>。你可以将出参放在这个 Map 中进行返回， 但是这样做并不是必须的。脚本运行后，脚本服务执行器在上下文中查找所有定义在服务上的出参，并将它们加到结果中。脚本也可以返回（计算得到）一个返回结果的 Map 对象。

2.3 实体的自动服务  
entity-auto 类型的服务你无需去实现它， 其实现基于 verb 和 noun 属性值自动生成。 动词可以是 create,update,delete 或 store（如果记录不存在则新建，存在时更新）。名词是一个实体名称，既可以是一个带包路径的全名也可以仅仅是不带包名的实体名称。

</service>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
这个服务将允许 Tutorial 实体的所有字段传入，并总是返回主键字段（tutorialId）。这个服务定义中我们使用了基于实体的 auto-parameters 元素，这样如果我们新增了实体字段的话，它们将自动会体现在这个服务处理中。

对于 create 操作， 服务将额外的自动生成缺省的主键序列 ID。 如果实体有两个主键并且一个指定另一个缺省，那么服务同样将生成一个次要主键序列 ID。这里还有一个特殊的服务行为，如果这里有 fromDate 主键字段未传递，那么服务将用当前时间戳（now Timestamp）去填充这个字段。

update 模式用于传递所有的主键字段（这是必须的）以及任何期望的非主键字段。特殊的服务行为同样适用于 update 模式。如果实体有一个 statusId 字段并且传入的 statusId 参数和字段值不同，那么服务将自动返回原始（DB 中）值放在 oldStatusId 出参中。无论何时实体有一个 statusId 字段，服务都还将返回一个 boolean 类型的 statusChanged 参数，如果状态字段和数据库中原始值不同，那么该字段为 true，反之为 false。实体自动服务还会通过检查匹配的moqui.basic. StatusFlowTransition 存在记录，去执行有效的状态变化。如果没有有效的状态变化，那么服务将返回一个错误。

实际运用中，实体的自动服务可以不用去定义，可以直接调用，如：

<service-call name="delete\#tutorial.Department"/>  
1  
3,服务的调用  
调用服务的语法格式为:

<service-call name="tutorial.DepartmentServices.create\#Department"/>

<service-call name="nap.GeneralServices.check\#BlackList"in-map="\[oriInstgId:instgId,trxCtgy:trxCtgy,sgnAcctId:sgnAcctId\]" out-map="context"/>  
1  
2  
3  
采用service-call元素来完成调用，元素的属性有：

name:调用服务的名称，遵循path. \{path\}.path.\{verb\}\#$\{noun\}的原则

in-map：调用该服务的传入参数

out-map：服务执行结束后的返回参数，都可以使用上下文context

out-map-add-to-existing：boolean类型，为true时，out-map被添加到相同的现有Map中，为false，在上下文中替换现有的map，默认为true

async:为true时,采用异步运行服务，可选的值有true，false，distribute

include-user-login:是否将当前用户包含在服务调用中，boolean类型,默认为true

transaction：是否采用事物，默认use-or-begin

transaction-timeout：事物的超时时间，单位为秒

三，xml表单  
XML 表单有两种类型：单个表单和列表表单。 单个表单表现为单个带有标签和小部件的字段的集合。 列表表单表现为像是一个字段为列的表格， 表格页眉为标签，每行的字段都有个小部件，并且一行基于表单列表每个条目的输出。

然而还有其他的方式去获取数据，最常用的是从一个 Map 中获取单个表单的字段值，同时从一个 Map 的列表中获取一个列表表单的值。

XML 表单类似于界面 XML，它们都是用一个 FTL 宏定义为每个元素进行渲染，同时它们都支持多种呈现模式。就像界面 XML 部件一样，你可以通过添加宏定义去添加你自己的部件。 XML 表单的宏定义存在和界面 XML 宏定义相同的 FTL 文件中，所以使用相同的方式去添加自定义宏。

1，单个表单  
使用 form-single 元素去定义单个表单。 下面是 form-single 的使用案列：

<form-single name="CreateExample" transition="createExample" focus-field="exampleName">  
    <field name="statusId">  
        <default-field title="Status" tooltip="The status of the  example"> <drop-down allow-empty="false">  
                <list-options list="exampleStatusItemList" text="$\{description\}"/>  
            </drop-down>  
        </default-field>  
    </field>  
    <field name="exampleTypeEnumId">  
        <default-field title="Type" tooltip="Type of example">  
            <drop-down allow-empty="false">  
                <dynamic-options transition="getExampleTypeEnumList" value-field="enumId" label-field="description">  
                    <depends-on field="statusId"/>  
                </dynamic-options>  
            </drop-down>  
        </default-field>  
    </field>  
    <field name="exampleName"><default-field tooltip="The name of the example"><text-line/></default-field></field>  
    <field name="submitButton"><default-field title="Create"><submit/></default-field></field>  
</form-single>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
对于表单来说最重要的就是表单字段，我们会在后面的介绍中会单独列出表单字段的用法，这里主要讲解form-single的属性。

name: 表单的名称。 用于和界面 XML 文件位置一起去引用表单。 对于 HTML 输出来说，这是表单的名称和 id，同时对于其他的输出来说，它也可被用于定义表单相关的输出部分。

extends: 扩展使用井号（\#） 分隔位置和名称的表单。 如果这里没有位置则它将被视为当前界面中的一个表单名称。

transition: 当前界面提交表单跳转到的转换。

map: 获取字段值的 Map。通常是一个 EntityValue 对象或从各种地方拉取的用于填充表单的 Map。Map 键匹配字段的名称。如果 field.entry-name 属性在每个字段被渲染的同时，用于上下文计算，它将会被忽略。默认为 fieldValues。

focus-field: 当界面呈现时焦点所在的字段名称 name。

skip-start: 表单渲染跳过的字段的起点。 在一个表单之后使用 skip-end=true， 这会有效的将多个表单组合成一个表单。

skip-end: 表单渲染跳过的字段的终点。 使用它去离开一个打开的表单， 这样额外的表单可以和它一起进行组合。

dynamic: 如果为 true， 表单将被认为是动态的， 并且内部定义每次都会被构建而不仅仅是第一次引用的时候去构建。 当 auto-fields-元素为服务或实体名称有$\{\}字符扩展， 这就十分的必要。

background-submit: 在后台提交表单而无需重载界面。

background-reload-id: 在后台提交表单之后，通过这个 id 去重载 dynamic-container。

background-message: 在后台提交表单之后， 在一个对话框中展示这个信息。

使用 form-single.field-layout 元素进行字段的布局， 而不仅仅是平铺的字段列表。 对于HTML 输出来说， 这里有个可选的 id 属性用于辅助样式。如果字段布局包含字段分组， 设置collapsible 属性为 true，使用一个手风琴部件去保存空间位置。可选的指定 active 激活的分组索引，而不是第一个分组初始化时展开。这里的子元素用于定义一个布局：

field-ref: 指定名称为 name 的字段位于何处 。

fields-not-referenced: 包含所有未在别处引用的字段； 如果这个元素未展现在 field-layout 中没有引用的字段， 则将不会被呈现 。

field-row: 创建一行通过 field-ref 子元素指定的字段； 如果这里行中有两个字段将会显示为四列，都带有标题；如果这里有多余两个字段只有第一个字段的标题会显示，其他的字段部件将会在行中并排的排列，按照需要进行包装 。

field-group: 如果 field-layout.collapsible 被设置为 true，创建一个手风琴类型的字段分组， 同时带有一个可选的 title 显示在分组上，一个可选的分组外部容器（div）的 HTML 输出样式 style；使用 field-ref， fields-not-referenced 和 field-row 子元素用于指定分组包含的字段以及可选的将它们放入行中 。

2，列表表单  
使用 form-single 元素定义单个表单。 下面是 form-list 的使用案例：

<form-list name="ListExamples" list="exampleList" skip-form="true" header-dialog="true" select-columns="true"  
           show-csv-button="true" show-text-button="true" show-pdf-button="true">  
    <field name="exampleId" print-width="10" print-width-type="characters">  
        <header-field><text-find hide-options="true"/></header-field>  
        <default-field>  
            <link url="editExample" text="$\{exampleId\}" link-type="anchor"/>  
        </default-field>  
    </field>  
    <field name="exampleName" print-width="40">  
        <header-field title="Name" show-order-by="case-insensitive"><text-find/></header-field>  
        <default-field><link url="editExample" text="$\{exampleName\}" link-type="anchor"/></default-field>  
    </field>  
    <field name="exampleTypeEnumId" print-width="30">  
        <header-field title="Type"><auto-widget-entity entity-name="moqui.example.Example" field-type="edit"/></header-field>  
        <default-field><display-entity entity-name="moqui.basic.Enumeration"/></default-field>  
    </field>  
    <field name="statusId" print-width="30">  
        <header-field title="Status"><drop-down allow-empty="true">  
            <list-options list="exampleStatusItemList" text="$\{description\}"/></drop-down></header-field>  
        <default-field><display-entity entity-name="moqui.basic.StatusItem"/></default-field>  
    </field>  
    <field name="exampleDate" print-width="16" print-width-type="characters">  
        <header-field title="Date" show-order-by="true"><date-period/></header-field>  
        <default-field><display/></default-field>  
    </field>  
    <field name="description" print-width="0">  
        <header-field show-order-by="case-insensitive"><text-find/></header-field>  
        <default-field><display/></default-field>  
    </field>  
    <field name="findButton"><header-field title=""><submit text="Find"/></header-field>  
        <default-field><ignored/></default-field></field>  
</form-list>  
1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
name: 表单的名称。 用于和界面 XML 文件位置一起去引用表单。 对于 HTML 输出来说，这是表单的名称和 id，同时对于其他的输出来说，它也可被用于定义表单相关的输出部分。

extends: 扩展使用井号（\#） 分隔位置和名称的表单。 如果这里没有位置则它将被视为当前界面中的一个表单名称。

transition: 当前界面提交表单跳转到的转换。

multi: 将表单作为多值提交的表单，页面上所有的行在单个请求中一起提交，同时每个字段都有个“\_$\{rownumber\}”后缀。 同样还传递一个\_isMulti=true 参数， 这样服务门面知道为每一行去运行服务（在 transition 中的单个 service-call）。 默认为 true， 因此设置为 false 去禁用上面的行为并为每一行有一个独立的表单（单独提交）。

list: 一个遍历列表去计算的表单式。

list-entry: 如果指定则每个列表条目都会使用这个名称被放到上下文中， 否则列表条目必须为一个 Map， 并且每行的 map 中的条目将会被放到上下文中。

paginate: 表明表单是否需要进行分页。默认为 true。

paginate-always-show: 总是显示带有记录行总数的分页控制， 哪怕只有一页。默认为 true。

skip-start: 表单渲染跳过的字段的起点。 在一个表单之后使用 skip-end=true， 这会有效的将多个表单组合成一个表单。

skip-end: 表单渲染跳过的字段的终点。 使用它去离开一个打开的表单， 这样额外的表单可以和它一起进行组合。

skip-form: 令输出成为一个普通的表格，不能提交（在 HTML 中不生成 form 元素）。 最小化的输出只读的列表表单时很有用。

类似于单个表单中的 field-layout，列表表单中有个 form-list-column 元素。 当使用它时需要每个表格中的列都有一个元素，并且所有的字段都参照一列，否则将不会被显示。 formlist-column 元素有单个子元素， 用于单个表单 field-layout 中相同的 field-ref 元素。

表单的数据准备最好通过界面 XML 的动作 actions 去完成， 但有时你需要为列表表单的每一行去准备数据。 这可以通过高级的 Map 的 List 对象为列表表单条目字段准备数据去实现。 通过这种方式，准备 List 的业务逻辑可以为准备数据进行额外的数据查找或计算。 另一种方式是在 form-list.row-actions 元素下添加 XML 动作。 这些为每一行运行的动作都在一个独立的上下文中，因此任何上下文中定义的字段都只能用于对应的那一行。

3，表单字段  
<field name="statusId">  
    <default-field title="Status" tooltip="The status of the example">  
        <drop-down allow-empty="false">  
            <list-options list="exampleStatusItemList" text="$\{description\}"/>  
        </drop-down>  
    </default-field>  
</field>  
1  
2  
3  
4  
5  
6  
7  
表单最主要的元素就是 field， 通过其 name 属性进行定义。 当一个表单扩展另一个表单的字段时，使用相同的字段名称进行覆盖。对于 HTML 输出这也是 HTML 表单字段的名称。这个名称还可以用于获得字段值 map 的键或者参数名称（如果没有找到 map 的键值对，或 表单提交时出现错误的情况）。 从上下文中获得字段值， 参数的 name 属性依然可以使用，同时 entry-name 属性可以为任何 Groovy 表达式， 用于计算出期望的数值。

你可以在基于服务参数生成 HTML 时，使用字段元素上的 validate-service 和 validateparameter 属性去自动进行客户端的校验。 当表单字段使用 auto-fields-service 元素基于服务自动定义时，这两个属性都会被自动进行填充。 XML 表单渲染时将会查看表单提交的转换transition，并且如果它有单个 service-call 元素（相对于使用 actions 元素去处理输入）， 那么它将会查看服务的输入参数， 同时如果其名称匹配字段名称则使用其校验。

字段类型或字段的“部件”（可视的/交互元素） 存在于 field 元素下的子元素中。 默认部件使用在 default-field 子元素中， 并且所有的字段都需要有一个（并且仅有一个）。 如果你想要在特定的条件下使用不同的部件，可以使用 conditional-field 元素及一个 Groovy 表单式去计算出一个 boolean 值存在 condition 属性中。 这在单个表单和列表表单都可生效， 同时对于列表表单， 将会为每一行都进行计算。

这里还有部件的 field.header-field 子元素用于列表表单的行数据头。 当使用这些数据头字段部件在一个独立的表单时，通常意味着为搜索操作而使用。 排序链接自然的和搜索操作一起在列表表单的数据头中， 并且它们可以通过设置 header-field.show-order-by 属性为 true或者 case-insensitive 来开启。

字段的标题来源于 default-field.title 属性，除非这里有 header-field 元素， 然后它将从这个元素上的 title 属性中获取。 default-field 元素同样有 tooltip 属性用于当焦点在字段上或者鼠标悬停在字段上时（指定悬停依赖于生成的 HTML 或其他指定的表单呈现），显示一个弹出的提示信息。

通常当起始时间还没到或截止时间之后， 将时间值标为红色比较好。 可以使用 default-field.red-when 属性进行控制， 这个属性值默认为 by-name， 意味着如果字段 name 是起始时间 fromDate，那么当前时间还没到则这个字段就是红色，同时如果字段 name 是截止时间thruDate，那么当当前时间已经超过这个时间则字段为红色。 属性值还可以为 before-now，after-now 和 never。

3.1 字段组件  
在moqui中，有很多开箱即用的表单字段小部件，同时额外的小部件可以使用宏定义模板和自定义元素截面中描述的扩展机制进行添加。 组件使用在 default-field 子元素中，如：

<field name="statusId">  
    <default-field title="Status" tooltip="The status of the example">  
        <drop-down allow-empty="false">  
            <list-options list="exampleStatusItemList" text="$\{description\}"/>  
        </drop-down>  
    </default-field>  
</field>  
1  
2  
3  
4  
5  
6  
7  
下面是 Moqui 中开箱即用的字段部件总结：

3.1.1 auto-widget-service ：

元素属性有parameter-name ，service-name（必要属性），field-type。基于 parameter-name 入参和 service-name 服务自动的定义字段的部件。 使用 field-type 属性去指定字段部件一般的类型， 指定的字段部件是基于参数对象的类型去进行选择。它可以是 edit（默认值）， find， display， find-display（同时添加 find 和 display 部件）或 hidden。

3.1.2 auto-widget-entity：

元素属性有entity-name，field-name，field-type。基于 entity-name 实体的 field-name 字段去自动的定义字段部件。 使用 field-type 属性去指定使用的字段部件一般的类型， 指定的字段部件是基于字段类型进行选择的。 它可以是 edit， find， display， find-display（默认值； 同时添加 find 和 display 部件）或hidden。

3.1.3 widget-template-include：

在一个 XML 文件中使用 widget-templates 根元素去定义表单字段部件模板。 每个widget-template 元素可以包含任意按需要带有$\{\}参数的字段部件元素。使用一个部件模板需要指定它的 location 以及按需要 set 用于呈现模板中定义字段的子元素。

3.1.4 check：

为 entity-options， list-options 和/或 option 子元素（查看 drop-down 描述中的细节）中的可选项列表显示一个选择框。 可选操作： 默认选中使用 no-current-selected-key 属性去指定一个选择框， 或设置 all-checked 为 true 去勾选所有的框。

3.1.5 date-time：

时间部件，对应的属性有：

type:时间类型，可以为timestamp，date-time，date，time。

format：日期/时间字符串的格式，使用一个 Java 的 SimpleDateFormat字符串类型来进行指定。

default-value：在没有上下文或参数值时， 指定字段的默认值去使用。

size：部件的文本输入框的宽度的字符个数

max-length：输入字符的最大数目

3.1.6 date-find：

和 date-time 使用一样的 type 和 format 属性，去显示两个日期/时间输入部件。 使用default-value-from 属性作为表单（左边的） 输入框默认值， 同时 default-value-thru 属性作为截止时间框（右边的） 的值。

3.1.7 display：

一个普通的扩展的字符串文本显示， 对应的属性有：

text：指定要显示的字符串，可以使用$ \{\}语法来插入上下文值; 如果为空，该字段的值将被打印为默认值

also-hidden：如果设置为true，则还会呈现隐藏的表单字段，呈现的值为该字段的值

currency-unit-field： 对于币种字段进行格式化

format：为日期/时间（SimpleDateFormat），数字（DecimalFormat）等值去指定 Java 格式化字符串。

text-format：用于格式化文本输出的Number / Time / Date / Timestamp / etc对象。

encode ：boolean类型，为true时，对于 HTML 输出文本默认进行编码。

dynamic-transition：如果指定了，将会动态获取参数值，存储到parameter-map参数中

parameter-map：从动态值请求中获取参数名称和值的映射。

3.1.8 display-entity:

为 entity-name 查找实体的值并显示包含实体字段值的扩展 text 字符串。 它仅限于通过单一主键字段进行查找， 并且如果实体的主键字段名称和 field.name 不同， 则通过key-field-name 属性去指定它。 默认的这里有个缓存的查询， 不使用实体缓存设置 usecache 为 false。 就像 display 一样， 它有一个相应的表单提交的隐藏字段， 除非 alsohidden 被设置为 false。 对于 HTML 输出文本默认进行编码， 除非 encode 被设置为false。

3.1.9 drop-down:

下拉列表，对应的属性有：

size：下拉列表值得个数，默认为1

allow-multiple：为 true时，允许选择多个数值，默认为false

current ：设置为 first-in-list（默认值）， 或者通过 selected 选项去设置选中值。

allow-empty：为true时，可以添加一个空的选项到列表中。

no-current-selected-key：设置默认选项的键值。

current-description：如果设置的选项不在已存在的选项中，使用 current-description 属性去指定它的描述。

search：boolean类型，默认为true，动态下拉框部件基于输入的文本进行选项过滤。 使用普通的下拉设置 search为 false。

combo-box：boolean类型，为true时，允许用户输入一个新的不存在于下拉中并提交的选项。

style：只能在紧急情况下使用，例如弹出窗口中选择的问题。

drop-down下面的子元素有 entity-options， list-options，option ，dynamic-options，下面来详细介绍一下这四个子元素。

3.1.9.1 entity-options

从数据库记录中获取选项， 利用entity-find 元素查询约束的选项，和XML 动作脚本中相同的元素使用方式一样。对应的属性：

key：指定实体字段用于键

text：字段的文本标签值。

3.1.9.2 list-options

使用 list-options 元素用于 Map 值的列表选项，通过 Groovy 表达式来计算获得 list 属性中的列表， 并且 Map 中键值对选项的键值在 key 属性中， 同时 Map 键值的文本标签值在 text 属性中。

3.1.9.3 options

option 元素可以明确的为每个选项指定 key 和 text 属性。

3.1.9.4 dynamic-options

利用界面 transition 返回一个包含了 Map 的 List，动态选项列表，属性有

transition：指定需要执行的转换，来获取选项列表

value-field：获取到的map中的key

label-field:代表选项的标签(value)。

dynamic-options下面还有一个depends-on的子元素，使用动态选项的主要原因是当另一个字段变化时去改变选项。需要使用一个或多个 depends-on 子元素以及 field 属性中的表单字段名去实现它。当一个参照的字段改变新的选项时将会请求界面跳转， 将所有的参照字段值作为参数传递到请求中。

3.1.10 file:

一个宽度为 size（默认为 30） 字符并允许最大输入 maxlength 字符的文件上传输入框（有一个按钮/链接去弹出文件选择窗口）。如果没有上下文或这个字段没有参数值，则用 default-value 属性去指定默认值。

3.1.11 hidden:

隐藏字段的值会和表单一起提交但不会显示给用户。 如果没有上下文或这个字段没有参数值，则用 default-value 属性去指定默认值。

3.1.12 ignored:

将这个字段视为甚至没有被定义。 当扩展另一个表单排除不需要的字段时很有用。

3.1.13 password:

一个宽度为 size（默认为 30） 字符并允许最大输入 maxlength 字符的密码输入框。标记输入为安全的。

3.1.14 radio:

为源于 entity-options， list-options 和/或 option 子元素（查看 drop-down 描述中的细节）中的可选项列表显示一组单选框。 可选的使用 no-current-selected-key 属性去指定默认选中值（如果该字段没有值或者参数指定）。

3.1.15 range-find:

主要用于数字范围查找， 显示两个宽度为 size（默认为 10） 字符并允许最大输入maxlength 字符的小输入框。 使用 default-value-from 属性作为表单（左边的） 输入框默认值， 同时 default-value-thru 属性作为截止（右边的）的值。

3.1.16 reset:

重设表单的按钮。按钮的文本来源于字段标题

3.1.17 submit:

表单提交按钮。按钮文本来源于字段标题， 除非使用了 image 子元素在按钮上放置了一个图片。 可以使用 icon 属性去设置一个来源于图标库（默认运行时 webroot 里Bootstrap 模板 Glyphicons 中的图标都可用， 举个例子 icon="glyphicon glyphicon-plus"或利 用 "fa fa-search"来 使用 Font Awesome 图 标 ）的 图标 样 式放 在文 本 旁边 。在confirmation 属性中放置信息，可以在按钮点击时显示一条信息并让用户进行确认。

3.1.18 text-area:

一个文本域，宽度为 cols 字符高度为 rows 行， 并且允许最大输入字符为 maxlength。如果该字段没有上下文或参数值， 可以使用 default-value 属性去指定一个默认值。 设置 read-only 为 true， 可以使文本域仅用于显示而不允许改变其值。

3.1.19 text-line:

单行简单文本输入框，对应的属性有：

size ：单行简单文本输入框的宽度

maxlength：允许最大输入字符数

default-value：指定一个默认值

disabled ：为true时，文本框仅用于显示而不允许改变其值，只读

format ：为日期/时间（SimpleDateFormat），数字（DecimalFormat）等值去指定 Java 格式化字符串。

ac-transition：指定转换的名称

acdelay：查询的延时毫秒数，默认300

ac-min-length：查询前的最小输入字符数，默认为1

3.1.20 text-find:

size ：单行简单文本输入框的宽度

maxlength：允许最大输入字符数

default-value：指定一个默认值

ignore-case：忽略大小写

default-operator ：指定默认操作符以为 equals，like，contains 或 empty。

hide-options：设置是否隐藏忽略大小写选择框以及操作符下拉框，选项设置有：

true：隐藏两者

false：默认值，显示两者

ignore-case：只隐藏忽略大小写选择框

operator：只隐藏操作符下拉框  
————————————————  
版权声明：本文为CSDN博主「木木啊\_」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。  
原文链接：https://blog.csdn.net/qq\_40585287/article/details/84142668