Amis 微页面

​

微页面引擎

华炎魔方微页面引擎，支持系统内不同类型的页面设计，包括：

• 应用程序页面：全新的页面，可以用来设计企业业务数据看板、驾驶舱数据页面等；
• 记录页面：数据记录的详情页；
• 列表页面：对象数据列表页；
• 表单页面：数据新建、编辑页面；

设计好的页面可以通过“页面分配”来分配给不同的应用、简档用户以及区分手机端或PC端的页面显示，可以根据不同的业务场景来分配设计好的页面。

​

amis前端低代码框架

amis 是百度开源的低代码前端框架，它使用 JSON 配置来生成页面，可以减少页面开发工作量，极大提升效率。访问 amis 官网

• 提供完整的界面解决方案：其它 UI 框架必须使用 JavaScript 来组装业务逻辑，而 amis 只需 JSON 配置就能完成完整功能开发，包括数据获取、表单提交及验证等功能，做出来的页面不需要经过二次开发就能直接上线；
• 大量内置组件（120+），一站式解决：其它 UI 框架大部分都只有最通用的组件，如果遇到一些稍微不常用的组件就得自己找第三方，而这些第三方组件往往在展现和交互上不一致，整合起来效果不好，而 amis 则内置大量组件，包括了富文本编辑器、代码编辑器、diff、条件组合、实时日志等业务组件，绝大部分中后台页面开发只需要了解 amis 就足够了；
• 支持扩展：除了低代码模式，还可以通过 自定义组件 来扩充组件，实际上 amis 可以当成普通 UI 库来使用，实现 90% 低代码，10% 代码开发的混合模式，既提升了效率，又不失灵活性；
• 容器支持无限级嵌套：可以通过嵌套来满足各种布局及展现需求；
• 经历了长时间的实战考验：amis 在百度内部得到了广泛使用，在 6 年多的时间里创建了 5 万页面，从内容审核到机器管理，从数据分析到模型训练，amis 满足了各种各样的页面需求，最复杂的页面有超过 1 万行 JSON 配置。

​

如何配置

以下步骤描述了如何在华炎魔方中使用微页面引擎amis自定义用户界面。

​

新建微页面

请先进入“设置”应用，点击左侧“用户界面->微页面”菜单，然后点击右上角的新建按钮即可开始新建微页面。

• Api名称：请输入不与其他微页面重名的Api名称。
• 名称：请输入微页面显示名称。
• 渲染器：请选择Amis。
• 状态：用于控制微页面是否可用。
• 类型：amis引擎的微页面支持的页面类型，各个页面类型的详细说明请参阅后续小节 页面类型。
• 对象：类型为“记录页面”、“列表页面”和“表单”时，需要选择要绑定的对象。

​

设计页面

微页面新建好后，我们就可以点击右上角名为“设计器”的按钮打开微页面设计器来设计页面。

在设计器中我们可以根据业务需求拖动对应组件到画布中，然后为组件配置相关属性，也可以在设计器中编写相关脚本以对用户界面进行深度定制，详情请参阅后续小节 设计器。

​

发布

页面设计完成后，我们需要点击设计器右上角或微页面记录详情界面右上角的“发布”按钮来发布设计器中设计好的页面内容，两个发布按钮没有区别。

需要注意的是，每次在设计器中修改设计后，需要点击发布按钮发布后才能让最终用户看到最新设计后的效果。

发布操作实际上是把当前最新的“页面版本”标记为“已发布”状态，最终用户看到的页面内容也是最新的已发布状态的页面版本，后续小节 页面版本 会介绍更多细节。

​

配置权限

把设计好的微页面发布后，我们还需要为每个微页面配置访问权限才能让最终用户看到。

对于 页面类型 为“应用程序页面”的微页面，需要先把微页面绑定到 选项卡，用户只有通过选项卡才能访问到对应的微页面，详情请参阅后续 页面类型 - 应用程序页面 小节。

