Ux注解
大约 14 分钟
Ux注解
我们默认视图已经基本可以用了，但实际业务中还是会有一些不大不小的自定义需求，写自定义视图又太麻烦，所以我们有一种更加轻量的模式即：后端研发可以通过注解来配置视觉交互。该系列注解以Ux开头，例如@UxHomepage、@UxMenu、@UxAction、@UxView、@UxWidget等等。 视图XML的配置优先级大于在代码上的注解，也就是代码上的注解影响的是默认展示逻辑。
一、Ux注解家族
注解介绍
@UxHomepage
描述： 可以为模块首页配置添加元数据信息，包括引用的 action 名称和路由信息。
使用示例
@UxHomepage(actionName = "customAction",
value = @UxRoute()）
属性解释
actionName: 引用的 action 名称。不指定则创建一个新的 action。示例：@UxHomepage(actionName = "customAction")value: 路由信息，类型为UxRoute。
@UxRoute
描述： 该注解用于定义窗口动作的路由信息。 使用示例
@UxRoute(value = @UxRoute(PamirsCompany.MODEL_MODEL),
viewName = @UxRoute(PamirsCompany.MODEL_MODEL),
viewType = ViewTypeEnum.TABLE,
openType =ActionTargetEnum.ROUTER,
module = PamirsCompany.MODEL_MODEL,
title = "",
theme = "",
mask = "",
views = {ViewTypeEnum.TABLE, ViewTypeEnum.FORM},
queryMode = QueryModeEnum.DOMAIN,
load = "",
mapping = {},
context = {},
domain = "",
filter = "partnerType=='COMPANY'",
limit = 30)
属性解释
value或model: 目标模型编码，用于指定目标模型。viewName: 指定目标视图，可缺省，使用默认视图。viewType: 视图类型，表示窗口动作的目标视图类型，默认为ViewTypeEnum.TABLE。- 可选值：
CUSTOM("CUSTOM", "自定义视图类型", "自定义视图类型"),DETAIL("DETAIL", "详情", "详情"),FORM("FORM", "表单", "表单"),TABLE("TABLE", "表格", "表格"),SEARCH("SEARCH", "搜索", "搜索"),CALENDAR("CALENDAR", "日历", "日历"),KANBAN("KANBAN", "看板", "看板"),GALLERY("GALLERY", "画廊", "画廊"),CHART("CHART", "图表", "图表"),TREE("TREE", "树", "树"),
openType: 打开方式，表示窗口动作的打开方式，默认为ActionTargetEnum.ROUTER。- 可选值：
- ROUTER("router", "页面路由", "页面路由"),
- DIALOG("dialog", "页面弹窗", "页面弹窗"),
- DRAWER("drawer", "打开抽屉", "打开抽屉"),
- INNER("inner", "页内路由", "页内路由"),
- OPEN_WINDOW("openWindow", "打开新窗口", "打开新窗口"),
module: 目标模块编码。title: 页面标题。theme: 主题。mask: 母版。views: 支持可供切换的视图类型列表，类型为ViewTypeEnum数组。queryMode: 数据加载方式，表示窗口动作的数据加载方式，默认为QueryModeEnum.DOMAIN。- 可选值：
DOMAIN("domain", "条件入参", "条件入参"),ENTITY("entity", "单行或多行实体入参", "单行或多行实体入参");
load: 数据加载函数编码。mapping: 数据传输映射DSL，类型为Prop数组。context: 上下文，类型为Prop数组。domain: 数据过滤-客户端。filter: 数据过滤-服务端。limit: 初始化页面数据数量限制，默认为 20。
@UxAppLogo
描述： 该注解用于配置应用的 Logo。 使用示例
@UxAppLogo(logo = "/images/app_logo.png")
属性解释
value或logo: 应用 Logo 的路径。
@UxDetail
- 介绍：
- 用于标注在类上，表示这是一个详情视图的配置。
- 提供了一些属性用于配置详情视图的行为，如栅格数、默认分组标题、是否将所有表格子视图合并为选项卡等。
- 使用示例
@UxDetail(
grid = 2,
group = "",
tabsTable = true
)
@UxDetail.FieldWidget(value = @UxWidget(value = ""))
- 属性说明：
grid：表示栅格数，用于配置详情视图的栅格布局，默认值为GridConstants.defaultViewGrid。group：表示默认分组标题，用于在详情视图中分组展示字段，默认为空字符串。tabsTable：表示是否将所有表格子视图合并为选项卡置于视图底部，默认为true。
- @FieldWidget 注解：
- 嵌套在
@UxDetail注解内部，用于配置字段组件。 - 标注在字段上，表示该字段应使用特定的字段组件（通过
UxWidget类型的参数指定）。
- 嵌套在
@UxForm
- 介绍：
- 用于标注在类上，表示这是一个表单视图的配置。
- 提供了一些属性用于配置表单视图的行为，如栅格数、默认分组标题、是否将所有表格子视图合并为选项卡等。
- 使用示例
@UxForm(
grid = 2,
group = "",
tabsTable = false
)
@UxForm.FieldWidget(
value = @UxWidget()
)
属性说明：
grid：表示栅格数，用于配置表单视图的栅格布局，默认值为GridConstants.defaultViewGrid。group：表示默认分组标题，用于在表单视图中分组展示字段，默认为空字符串。tabsTable：表示是否将所有表格子视图合并为选项卡置于视图底部，默认为true。
字段组件注解：
@FieldWidget：用于配置字段的组件，可以标注在字段上，表示该字段应使用特定的字段组件（通过UxWidget类型的参数指定）。
关联关系字段组件注解：
@RelationSelect：用于关联关系下拉字段组件的配置，包括是否显示创建按钮，默认为true。@RelationTable：用于关联关系表格字段组件的配置，包括是否显示创建、编辑、详情、删除按钮，默认为true。
@UxTable
- 介绍：
- 用于标注在类上，表示这是一个表格视图的配置。
- 提供了一些属性用于配置表格视图的行为，如栅格数、是否启用搜索、是否开启序号（表格）等。
- 使用示例
@UxTable(
grid = 2,
enableSearch = true,
enableSequence = false
)
@UxTable.FieldWidget(
value = @UxWidget()
)
- 属性说明：
grid：表示栅格数，用于配置表格视图的栅格布局，默认值为GridConstants.defaultViewGrid。enableSearch：是否需要启用搜索功能，默认为true。enableSequence：是否开启序号（表格），默认为false。
- @FieldWidget 注解：
- 嵌套在
@UxTable注解内部，用于配置字段组件。 - 标注在字段上，表示该字段应使用特定的字段组件（通过
UxWidget类型的参数指定）。
- 嵌套在
@UxTableSearch
- @UxTableSearch 注解：
- 用于标注在类上，表示这是一个列表搜索配置。
- 提供了一些属性用于配置列表搜索的行为，如栅格数。
- 使用示例
@UxTableSearch(
grid = GridConstants.defaultTableSearchGrid
)
@UxTableSearch.FieldWidget(
value = @UxWidget()
)
- 属性说明：
grid：表示栅格数，用于配置列表搜索的栅格布局，默认值为GridConstants.defaultTableSearchGrid。
- @FieldWidget 注解：
- 嵌套在
@UxTableSearch注解内部，用于配置字段组件。 - 标注在字段上，表示该字段应使用特定的字段组件（通过
UxWidget类型的参数指定）。
- 嵌套在
@UxWidget
- 介绍：
- 用于标注在局部变量上，表示这是一个自定义组件的配置。
- 提供了一系列属性用于配置自定义组件的行为，包括显示名称、组件类型、组件配置参数、数据传输映射DSL等。
- 使用示例
@UxWidget(
label = "",
widget = "",
span = 6,
placeholder = "",
required = "",
readonly = "false",
invisible = "false",
disable = "false",
group = "",
tab = "",
priority = 1
)
- 属性说明：
value/label：显示名称，可用于设置组件的标签。widget：组件类型，表示使用的自定义组件的类型。config：组件配置参数，用于设置组件的相关参数。mapping：数据传输映射DSL，用于配置数据传输映射规则。context：上下文，用于配置组件的上下文信息。queryMode：查询方式，表示在查询时使用的方式，默认为QueryModeEnum.DOMAIN。
- 布局相关属性：
span：块所占栅格。offset：栅格左侧的间隔格数，间隔内不可以有栅格。
- 提示信息属性：
placeholder：占位提示。hint：说明提示。
- 显示与隐藏属性：
required：必填。readonly：只读。invisible：隐藏。disable：禁用。
- 分组与顺序属性：
group：分组，开启新的分组并设置分组标题，默认为融入前序组件的分组。tab：选项卡页，开启新的选项卡页并设置选项卡页标题，默认为融入前序组件的选项卡页。breakTab：不再融入前序组件的选项卡，默认为false。priority：优先级，用于设置组件的显示顺序。
@UxIgnore
- 介绍：
- 用于标注在字段上，表示该字段在指定的视图类型中应该被忽略。
- 提供了一个
value属性，用于指定要忽略的视图类型数组，默认为空数组。
- 使用示例
@UxIgnore(value = {ViewTypeEnum.LIST, ViewTypeEnum.DETAIL})
- 属性说明：
value：表示要忽略的视图类型数组，可以在注解中指定需要忽略的视图类型。默认为空数组，表示在所有视图中都要忽略。
@UxAction
- 介绍：
- 用于标注在局部变量上，表示这是一个动作的基本配置。
- 提供了一系列属性，用于配置动作的名称、展示名称、显示文字、描述、上下文类型等。
- 使用示例
@UxAction(
name = "fullExampleAction",
displayName = "",
label = "",
summary = "",
contextType = ActionContextTypeEnum.SINGLE,
bindingType = {ViewTypeEnum.TABLE, ViewTypeEnum.FORM},
invisible = "",
rule = "allowExecute == true",
disable = "disableAction == true",
bindingView = "specificView",
priority = 75,
props = {
@Prop(name = "prop1", value = "value1"),
@Prop(name = "prop2", value = "value2")
}
)
- 属性说明：
name：动作名称。displayName：展示名称。label：显示文字。summary：描述。contextType：上下文类型，表示动作适用的上下文环境，默认为ActionContextTypeEnum.SINGLE。- 可选值：
SINGLE("SINGLE", "单行", "单行"),BATCH("BATCH", "多行", "只在多行出现，例如合并包裹的动作"),SINGLE_AND_BATCH("SINGLE_AND_BATCH", "单行和多行", "单行和多行"),CONTEXT_FREE("CONTEXT_FREE", "上下文无关", "上下文无关"),
bindingType：动作绑定在源模型上的哪些视图上，可指定多个视图类型，默认为{ViewTypeEnum.TABLE}。invisible：客户端显隐表达式。rule：服务端过滤表达式。disable：禁用规则。bindingView：绑定视图名称，设置动作只出现在指定视图。priority：优先级，用于设置动作的显示顺序，默认为99。props：扩展属性，用于设置动作的额外属性。
@UxClient
- 介绍：
- 用于标注在类上，表示这是一个链接动作的配置。
- 提供了一些属性，用于配置链接动作的客户端函数编码、链接计算函数模型、计算函数编码、数据传输映射DSL等。
- 使用示例
@UxClient(
value = "",
model = "",
compute = ,
mapping = {
@Prop(name = "mapProp1", value = "mapValue1"),
@Prop(name = "mapProp2", value = "mapValue2")
},
context = {
@Prop(name = "contextProp1", value = "contextValue1"),
@Prop(name = "contextProp2", value = "contextValue2")
}
)
- 属性说明：
value/fun：客户端函数编码，用于指定链接动作的客户端函数编码。model：链接计算函数模型，表示链接的计算函数模型。compute：计算函数编码，用于指定链接动作的计算函数编码。mapping：数据传输映射DSL，用于配置数据传输映射规则。context：上下文配置，用于配置链接动作的上下文信息。
@UxServer
- 介绍：
- 用于标注在类上，表示这是一个服务器动作的配置。
- 提供了一些属性，用于配置服务器动作的模型编码、动作名称、数据传输映射DSL等。
- 使用示例
@UxServer(
model = "",
name = "",
mapping = {
@Prop(name = "mapProp1", value = "mapValue1"),
@Prop(name = "mapProp2", value = "mapValue2")
},
context = {
@Prop(name = "contextProp1", value = "contextValue1"),
@Prop(name = "contextProp2", value = "contextValue2")
}
)
- 属性说明：
model：模型编码，表示服务器动作所属的模型。name：动作名称，用于指定服务器动作的名称。mapping：数据传输映射DSL，用于配置数据传输映射规则。context：上下文，用于配置服务器动作的上下文信息。
@UxClientButton
- 介绍：
- 用于标注在类上，表示这是一个链接按钮的配置。
- 通过
action属性指定了基本的动作配置。 - 通过
value属性指定了客户端动作配置。 - 使用
@Repeatable元注解，使得UxClientButton注解可以重复使用。
- 使用示例
@UxClientButton(
action = @UxAction(
name = "",
displayName = "",
label = "",
summary = "",
contextType = ActionContextTypeEnum.SINGLE,
bindingType = {ViewTypeEnum.TABLE},
invisible = "",
rule = "",
disable = "",
bindingView = {ViewTypeEnum.TABLE},
priority = 42,
props = {
@Prop(name = "prop1", value = "value1"),
@Prop(name = "prop2", value = "value2")
}
),
value = @UxClient(
fun = "",
model = "",
compute = "",
mapping = {
@Prop(name = "mapProp1", value = "mapValue1"),
@Prop(name = "mapProp2", value = "mapValue2")
},
context = {
@Prop(name = "contextProp1", value = "contextValue1"),
@Prop(name = "contextProp2", value = "contextValue2")
}
)
)
@UxClientButton.UxClientButtons(value = {})
- UxClientButtons 内部注解：
- 用于标注在类上，允许配置多个按钮。
- 通过
value属性配置多个按钮的数组。
- 属性说明：
action（UxAction）：动作基本配置，用于配置按钮的基本信息，包括名称、展示名称等。value（UxLink）：客户端动作配置，用于配置按钮的客户端动作，包括客户端函数编码、计算函数编码等。
@UxLinkButton
- 介绍：
- 用于标注在类上，表示这是一个链接按钮的配置。
- 通过
action属性指定了基本的动作配置。 - 通过
value属性指定了链接动作配置。 - 使用
@Repeatable元注解，使得UxLinkButton注解可以重复使用。
- 使用示例
@UxLinkButton(
action = @UxAction(
name = "",
displayName = "",
label = "",
summary = "",
contextType = ActionContextTypeEnum.SINGLE,
bindingType = {ViewTypeEnum.TABLE},
invisible = "",
rule = "",
disable = "",
bindingView = "",
priority = 99,
props = {
@Prop(name = "prop1", value = "value1"),
@Prop(name = "prop2", value = "value2")
}
),
value = @UxLink(
model = "exampleModel",
compute = "computeFunction",
params = {
@Param(name = "param1", value = "value1"),
@Param(name = "param2", value = "value2")
},
mapping = {
@Prop(name = "mappingProp1", value = "mappingValue1"),
@Prop(name = "mappingProp2", value = "mappingValue2")
},
context = {
@Prop(name = "contextProp1", value = "contextValue1"),
@Prop(name = "contextProp2", value = "contextValue2")
}
)
)
- UxLinkButtons 内部注解：
- 用于标注在类上，允许配置多个按钮。
- 通过
value属性配置多个按钮的数组。
- 属性说明：
action：动作基本配置，用于配置按钮的基本信息，包括名称、展示名称等。value：链接动作配置，用于配置按钮的链接动作，包括链接函数编码、计算函数编码等。
@UxRouteButton
- 介绍：
- 用于标注在类上，表示这是一个跳转按钮的配置。
- 通过
action属性指定了基本的动作配置。 - 通过
value属性指定了窗口动作配置。 - 使用
@Repeatable元注解，使得UxRouteButton注解可以重复使用。
- 使用示例
@UxRouteButton(
action = @UxAction(
),
value = @UxRoute(
)
)
- UxRouteButtons 内部注解：
- 用于标注在类上，允许配置多个按钮。
- 通过
value属性配置多个按钮的数组。
- 属性说明：
action：动作基本配置，用于配置按钮的基本信息，包括名称、展示名称等。value：窗口动作配置，用于配置按钮的窗口动作，包括窗口名称、路径等。
@Validation
- 介绍：
- 用于标注在类、方法或字段上，表示这是一个校验注解。
- 提供了以下属性：
check：模型约束-校验函数，配置校验函数编码列表。checkWithTips：模型约束-校验函数，配置函数编码及提示列表。rule：模型约束-校验表达式，配置校验表达式列表。ruleWithTips：模型约束-校验表达式，配置表达式及提示列表。
- 使用示例：
@Validation(
check = {"check1", "check2"},
checkWithTips = {
},
rule = {"rule1", "rule2"},
ruleWithTips = {
}
)
@Validation.Rule(value = "", tips = "", error = "", errorType = ErrorTypeEnum.BIZ_ERROR, level = InformationLevelEnum.ERROR)
@Validation.Fun(value = "", tips = "", scope = FunctionScopeEnum.SERVER)
- 嵌套注解 @Rule：
- 用于配置校验表达式的详细信息，包括以下属性：
value：校验表达式的内容。tips：校验表达式的提示信息。error：错误提示信息。errorType：错误类型，指定错误的类型，如业务错误。level：信息级别，指定信息的级别，如错误级别。remark：备注信息。scope：执行域，指定校验的执行域，包括前端、后端等。
- 用于配置校验表达式的详细信息，包括以下属性：
- 嵌套注解 @Fun：
- 用于配置校验函数的详细信息，包括以下属性：
value：校验函数的内容。tips：校验函数的提示信息。remark：备注信息。scope：执行域，指定校验的执行域，包括前端、后端等。
- 用于配置校验函数的详细信息，包括以下属性：
二、默认视图后端配置
这段代码涉及到UxTable、UxForm、UxDetail、UxTableSearch等组件，并有一些特殊点需要解释。以下是主要内容的总结：
- Group分组配置逻辑： 为了简化配置，实现字段分组，采用了第一个字段写了Group，之后出现的group之间的字段都自动归为同一个Group，避免在一个分组内的字段重复写Group。
- 搜索整体不展示： 可以通过在模型的类上使用“@UxTable(enableSearch = false)”配置，实现整体搜索栏的隐藏。
- 字段搜索配置： 使用“UxTableSearch”配置在模型的字段上，特殊逻辑是只要配置了一个字段，系统就不会自动添加其他字段。例如，表格页的搜索栏只会显示店铺名称和店铺编码，而不会自动补充其他字段。
……其他代码
//@UxTable(enableSearch = false)，整体不支持搜索
public class PetShop extends AbstractDemoIdModel {
public static final String MODEL_MODEL="demo.PetShop";
@Field(displayName = "店铺编码")
@UxForm.FieldWidget(@UxWidget(group = "Form基础数据"))//Form分组
@UxTableSearch.FieldWidget(@UxWidget())//支持搜索
private String code;
@Field(displayName = "店铺编码2")
@Field.Sequence(sequence = "DATE_ORDERLY_SEQ",prefix = "C",size=6,step=1,initial = 10000,format = "yyyyMMdd")
private String codeTwo;
@UxTableSearch.FieldWidget(@UxWidget())//支持搜索
@UxTable.FieldWidget(@UxWidget(invisible = "true"))//表格中不展示支持搜索
@Field(displayName = "店铺名称",required = true,immutable=true)
private String shopName;
@Field(displayName = "一年内新店")
@UxForm.FieldWidget(@UxWidget(widget = "Switch",group = "Form基础数据"))//Switch,Checkbox可以切换着看，字段可选widget参考【字段的配置】一文
private Boolean oneYear;
@Field(displayName = "开店时间",required = true)
@UxDetail.FieldWidget(@UxWidget(invisible = "true"))//详情不展示
private Time openTime;
@Field(displayName = "闭店时间",required = true)
@UxDetail.FieldWidget(@UxWidget(invisible = "true"))//详情不展示
private Time closeTime;
…… 其他代码
}