Yida Custom Page

宜搭自定义页面开发技能

概述

本技能提供在阿里宜搭低代码平台上开发自定义页面的完整能力，涵盖从编码到部署的全流程：

何时使用

当以下场景发生时使用此技能：

• 用户需要开发自定义展示页面（非表单）
• 用户需要实现复杂的页面交互逻辑
• 用户需要调用宜搭 JS API 进行数据操作
• 已有自定义页面，需要编写或修改 JSX 代码

使用示例

注意：编译和发布功能由 yida-publish-page 技能提供，此处仅作流程说明。

示例 1：编译源码

场景：将 JSX 源码编译为宜搭可用的格式 依赖：需先安装 yida-publish-page 依赖 命令：

cd .claude/skills/yida-publish-page/scripts && npm install
node babel-transform/transform.js pages/src/my-page.js

示例 2：发布页面

场景：编译并发布自定义页面到宜搭平台 命令：

node .claude/skills/yida-publish-page/scripts/publish.js APP_XXX FORM-XXX pages/src/my-page.js

快速开始

前置条件

• Node.js 16+（用于 Babel 编译和发布）
• Python 3.12+ + playwright（用于登录态管理）
• 首次使用需安装依赖：

cd .claude/skills/yida-publish/scripts && npm install
pip install playwright && playwright install chromium

编译源码

node scripts/babel-transform/transform.js <源文件路径>

编译流程：

源文件(.js) → @ali/vu-babel-transform (Babel 转换) → UglifyJS (压缩) → <name>.compile.js

部署到宜搭

cd .claude/skills/yida-publish-page/scripts
npm install  # 首次需要安装依赖
node publish.js <appType> <formUuid> <源文件路径>

部署流程：

编译源码（Babel + UglifyJS） → 代码动态构建 Schema JSON（填入 source/compiled）
→ 调用 yida-login 获取登录态（Cookie 持久化） → 调用 saveFormSchema 接口保存

参数说明：

baseUrl 无需手动传入，脚本会自动调用 login.py 获取登录态并从中读取 base_url。

开发规范

以下规范是编写宜搭自定义页面代码的核心约束，必须严格遵守。

运行环境与约束

宜搭自定义页面的 JSX 组件本质上是 React 类组件中的 render 方法，而非独立的 React 组件。因此存在以下关键约束：

文件结构

一个完整的宜搭自定义页面源文件必须包含：

• _customState 变量
• getCustomState 函数
• setCustomState 函数
• forceUpdate 函数
• didMount 函数
• didUnmount 函数
• renderJsx 函数

以下是一个完整自定义页面示例，包含状态管理、生命周期钩子、渲染函数

// ============================================================
// 状态管理
// ============================================================

const _customState = {
  // 在此定义所有业务状态的初始值
  count: 0,
  loading: false,
};

/**
 * 获取状态
 * @param {string} [key] - 传入 key 返回单个值，不传返回全部状态的浅拷贝
 */
export function getCustomState(key) {
  if (key) {
    return _customState[key];
  }
  return { ..._customState };
}

/**
 * 设置状态（合并更新，自动触发重新渲染）
 * @param {Object} newState - 需要更新的状态键值对
 */
export function setCustomState(newState) {
  Object.keys(newState).forEach(function(key) {
    _customState[key] = newState[key];
  });
  this.forceUpdate();
}

/**
 * 强制重新渲染（通过更新 timestamp 触发 React 重渲染）
 */
export function forceUpdate() {
  this.setState({ timestamp: new Date().getTime() });
}

// ============================================================
// 生命周期
// ============================================================

/**
 * 页面加载完成时调用
 * 用于：初始化数据、启动定时器、绑定事件等
 */
export function didMount() {
  // 初始化逻辑
}

/**
 * 页面卸载时调用
 * 用于：清理定时器、解绑事件、释放资源等
 */
export function didUnmount() {
  // 清理逻辑
}

export function handleSubmit(e) {
  this.setCustomState({ submitted: true });
  this.utils.toast({ title: '提交成功', type: 'success' });
}
// ============================================================
// 渲染
// ============================================================

/**
 * 页面渲染函数（等同于 React 类组件的 render 方法）
 * 注意：必须包含隐藏的 timestamp div 以支持 forceUpdate 机制
 */
export function renderJsx() {
  const { timestamp } = this.state;

  return (
    <div>
      {/* 必须保留：用于触发重新渲染 */}
      <div style={{ display: "none" }}>{timestamp}</div>

      {/* 页面内容写在这里 */}
      <div => {this.handleSubmit(e)}>提交</div>
    </div>
  );
}

状态管理使用方式

// 获取全部状态（返回浅拷贝）
const state = this.getCustomState();

// 获取单个状态值
const count = this.getCustomState('count');

// 设置状态并自动触发重新渲染
this.setCustomState({ count: count + 1, loading: true });

