易企办开发者 / 自定义代码

自定义代码示例

从字段读取、列表查询和常见控件场景了解易企办自定义代码的实现方式。

结合完整模板阅读示例

下方介绍参数和输出模式。使用时请打开对应模板，查看完整 TSX、中文配置说明和目标环境的适用范围。

配置一张说明卡

在参数中填写标题和正文，验证 context.params 的值可以显示在表单中。这个入门示例只渲染配置的文字。

import React from "react";

export class CodeInApplication implements CodeInComp {
  description() {
    return "显示可配置的说明卡";
  }

  requiredFields() {
    return [];
  }

  inputParameters(): InputParameter[] {
    return [
      { id: "titleText", name: "标题", type: "string", desc: "显示在说明卡顶部" },
      { id: "bodyText", name: "正文", type: "string", desc: "显示在标题下方" },
    ];
  }

  render(context: CodeInContext) {
    const params = context.params || {};
    const title = typeof params.titleText === "string" && params.titleText.trim()
      ? params.titleText.trim()
      : "填写说明";
    const body = typeof params.bodyText === "string" ? params.bodyText.trim() : "";
    return <section aria-label={title}>
      <strong>{title}</strong>
      {body && <p>{body}</p>}
    </section>;
  }
}

配置月度数据表

把预算、实际支出或资源计划按月份展示，编辑后保存结构化数据。

参数	类型	用途
`yearFieldName`	string 或 variable	保存年份的当前字段
`monthFieldName`	string 或 variable	保存月份的当前字段
`tableConfig`	variable	行列、标签和默认值配置
`saveToField`	variable	表格结果的可写目标
`readonlyModeText`	string	只读状态的提示

[
  {
    "month": "2026-01",
    "planned": 12000,
    "actual": 9800,
    "notes": "等待最终发票"
  }
]

汇总仪表盘指标

数据查询与指标展示可按需要组合。查询组件核对来源列表、分页和筛选，展示组件接收整理后的指标数据。现有「指标卡组」模板使用 cardsConfig 接收卡片配置。

配置	用途	验收内容
`dataListId`	查询来源列表	当前用户的访问权限
`pageSize`	每页记录数量	分页完整性和加载状态
`filterField / filterValue`	筛选字段与条件	条件变更时重新查询
`cardsConfig`	指标卡组的卡片数据	指标名称、值和格式与来源一致

列表查询和智能选择器

根据参数读取记录、显示可选择的结果，再向绑定字段写入所需值。先验证列表访问权限和结果唯一标识。

参数	类型	用途
`dataListId`	variable	来源数据列表
`displayField / valueField`	variable	显示字段和保存值字段
`saveToField`	variable	保存完整 JSON 的可写目标
`selectedItemsField / newItemsField`	variable	分别保存已有记录和手工值
`multiSelect / allowManualEntry`	variable	是否多选及允许手工录入

[
  {
    "display": "华东示例制造公司",
    "value": "SUP-1024",
    "isManual": false,
    "source": "selected"
  }
]

插入变量的富文本编辑器

加载已有内容，提供可插入的变量清单，将最终内容写入已配置的目标。按业务用途确定保存 HTML、纯文本或 Markdown，并验证只读显示和内容重新加载。

参数	类型	用途
`initialContentField`	variable	已有内容
`saveToField`	variable	最终内容的可写目标
`availableVariables`	variable	可插入变量的 JSON 数组
`showToolbar`	variable	是否显示格式工具栏
`placeholderText`	string	空内容提示

[
  {
    "label": "客户名称",
    "token": "{{CustomerName}}"
  },
  {
    "label": "申请金额",
    "token": "{{RequestAmount}}"
  }
]

采集现场照片

巡检、现场问题和交付确认可通过相机或文件选择采集图片。结合宿主上传接口记录文件引用、拍摄时间和说明，保存后重新打开记录核对附件。

参数	类型	用途
`saveToField`	variable	图片引用或元数据保存目标
`maxPhotos`	string	图片数量上限
`allowNotes / requirePhoto`	variable	是否填写说明及要求照片
`labelText`	string	控件标题

[
  {
    "name": "现场巡检入口.jpg",
    "url": "https://example.com/file.jpg",
    "note": "门框有可见破损",
    "capturedAt": "2026-05-10T08:30:00.000Z"
  }
]

查询与异常处理片段

先检查 SDK 是否提供目标方法，再读取需要的字段。根据目标运行时处理返回行结构、空结果和失败反馈。以下片段需要放入完整的控件或动作中，并提供 listId。

const sdk = context.modules?.yeeSDKClient;
if (!sdk?.lists?.queryItems) {
  throw new Error("当前页面不支持数据查询");
}
const result = await sdk.lists.queryItems({
  listId,
  dataListId: listId,
  pageIndex: 1,
  pageNo: 1,
  pageSize: 20,
  fields: ["Title"],
  fieldIds: ["Title"],
});
// 按当前宿主返回的结构解析记录，并区分空结果与请求失败。

在表单中查询外部系统

例如在采购申请中按供应商编号查询主数据。先确认目标租户提供的外部查询方式，再把编号传给已授权的服务，只返回当前使用者需要的名称、状态和唯一标识。

在支持远程查找的表单中，将查询条件绑定到表单字段，并核对返回值的类型和映射。
由服务端保存外部接口凭据，核对调用身份、数据权限和查询范围。
用样本覆盖无匹配、重复匹配、无权限及服务超时。确认人员能识别查询失败和已成功选定的结果。

常用控件设计模式

月度数据表按配置选择期间和字段，在保存时校验数字与业务范围。
指标卡组汇总业务数据，并让用户找到数据来源和时间口径。
审批面板在表单中显示决策信息，并把处理结果交给流程。
富文本编辑器按需要插入变量，并检查输出格式与只读渲染。
拍照控件在有权限的环境中获取图片，并把结果交给附件或目标字段。

本页对照国际站文档整理为中文。示例的宿主接口与保存行为需在目标易企办环境中验证。

查看国际站原文查看易企办官方代码示例

继续阅读自定义代码模板