其他类型的微页面，请参考后续小节 页面分配 来配置每个微页面的访问权限，只有被授权的用户才能看到使用微页面定制后的界面效果。

​

设计器

我们在微页面中集成了amis可视化设计器，只要在微页面详情界面点击右上角的“设计器”按钮即可打开它，设计器本身是运行在 云端 的，但是在上面设计的内容会保存和发布到本地数据库中，也可以 同步为代码。

​

页面设计

我们在微页面设计器中可以拖动左侧的组件到中间的画布中，然后在设计器右侧进一步配置各个组件的属性以实现相关功能。

组件有两种，一种是 amis 本身内置的组件，其使用方法请参阅其官网文档： amis组件，另一种则是 华炎魔方组件，这是我们为 amis 扩展的可以快速整合华炎魔方各种界面能力的相关功能组件。

在设计器的左侧可以快速切换“组件”、“大纲”与“代码”模块，在大纲模块中可以很方便查看页面上的组件层级结构，在代码模块中可以查看页面设计内容最终会生成的 Schema 代码，我们也可以修改代码。

页面设计完成后，可以点击设计器右上角的两个预览按钮，预览其在PC和手机端生成的页面效果，右上角还有保存和发布按钮，分别用于保存和发布设计器生成的Schema代码到数据库中。

​

华炎魔方组件

这是我们为 amis 扩展了以下组件用于快速实现华炎魔方各种界面能力。

​

华炎魔方容器

这是一个容器组件，理论上需要进行数据交互的组件都应该放到该组件中，该容器组件可以自动获取包括当前登录用户id，token等可用于数据交互的环境变量值。

• rootUrl：华炎魔方服务访问地址。
• tenantId：华炎魔方id。
• userId：用户id。
• authToken：用户登录后的token。

​

对象表单

这是一个用于显示、新建或编辑对象记录的表单组件。

只要为其配置以下简单的属性即可快速实现对象表单的相关功能：

• 对象Api名称：要关联到的对象，默认取值为当前对象Api名称。
• 记录ID：要关联到的对象记录，默认取值为当前对象记录的ID值。
• 显示状态：显示为只读还是编辑状态。
• 表单布局：显示为横向还是纵向布局效果。

​

列表视图

这是一个华炎魔方列表视图组件，它把对象记录显示为表格，同时包含了对象记录的增删改查以及其他操作按钮功能。

只要为其配置以下简单的属性即可快速生成一个功能完善的列表视图组件：

• 对象名：要关联到的对象，默认取值为当前对象Api名称。
• 列表视图名：要关联到的对象列表视图，默认取值“all”，即“所有”视图。

​

相关列表

这是一个华炎魔方相关列表视图组件，一般用于在记录详情界面显示相关子表列表，它把对象相关表记录显示为表格，同时包含了对象记录的增删改查以及其他操作按钮功能。

只要为其配置以下简单的属性即可快速生成一个功能完善的相关列表视图组件：

• 父级对象：要关联到的父对象，即相关列表所关联到的主表记录对象名，默认取值为当前对象Api名称。
• 父级记录：要关联到的父对象记录，即相关列表所关联到的主表记录ID值，默认取值为当前对象记录的ID值。
• 相关列表对象：要显示的是哪个相关对象的列表，需要输入对象Api名称，默认取值为空。

比如想在合同记录详情界面显示付款子表列表，应该在“相关列表对象”属性中输入付款对象的Api名称，在“父级对象”属性中可以输入合同对象的Api名称。

​

标题面板

这是一个会显示当前对象显示名称和当前记录显示名称的面板组件，一般用于在记录详情界面顶部显示标题信息。

该组件最核心的价值在于会在右侧显示出当前登录用户对当前对象记录有操作权限操作按钮，比如编辑、删除、打印等操作按钮。

只要为其配置以下简单的属性即可快速生成一个功能完善的标题面板组件：