// 仅触发重新渲染（不修改状态）
this.forceUpdate();

生命周期钩子

全局变量

编码注意事项

1. 自定义方法必须用 export function 定义：凡是需要在方法内部使用 this（包括 this.utils.yida.*、this.setCustomState 等）的自定义方法，必须且只能使用 export function 方法名() {} 的形式定义，调用时使用 this.方法名()。禁止使用 const fn = () => {}、const fn = function() {} 等形式定义需要访问 this 的方法，这些形式无法被宜搭运行时正确绑定 this：

   // ✅ 正确：export function + this.方法名() 调用
   export function didMount() {
     this.loadStatistics();
   }
   export function loadStatistics() {
     this.utils.yida.searchFormDatas({ formUuid: 'FORM-XXX', pageSize: 10 });
   }
   
   // ❌ 错误①：缺少 export，无法被宜搭运行时识别，this 丢失
   export function didMount() {
     loadStatistics();  // 直接调用，this 丢失
   }
   function loadStatistics() {
     this.utils.yida.searchFormDatas(...);  // 报错：this is undefined
   }
   
   // ❌ 错误②：箭头函数/函数表达式形式，缺少 export，无法被宜搭运行时绑定 this，禁止使用
   const loadStatistics = () => {
     this.utils.yida.searchFormDatas(...);  // 报错：this is undefined
   };
   const loadStatistics = function() {
     this.utils.yida.searchFormDatas(...);  // 报错：this is undefined
   };
   

2. 【严格禁止】事件绑定必须使用箭头函数包裹：在 renderJsx 中绑定任何事件处理器（onClick、onChange、onSubmit 等）时，必须且只能使用箭头函数 (e) => { this.方法名(e) } 的形式，严禁直接写 this.方法名 作为事件处理器，否则 this 会丢失导致运行时报错：

   export function handleSubmit(e) {
     this.setCustomState({ submitted: true });
     this.utils.toast({ title: '提交成功', type: 'success' });
   }
   
   // ✅ 正确：箭头函数包裹，this 正确捕获
   export function renderJsx() {
     return <button => { this.handleSubmit(e); }}>提交</button>;
   }
   
   // ❌ 错误①：直接传方法引用，this 丢失，运行时报错，绝对禁止！
   export function renderJsx() {
     return <button
   }
   
   // ❌ 错误②：使用 .bind(this) 绑定，虽然能运行但不符合规范，禁止使用！
   export function renderJsx() {
     return <button { this.handleSubmit(); }.bind(this)}>提交</button>;
   }
   

   生成代码时的自检清单：检查 renderJsx 中所有 onClick、onChange、onSubmit 等事件属性，确保每一个都是 (e) => { this.xxx(e) } 形式，不存在任何 onClick={this.xxx} 的写法。

3. 输入法组合输入处理：使用 _isComposing 标记配合 compositionstart / compositionend 事件，正确处理中文输入法的组合输入状态，避免输入过程中触发提交

4. 定时器清理：在 didUnmount 中必须清理所有通过 setInterval / setTimeout 创建的定时器，防止内存泄漏

5. 错误处理：所有 API 调用（this.utils.yida.*、fetch）必须使用 .catch() 处理异常，并通过 this.utils.toast({ title: message, type: 'error' }) 向用户展示错误提示

6. 样式方式：所有样式通过 JavaScript 对象定义（内联样式），在 renderJsx 中通过 style 属性应用，不使用外部 CSS 文件

7. 异步操作：可以使用 async/await 语法，Babel 编译会自动转换为 ES5 兼容代码

8. pageSize 上限：调用 searchFormDatas、searchFormDataIds、getProcessInstances、getProcessInstanceIds 等分页接口时，pageSize 最大值为 100，超过会导致接口报错。禁止将 pageSize 设置为超过 100 的值，推荐使用 10～100 之间的合理值。

9. 输入框使用非受控组件：在宜搭环境中，<input> 的 value 属性绑定状态后会触发重渲染导致输入异常。正确做法：使用 defaultValue，在 onChange 中更新 _customState 而不调用 setCustomState：

   // ❌ 错误：受控组件，每次输入都触发重渲染导致无法输入
   <input value={userAnswer} { this.setCustomState({ userAnswer: e.target.value }); }} />
   
   // ✅ 正确：非受控组件，仅静默更新状态，不触发重渲染
   <input id="my-input" defaultValue="" { _customState.userAnswer = e.target.value; }} />
   
   // 需要清空时通过 DOM 操作
   var inputEl = document.getElementById("my-input");
   if (inputEl) { inputEl.value = ""; }
   

10. DateField 时间戳格式：保存日期字段时，值必须是 时间戳（毫秒），不能是字符串：

    // ❌ 错误：字符串格式
    dateField_xxx: '2024-01-15'
    
    // ✅ 正确：时间戳格式
    dateField_xxx: new Date().getTime()
    

