PageView Spec

表达页面视图的定义语义。appRef 指向所属 App，不存在时安装器会自动创建同名 App。

定位与自然键

  • 自然键：appName + route。AppDefinitionWriteService.upsertPageView 先按 appRef.name 定位 App，再按 route 定位同一 App 下的页面。
  • appRef.name 为空时直接返回 UNCHANGED，不会创建页面。

PageViewSpecDTO

字段类型说明
appRefResourceRefDTO所属应用引用，安装器按 appRef.name 解析或创建 App
namestring页面名称
displayNamestring页面显示名称
descriptionstring未使用。写入服务不消费该字段。
routestring页面路由，与 appName 组成自然键
sortOrderinteger页面排序
schemaVersionstringSchema 版本，为空时默认 1.0
showInMenuboolean是否显示在菜单中
iconstring页面图标
rootPageWidgetNodeSpecDTO页面布局根节点，描述 widget 树结构
widgetsList<PageWidgetSpecDTO>页面 widget 列表，平铺定义每个 widget 的详细配置

子结构

ResourceRefDTO（appRef）

字段类型说明
kindstring未使用。appRef 仅消费 name。
namestringApp 自然键，用于定位或创建 App
apiNamestring未使用。appRef 仅消费 name。

PageWidgetNodeSpecDTO

页面布局树节点，表达 widget 的嵌套层级。

字段类型说明
widgetIdstringWidget 标识，与 widgets 列表中的 widgetId 对应
typestring节点类型。DASHBOARD_ROOT / ROOT / PAGE_ROOT / CONTAINER 归一化为 Container
childrenList<string>子节点 widgetId 列表

PageWidgetSpecDTO

字段类型说明
widgetIdstringWidget 标识，需在 root 树中被引用才能渲染
typestringWidget 类型，写入时归一化为运行时类型
positionWidgetPositionDTO布局位置信息，序列化为 JSON 写入 position_json
propsObject组件属性，可为对象或数组，序列化为 JSON
bindingsObject数据绑定配置，可为对象或数组，序列化为 JSON
filterBindingsList<WidgetFilterBindingDTO>过滤绑定配置列表，序列化为 JSON
linkagesObject联动配置，可为对象或数组，序列化为 JSON

Widget 类型归一化

后端 AppPageServiceImpl.normalizeWidgetType 在安装时将输入类型映射为运行时类型：

输入类型运行时类型说明
STAT_CARDCard统计卡片
KPI_CARDCardKPI 卡片
CARDCard普通卡片
CHARTChart / GeoMap当 props.chartType == "MAP" 时映射为 GeoMap，否则为 Chart
MAP / GEO_MAPGeoMap地图
TABLE / DATA_TABLEDataTable数据表格
GANTTGantt甘特图
TIMELINETimeline时间线
TEXTText文本
CONTAINERContainer容器
其他原值保留未命中上述映射时保持原类型字符串

WidgetPositionDTO

全部字段已消费，序列化为 JSON。

字段类型说明
hObject高度
wObject宽度
spaninteger栅格跨度
stackOnMobileboolean是否在移动端堆叠

WidgetFilterBindingDTO

全部字段已消费，序列化为 JSON。

字段类型说明
consumeAsstring消费方式：time_range 或 filter
filterKeystring筛选器 widget 的 filterKey
targetFieldstring目标字段

示例

appRef:
  name: Manufacturing
name: production_dashboard
route: /production/dashboard
schemaVersion: "1.0"
showInMenu: true
icon: LayoutDashboard
root:
  widgetId: root
  type: CONTAINER
  children:
    - total_output_card
    - yield_chart
    - work_order_table
widgets:
  - widgetId: total_output_card
    type: STAT_CARD
    position:
      span: 6
    props:
      title: 今日产量
      metricRef:
        kind: Metric
        name: total_output
  - widgetId: yield_chart
    type: CHART
    position:
      span: 12
    props:
      chartType: BAR
      metricRef:
        kind: Metric
        name: yield_rate
  - widgetId: work_order_table
    type: TABLE
    position:
      span: 12
    bindings:
      objectRef:
        kind: ObjectType
        name: work_order

消费位置

  • foundry-app-biz: AppDefinitionWriteService.upsertPageView 按 appRef.name 解析或创建 App，再按 appName + route 定位页面。
  • foundry-app-biz: AppPageServiceImpl.upsertPageBySemanticKey 将 PageViewSpecDTO 转换为 PageUpsertReqDTO 并写入 App / PageView runtime 表。
  • foundry-app-biz: AppDomainProjectionAdapter 调用 appDefinitionApi.upsertPageView。

相关文档