前端开发
华炎魔方微页面引擎,全新引入amis渲染器,帮助开发人员快速实现个性化界面需求。
华炎魔方微页面引擎,支持系统内不同类型的页面设计,包括:
设计好的页面可以通过“页面分配”来分配给不同的应用、简档用户以及区分手机端或PC端的页面显示,可以根据不同的业务场景来分配设计好的页面。
amis 是百度开源的低代码前端框架,它使用 JSON 配置来生成页面,可以减少页面开发工作量,极大提升效率。访问 amis 官网
以下步骤描述了如何在华炎魔方中使用微页面引擎amis自定义用户界面。
请先进入“设置”应用,点击左侧“用户界面->微页面”菜单,然后点击右上角的新建按钮即可开始新建微页面。
微页面新建好后,我们就可以点击右上角名为“设计器”的按钮打开微页面设计器来设计页面。
在设计器中我们可以根据业务需求拖动对应组件到画布中,然后为组件配置相关属性,也可以在设计器中编写相关脚本以对用户界面进行深度定制,详情请参阅后续小节 设计器。
页面设计完成后,我们需要点击设计器右上角或微页面记录详情界面右上角的“发布”按钮来发布设计器中设计好的页面内容,两个发布按钮没有区别。
需要注意的是,每次在设计器中修改设计后,需要点击发布按钮发布后才能让最终用户看到最新设计后的效果。
发布操作实际上是把当前最新的“页面版本”标记为“已发布”状态,最终用户看到的页面内容也是最新的已发布状态的页面版本,后续小节 页面版本 会介绍更多细节。
把设计好的微页面发布后,我们还需要为每个微页面配置访问权限才能让最终用户看到。
对于 页面类型 为“应用程序页面”的微页面,需要先把微页面绑定到 选项卡,用户只有通过选项卡才能访问到对应的微页面,详情请参阅后续 页面类型 - 应用程序页面 小节。
其他类型的微页面,请参考后续小节 页面分配 来配置每个微页面的访问权限,只有被授权的用户才能看到使用微页面定制后的界面效果。
我们在微页面中集成了amis可视化设计器,只要在微页面详情界面点击右上角的“设计器”按钮即可打开它,设计器本身是运行在 云端 的,但是在上面设计的内容会保存和发布到本地数据库中,也可以 同步为代码。
我们在微页面设计器中可以拖动左侧的组件到中间的画布中,然后在设计器右侧进一步配置各个组件的属性以实现相关功能。
组件有两种,一种是 amis 本身内置的组件,其使用方法请参阅其官网文档: amis组件,另一种则是 华炎魔方组件,这是我们为 amis 扩展的可以快速整合华炎魔方各种界面能力的相关功能组件。
在设计器的左侧可以快速切换“组件”、“大纲”与“代码”模块,在大纲模块中可以很方便查看页面上的组件层级结构,在代码模块中可以查看页面设计内容最终会生成的 Schema 代码,我们也可以修改代码。
页面设计完成后,可以点击设计器右上角的两个预览按钮,预览其在PC和手机端生成的页面效果,右上角还有保存和发布按钮,分别用于保存和发布设计器生成的Schema代码到数据库中。
我们为 amis 扩展了以下组件用于快速实现华炎魔方各种界面能力。
如果我们在设计器中拖动到画布中的是上面提到的华炎魔方组件,是不用操心界面与后台API接口的交互过程的,因为这些组件已经内置了相关功能。
但是如果我们想拖动一个amis原生的组件到画布中的话,一般来说都需要考虑与后台API接口的交互,amis原生组件中也有大量需要配置API接口的组件,以下是几种常见的API配置方法。
使用 GraphQL 很容易实现使用一条查询语句实现返回多表级联扩展查询结果,这种接口在实现除统计汇总外的列表查询、单记录查询时非常方便。
华炎魔方会自动为每个对象生成GraphQL接口,详情请参阅教程 Api Records GraphQL,这意味着不用编写任何代码就可以直接在amis组件中使用GraphQL接口,所以我们推荐大家首选这种方式来配合amis组件实现API交互功能。
查询设计器是另一种非常推荐大家为amis组件配置API接口的方案,这是一种可视化的查询设计工具,可以快速生成查询API接口,有统计汇总查询需求时,很适合使用这种方式与amis工具配合来实现数据分析功能,详情请参考 查询设计器。
在以上两种为amis组件配置API接口的方案都不适用时,我们还可以借助华炎魔方自定义接口的能力,实现任何复杂需求下的API接口,详情请参阅教程 自定义API。
使用amis渲染器的微页面支持以下几种页面类型,它们有各自的应用场景。
如果需要定制一个全新的应用程序页面,可以使用这种类型的微页面,使用它可以给系统新增加一个使用amis设计出来的定制页面,只要把它绑定到选项卡,用户就可以通过选项卡来访问这个页面。
比如我们可能需要为合同应用配置一个主页,在页面中显示各种合同收款、付款统计曲线或柱状图,再比如我们可能需要为协同办公应用配置一个主页,在页面中显示各种办公应用常用的列表数据。
假设我们已经设计好并发布了页面,以下步骤描述了如何把类型为“应用程序页面”的微页面绑定到选项卡并让最终用户看到它。
有时我们需要的并不是定制一个全新的应用页面,而是希望定制某个业务对象,比如合同对象的记录页面,用于替换系统内置的记录页面以实现个性化的记录详情页面显示效果。
要为某个业务对象定制记录页面,请参阅上面 如何配置 小节为该对象新建一个类型为“记录页面”的微页面,设计好并发布后,再通过 页面分配 来配置该微页面的访问权限。
与记录页面类似,“列表页面”类型的微页面是用于定制某个业务对象,比如合同对象的列表页面,可以替换掉系统内置的列表页面以实现个性化的列表页面显示效果。
要为某个业务对象定制列表页面,请参阅上面 如何配置 小节为该对象新建一个类型为“列表页面”的微页面,设计好并发布后,再通过 页面分配 来配置该微页面的访问权限。
与记录页面类似,“表单”类型的微页面是用于定制某个业务对象,比如合同对象的表单,可以替换掉在新建以及编辑记录时弹出的内置表单效果。
与记录页面不同,“表单”类型的微页面只会替换弹出的表单界面,并不会影响记录详情页面的只读界面效果,而“记录页面”类型的微页面正好相反,它会把整个记录详情页面的只读效果替换掉,但是并不会影响弹出的表单界面。
要为某个业务对象定制表单,请参阅上面 如何配置 小节为该对象新建一个类型为“表单”的微页面,设计好并发布后,再通过 页面分配 来配置该微页面的访问权限。
对于 页面类型 为“记录页面”、“列表页面”和“表单”的微页面,需要通过配置“页面分配”来配置哪些用户可以看到我们设计好的微页面。
我们可以根据不同的业务场景来分配设计好的页面,也就是说可以让用户在访问不同的应用,或者不同的简档下的用户看到不一样的页面效果。
在微页面记录详情界面可以看到一个名为“页面分配”的子表列表,我们点击该列表右上角的新建按钮可以新建一条页面分配记录。
我们可以为同一个微页面新建多个页面分配记录,它们都会生效。
以下表格描述了在页面分配中支持的三种授权类型对于微页面授权范围的区别:
授权类型 | 授权应用 | 授权简档 |
---|---|---|
组织默认设置 | 所有应用 | 所有简档 |
应用程序默认设置 | 仅限指定应用 | 所有简档 |
应用程序和简档 | 仅限指定应用 | 仅限指定简档 |
在微页面授权范围内的用户可以看到使用amis定制的页面效果,而不在授权范围内的用户看到的页面会是系统原来默认内置的页面效果。
比如假设我们为合同对象设计了一个类型为“记录页面”的使用amis引擎的微页面,并且在页面分配时只授权给“合同管理员”这个简档,那么合同管理员在查看合同记录详情界面时会看到我们定制的微页面,而其他用户看的则会是非定制的默认合同记录详情页面效果。
第一次在设计器中保存设计内容后,会生成一个页面版本,我们可以在微页面记录详情界面的“页面版本”子表中看到它。
每次点击发布按钮后会把当前最新的页面版本标记为“已发布”,而且后续每次在设计器中修改并保存已发布过的微页面都会生成一个新的待发布的页面版本。
我们在设计器中设计的页面内容最终是以 amis Schema 保存到每个页面版本中的,如果熟悉 amis Schema 语法,我们也可以直接在页面版本中修改它。
与其他元数据一样,上面提到的与微页面相关元数据,包括业务人员通过查询设计器生成的查询API、页面设计器设计的页面、页面分配、页面版本以及选项卡等都可以同步为代码,同步这些元数据的方法与其他元数据是一样的,详细操作方法可以参考 开发人员快速向导 中的 同步元数据 小节。
类型 | 节点 | 同步到文件夹 |
---|---|---|
查询 | Queries | main/default/queries |
微页面 | Pages | main/default/pages |
选项卡 | Tabs | main/default/tabs |
以上表格中“节点”列表示的是不同元数据类型在VSCODE编辑器里的Steedos插件面板中所处节点位置。
其中在页面设计器设计的页面内容会保存到页面版本中,它会以 amis Schema 格式同步保存到main/default/pages/xxx.page.amis.json
文件中,但是只会保存最后一个已发布的版本中的内容。
另外“页面分配”会同步到微页面元数据,即main/default/pages/xxx.page.yml
文件的“pageAssignments”属性中。
amis 本身提供了非常丰富的组件功能,基本它可以实现大部分业务场景的UI界面需求。
如果遇到适合自己开发自定义组件的场景,我们也可以通过自定义资产包来把自定义组件集成到amis设计器中,这样我们就可以实现任何我们想要的UI效果了。
只要把自定义资产包地址配置到环境变量 STEEDOS_PUBLIC_PAGE_ASSETURLS
中,华炎魔方会根据资产包中配置的资源包地址自动把相关自定义组件加载并集成到amis引擎中,非常方便。
STEEDOS_PUBLIC_PAGE_ASSETURLS=https://unpkg.com/@steedos-widgets/example@0.0.6/dist/assets.json
资产包的地址只要可以访问即可,它可以是发布到npm的包(unpkg.com)地址,也可以是其他任何可以被当前服务访问的地址,比如在远程开发环境中公开的资产包地址。
下面的示例 amis-custom-components 完整演示了如何在华炎魔方项目中通过引用自定义资产包的方式来集成自定义组件。
关于自定义资产包及自定义组件的开发,请参考下面的示例 steedos-widgets。
https://github.com/steedos/steedos-examples/tree/main/with-amis
里面有一些使用 amis 配置仪表盘的完整示例。
https://github.com/steedos/steedos-examples/tree/main/with-amis-custom-components
完整演示了如何在魔方项目中引用自定义资产包来实现自定义 amis 组件。
演示了如何开发一个名为 Hello 的自定义React组件,并把它发布为可供华炎魔方项目引用的资产包。
https://github.com/steedos/steedos-widgets/blob/master/packages/example