自定义列表页开发指南

概述

自定义列表页不是替代平台默认列表，开发者可以根据自身的业务需求自行编写页面结构与交互，实现自由风格的列表页。

• 页面形态：一个标准 Vue 组件。
• 运行位置：表单的「列表设计」中，为某张表单新增的自定义列表页。
• 前后端协作：前端通过 doAction 调用后端自定义逻辑，由后端返回业务数据。

运行环境约束

自定义列表页遵循标准 Vue 组件规范，但运行在氚云环境内，能力边界与普通 Vue 项目不同，以下四条是硬约束：

约束	说明
不支持引入外部依赖	不能 import 第三方库或 UI 组件库（如 Element UI、Vant 等），只能使用平台内置能力。
数据接入只能走氚云 API	数据只能通过氚云 API 同步调用后端自定义代码获取，不能自行发起任意 HTTP 请求。
交互组件使用氚云 API	弹窗、确认框、提示框等一律用氚云 API（H3API.* ）实现，不引入第三方组件。
遵循标准 Vue 组件规范	组件的结构、数据、生命周期等按标准 Vue 写法组织。

需要掌握的技术

开发自定义列表页需要同时具备前端与氚云平台两方面的能力，缺一不可：

技术 / 能力	在本文档中的用途	重要程度
Vue 组件开发	自定义列表页本身就是一个标准 Vue 组件：组件结构、data 、生命周期、事件绑定与列表渲染	核心
JavaScript（ES6+）	箭头函数、解构赋值、回调与异步控制流——示例代码全部基于此	核心
氚云平台概念	表单编码 schemaCode 、列表设计、自定义按钮、自定义列表页入口	必需
氚云前端 API（H3API）	弹窗、确认框、提示等交互组件，以及打开链接/表单、生成 UUID，见 API 参考	必需
后端自定义代码（C#）	列表数据、分页、删除等业务逻辑由后端提供，前端通过 doAction 调用；需能编写对应的后端接口	前后端配对时必需
HTML / CSS	手写页面的结构与样式（不套用平台默认样式，且不能引入 UI 组件库）	按需

前置说明

新增自定义列表页

列表设计 → 右侧属性面板的 表单名称 下拉选项 → 添加自定义列表页。

编写代码

自定义列表页是一个标准 Vue 组件。电脑端与移动端的代码编辑入口是分开的，点击对应的代码编辑按钮分别编写。

组件契约

本节是全文最重要的部分——写代码前请先确认组件里"有什么可用"。

从示例可观察到以下运行环境：

可用对象	来源	说明
this.context	Vue 组件实例	运行上下文，至少包含 schemaCode （当前表单编码）与 doAction （调用后端），actions(按钮), permission（字段权限）,properties（字段描述）
H3API	全局对象	平台工具集合，如 H3API.Common.UI.* 、H3API.Common.Utils.* 、H3API.SmartAction.*

上下文参考(this.context)

schemaCode

当前列表所属的表单编码，访问示例：this.context.schemaCode。

viewPageId

当前列表页的唯一标识，访问示例：this.context.viewPageId。

actions

当前列表页的所有按钮描述

[{
    "actionCode": "Create",
    "displayName": "新增",
    "icon": null,
    "styleType": null,
    "executeSetting": null,
    "selectable": false,
    "mergeBizData": false,
    "oldCode": "",
    "confirmInfo": null,
    "submitRule": null,
    "validateFieldConsistency": null,
    "hasAcl": true,
    "isCreatorOnly": false
}]

doAction

调用后端方法

// 参数：actionName 名称、schemaCode、自定义参数（分页、过滤条件等）、回调函数
this.context.doAction('action_name', this.context.schemaCode, { parmName: paramValue }, (data) => {
  // data 为后端返回值
  console.log(data);
  this.value = data.ReturnData.data;
});

permission

字段权限描述

[{
    "code": "CreatedBy", //字段编码
    "visible": true, //是否可见
    "editable": false, // 是否可编辑
    "required": false // 是否必填
}]

properties

当前表单的字段信息描述

[{
    "name": "CreatedBy", //字段编码
    "dataType": 26, // 字段类型
    "displayName": "创建人", // 字段显示名称
    "controlType": "FormCreater", // 控件类型
    "extension": {
        "defaultValueType": -1,
        "displayFormat": "",
        "isRollup": false,
        "associationSchemaCode": "",
        "fixedColNum": 0,
        "rowHeight": null,
        "isFormula": false,
        "referenceable": false,
        "summary": null,
        "voiceInput": false
    }
}]

API 参考

生成 UUID

const guidString = H3API.Common.Utils.guid();
console.log(guidString);

打开链接

// 新标签页打开
H3API.Common.Utils.openLink('https://www.baidu.com', H3API.SmartAction.OpenLinkType.Blank);

// 当前页面侧滑打开
H3API.Common.Utils.openLink('https://www.baidu.com', H3API.SmartAction.OpenLinkType.Self);

若链接地址来自用户数据，请自行做合法性校验，不要直接拼接执行。