11. 多端适配：宜搭自定义页面会在 PC 端和移动端同时展示，使用 this.utils.isMobile() 判断设备类型：

    const isMobile = this.utils.isMobile();
    var styles = {
      container: { padding: isMobile ? '12px' : '16px', minHeight: '100vh' },
      card: { padding: isMobile ? '12px' : '16px', marginBottom: isMobile ? '8px' : '12px' },
    };
    

12. 清除默认样式：宜搭自定义页面容器有默认 padding 和圆角，需要强制覆盖：

    var styles = {
      container: { padding: '0 16px', borderRadius: '0 !important', minHeight: '100vh' },
    };
    

13. 性能优化：

    • 不要在每次 onChange 都调用 setCustomState，可直接写入 _customState 静默更新
    • 只在需要触发重渲染时才调用 forceUpdate
    • 在 renderJsx 顶部定义事件处理函数，避免每次渲染都创建新的内联函数

14. 调试技巧：

    // 打印当前状态到控制台
    console.log('当前状态:', _customState);
    
    // 弹窗提示（适合快速验证逻辑）
    this.utils.toast({ title: '调试信息', type: 'info' });
    

15. iframe 嵌入表单 URL 规范：在自定义页面中通过 iframe 嵌入宜搭表单时，需使用正确的 URL 格式：

    场景	URL 格式
    表单提交页	{base_url}/{appType}/submission/{formUuid}
    数据管理页（列表）	{base_url}/{appType}/workbench/{formUuid}?iframe=true
    数据管理页（指定视图）	{base_url}/{appType}/workbench/{formUuid}?viewUuid={viewUuid}&iframe=true

    // ❌ 错误：formDetail 是表单详情页，不是数据列表
    const wrongUrl = `${baseUrl}/${appType}/formDetail/${formUuid}`;
    
    // ✅ 正确：workbench 是运行态数据管理页
    const listUrl = `${baseUrl}/${appType}/workbench/${formUuid}?iframe=true`;
    

    viewUuid 可选，从宜搭「数据管理」→「报表视图」页面的 URL 中获取，不传则使用默认视图。

API 参考

表单数据操作

通过 this.utils.yida.<方法名>(params) 调用，所有接口返回 Promise。

常用示例 — 新建表单数据：

this.utils.yida.saveFormData({
  formUuid: 'FORM-XXX',
  appType: window.pageConfig.appType,
  formDataJson: JSON.stringify({
    textField_xxx: '单行文本',
    textareaField_xxx: '多行文本',
  }),
}).then(function(res) {
  console.log('新建成功，实例ID:', res.result);
}).catch(function(err) {
  this.utils.toast({ title: err.message, type: 'error' });
}.bind(this));

常用示例 — 搜索表单数据：

this.utils.yida.searchFormDatas({
  formUuid: 'FORM-XXX',
  searchFieldJson: JSON.stringify({ textField_xxx: '查询值' }),
  currentPage: 1,
  pageSize: 10,
}).then(function(res) {
  // res.data: [{ formUuid, formInstId, formData: { textField_xxx: '值' } }]
  // res.totalCount: 符合条件的总数
  console.log('查询结果:', res.data);
}).catch(function(err) {
  this.utils.toast({ title: err.message, type: 'error' });
}.bind(this));

流程操作

表单设计类 API

以下接口用于表单页面的创建和配置，通过 HTTP 请求调用：

完整参数说明请参考 yida-api.md 的「表单设计类 API」章节。

大模型 AI 接口

以下接口用于调用大模型 AI 文本生成能力：

主要参数：_csrf_token（CSRF 令牌）、prompt（提示词）、skill（技能类型，如 ToText）、maxTokens（最大返回 token 数）

完整参数说明和示例请参考 model-api.md。

工具类 API 速查

以下工具函数通过 this.utils.<方法名>() 调用，无需 yida 命名空间：

完整参数说明和示例请参考 yida-api.md 的「工具类 API」章节。

工具链

编译 + 发布（一键完成）

cd .claude/skills/yida-publish-page/scripts
npm install  # 首次需要安装依赖
node publish.js <appType> <formUuid> <源文件路径>

处理流程：

1. 通过 @ali/vu-babel-transform 将 JSX 转换为 ES5 + UglifyJS 压缩
2. 通过代码动态构建完整的 Schema JSON，将 source 和 compiled 填入 actions.module
3. 调用 yida-login 获取登录态（Cookie 持久化，首次需扫码登录）
4. 通过 HTTP POST 调用 saveFormSchema 接口保存 Schema

仅编译（不发布）

node .claude/skills/yida-publish-page/scripts/babel-transform/transform.js <源文件路径>

输入 JSX 源文件，输出编译压缩后的 <name>.compile.js（与源文件同目录）。