• 对象名称：要关联到的对象，默认取值为当前对象Api名称。
• 记录Id：要关联到的对象记录，默认取值为当前对象记录的ID值。

​

关于API

如果我们在设计器中拖动到画布中的是上面提到的华炎魔方组件，是不用操心界面与后台API接口的交互过程的，因为这些组件已经内置了相关功能。

但是如果我们想拖动一个amis原生的组件到画布中的话，一般来说都需要考虑与后台API接口的交互，amis原生组件中也有大量需要配置API接口的组件，以下是几种常见的API配置方法。

​

对象GraphQL接口

使用 GraphQL 很容易实现使用一条查询语句实现返回多表级联扩展查询结果，这种接口在实现除统计汇总外的列表查询、单记录查询时非常方便。

华炎魔方会自动为每个对象生成GraphQL接口，详情请参阅教程 Api Records GraphQL，这意味着不用编写任何代码就可以直接在amis组件中使用GraphQL接口，所以我们推荐大家首选这种方式来配合amis组件实现API交互功能。

​

查询设计器

查询设计器是另一种非常推荐大家为amis组件配置API接口的方案，这是一种可视化的查询设计工具，可以快速生成查询API接口，有统计汇总查询需求时，很适合使用这种方式与amis工具配合来实现数据分析功能，详情请参考 查询设计器。

​

自定义接口

在以上两种为amis组件配置API接口的方案都不适用时，我们还可以借助华炎魔方自定义接口的能力，实现任何复杂需求下的API接口，详情请参阅教程 自定义API。

​

页面类型

使用amis渲染器的微页面支持以下几种页面类型，它们有各自的应用场景。

​

应用程序页面

如果需要定制一个全新的应用程序页面，可以使用这种类型的微页面，使用它可以给系统新增加一个使用amis设计出来的定制页面，只要把它绑定到选项卡，用户就可以通过选项卡来访问这个页面。

比如我们可能需要为合同应用配置一个主页，在页面中显示各种合同收款、付款统计曲线或柱状图，再比如我们可能需要为协同办公应用配置一个主页，在页面中显示各种办公应用常用的列表数据。

假设我们已经设计好并发布了页面，以下步骤描述了如何把类型为“应用程序页面”的微页面绑定到选项卡并让最终用户看到它。

• 进入“设置”应用，点击左侧“用户界面->选项卡”菜单，然后点击其右上角的新建按钮来新建一个选项卡。
• 在新建选项卡时，“类型”请选择“页面”，然后在“页面”属性中选择我们刚发布的需要绑定到选项卡的微页面。
• 点击“设置”应用的左侧菜单“应用程序->应用程序”，新建一个应用或编辑已有应用，在应用的选项卡属性中选择刚新建的选项卡。
• 刷新浏览器后点击左上角的九宫格，在弹出的“应用程序启动器”中点击进入刚新建的应用。
• 此时在顶部导航栏中可以看到刚新建好的选项卡，点击该选项卡即可进入我们之前使用amis设计好的定制页面。

​

记录页面

有时我们需要的并不是定制一个全新的应用页面，而是希望定制某个业务对象，比如合同对象的记录页面，用于替换系统内置的记录页面以实现个性化的记录详情页面显示效果。

要为某个业务对象定制记录页面，请参阅上面 如何配置 小节为该对象新建一个类型为“记录页面”的微页面，设计好并发布后，再通过 页面分配 来配置该微页面的访问权限。

​

列表页面

与记录页面类似，“列表页面”类型的微页面是用于定制某个业务对象，比如合同对象的列表页面，可以替换掉系统内置的列表页面以实现个性化的列表页面显示效果。

要为某个业务对象定制列表页面，请参阅上面 如何配置 小节为该对象新建一个类型为“列表页面”的微页面，设计好并发布后，再通过 页面分配 来配置该微页面的访问权限。

​

表单