打开表单弹窗

const that = this; // 保留当前作用域引用
H3API.Common.Utils.openForm({
  schemaCode: 'D00018smac7656a4b64d4c348fbb5cd2d3b11b7b', // 目标表单编码
  bizObjectId: '', // 数据 ID（留空则为新增页面）
  params: { param1: 'param1Value', param2: 'param2Value' }, // 自定义参数
  defaultValues: { F0000001: '新增时单行文本内容', F0000003: '2025-10-29' }, // 表单默认值
  modalConfig: {
    title: '打开测试表单填写数据',
    width: 800,
    height: 500,
    fullscreen: true // 优先级高于 width/height
  },
  closeCallback(actionCode, postValue) {
    console.log(actionCode);
    console.log(postValue);
  }
});

配置项	说明
schemaCode	目标表单编码
bizObjectId	数据 ID；留空表示新增
params	透传给目标表单的自定义参数
defaultValues	新增时的字段默认值，键为字段编码
modalConfig.title	弹窗标题
modalConfig.width/ height	弹窗尺寸
modalConfig.fullscreen	是否全屏，优先级高于 width/height
closeCallback(actionCode, postValue)	弹窗关闭后回调，可在此触发后端逻辑

Toast 提示框

支持 success、error、warning、info 四种类型（由 type 控制）。

H3API.Common.UI.toast({
  type: 'success', // error | warning | info
  content: '成功 toast 提示',
  onClose() {
    console.log('已关闭');
  }
});

参数	说明
type	success/ error/ warning/ info
content	提示文案
onClose	关闭后回调（可选）

数据加载框

H3API.Common.UI.loading({ title: '数据加载中...' }); // 持续显示
H3API.Common.UI.loading({ title: '数据加载中...', duration: 3 }); // 3 秒后关闭

确认提示框

支持 confirm、info、success、error、warning 五种样式。

type	按钮	说明
confirm	确定 + 取消	通常用于删除等破坏性操作，okText 可设为「删除」
info/ success / error/ warning	仅确定	不显示取消按钮

Confirm 确认框

H3API.Common.UI.dialog({
  type: 'confirm',
  title: '删除确认',
  content: '删除后将不可恢复，确定要删除？',
  okText: '删除',
  cancelText: '取消',
  onCancel() {},
  onOk() {
    // 执行删除操作
  }
});

其他类型确认框

H3API.Common.UI.dialog({
  type: 'info', // success | error | warning
  title: '删除确认',
  content: '删除后将不可恢复，确定要删除？',
  okText: '知道了',
  cancelText: '取消', // info 类型不显示取消按钮
  onCancel() {},
  onOk() {
    // 执行操作
  }
});

快速开始：一个完整的列表页

下面的示例串起了"确认框 → 加载中 → 后端取数 → 前端渲染"的完整链路，可作为起点。

前端代码

<template>
    <div>后台返回了消息：{{message}}</div>
</template>
<script>
export default {
    props: ['context'],
    components: {},
    data() {
        return {
            message: "",
        };
    },
    mounted() {
        const that = this; // 保留当前作用域引用
        console.log(this.context);
        H3API.Common.UI.dialog({
            type: 'confirm',
            title: '请求确认',
            content: '确定后将向后端发送请求，确定要执行？',
            okText: '确定',
            cancelText: '取消',
            onCancel() {},
            onOk() {
              // 执行请求操作
              // 参数 actionName的名称、schemaCode、自定义的参数（如后续要传分页、过滤条件等信息）、回调函数（能够获取到服务返回的信息） 
              H3API.Common.UI.loading({ title: '数据加载中...' });
              that.context.doAction('xxx', that.context.schemaCode, {"parmName": "你好，people!"}, (data) => {
                  // data为后端返回值
                  console.log(data);
                  H3API.Common.UI.loading({ title: '加载完成', duration: 1 });
                  that.message = data.ReturnData.message;
              })
          }
        });
    },
}
</script>
<style scoped></style>

后端代码

using System;
using System.Collections.Generic;
using System.Text;
using H3;

public class D00018sm7bb101dc078449e38abbe3c4de0a9e3a_ListViewController : H3.SmartForm.ListViewController
{
    public D00018sm7bb101dc078449e38abbe3c4de0a9e3a_ListViewController(H3.SmartForm.ListViewRequest request) : base(request)
    {
    }

    protected override void OnLoad(H3.SmartForm.LoadListViewResponse response)
    {
        base.OnLoad(response);
    }

    protected override void OnSubmit(string actionName, H3.SmartForm.ListViewPostValue postValue, H3.SmartForm.SubmitListViewResponse response)
    {
        if(actionName == "xxx")
        {
            string pValue = this.Request.GetValue<string>("parmName", "");
            if(response.ReturnData == null)
            {
                response.ReturnData = new Dictionary<string, object>();
            }
            response.ReturnData["message"] = pValue;
        }
        base.OnSubmit(actionName, postValue, response);
    }
}