与记录页面类似，“表单”类型的微页面是用于定制某个业务对象，比如合同对象的表单，可以替换掉在新建以及编辑记录时弹出的内置表单效果。

与记录页面不同，“表单”类型的微页面只会替换弹出的表单界面，并不会影响记录详情页面的只读界面效果，而“记录页面”类型的微页面正好相反，它会把整个记录详情页面的只读效果替换掉，但是并不会影响弹出的表单界面。

要为某个业务对象定制表单，请参阅上面 如何配置 小节为该对象新建一个类型为“表单”的微页面，设计好并发布后，再通过 页面分配 来配置该微页面的访问权限。

​

页面分配

对于 页面类型 为“记录页面”、“列表页面”和“表单”的微页面，需要通过配置“页面分配”来配置哪些用户可以看到我们设计好的微页面。

我们可以根据不同的业务场景来分配设计好的页面，也就是说可以让用户在访问不同的应用，或者不同的简档下的用户看到不一样的页面效果。

在微页面记录详情界面可以看到一个名为“页面分配”的子表列表，我们点击该列表右上角的新建按钮可以新建一条页面分配记录。

• 授权类型：请选择要配置的授权类型，有三个可选项，组织默认设置、应用程序默认设置、应用程序和简档。
• 页面：会自动选中当前微页面，无需变更。
• 应用：当授权类型为“应用程序默认设置”或“应用程序和简档”时，需要选择在且仅存哪个应用下该微页面生效。
• 简档：当授权类型为“应用程序和简档”时，除了要选择应用外，还需要选择该微页面在且仅在哪个 简档 下的用户才生效。
• 桌面端：勾选表示该微页面会显示在桌面端。
• 移动端：勾选表示该微页面会显示在手机设备上。

我们可以为同一个微页面新建多个页面分配记录，它们都会生效。

以下表格描述了在页面分配中支持的三种授权类型对于微页面授权范围的区别：

在微页面授权范围内的用户可以看到使用amis定制的页面效果，而不在授权范围内的用户看到的页面会是系统原来默认内置的页面效果。

比如假设我们为合同对象设计了一个类型为“记录页面”的使用amis引擎的微页面，并且在页面分配时只授权给“合同管理员”这个简档，那么合同管理员在查看合同记录详情界面时会看到我们定制的微页面，而其他用户看的则会是非定制的默认合同记录详情页面效果。

​

页面版本

第一次在设计器中保存设计内容后，会生成一个页面版本，我们可以在微页面记录详情界面的“页面版本”子表中看到它。

每次点击发布按钮后会把当前最新的页面版本标记为“已发布”，而且后续每次在设计器中修改并保存已发布过的微页面都会生成一个新的待发布的页面版本。

我们在设计器中设计的页面内容最终是以 amis Schema 保存到每个页面版本中的，如果熟悉 amis Schema 语法，我们也可以直接在页面版本中修改它。

​

同步为代码

与其他元数据一样，上面提到的与微页面相关元数据，包括业务人员通过查询设计器生成的查询API、页面设计器设计的页面、页面分配、页面版本以及选项卡等都可以同步为代码，同步这些元数据的方法与其他元数据是一样的，详细操作方法可以参考 开发人员快速向导 中的 同步元数据 小节。

以上表格中“节点”列表示的是不同元数据类型在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。

​

示例

​

amis-dashboard

https://github.com/steedos/steedos-examples/tree/main/with-amis

里面有一些使用 amis 配置仪表盘的完整示例。

​

amis-custom-components

https://github.com/steedos/steedos-examples/tree/main/with-amis-custom-components

完整演示了如何在魔方项目中引用自定义资产包来实现自定义 amis 组件。

​

steedos-widgets

演示了如何开发一个名为 Hello 的自定义React组件，并把它发布为可供华炎魔方项目引用的资产包。

https://github.com/steedos/steedos-widgets/blob/master/packages/example