React 占位组件（`ReactPlaceholder`）

React 占位组件（React 占位符 / 代码占位符，widgetType: ReactPlaceholder）是视图移动端渲染模板中由用户自定义 React 代码驱动的占位元素，通过数据字典按占位序号取用绑定的字段值与行按钮，在一个组件内自由渲染一个或多个占位内容。

概述

React 占位组件与占位组件（字段占位符 / 按钮占位符）解决同一类问题——自定义移动端卡片的渲染内容，但工作方式不同：

对比项	字段/按钮占位符	React 占位组件
内容来源	平台按占位序号自动渲染字段值/按钮	用户编写的 React 组件代码
单个组件渲染数量	一个序号对应一个内容	可同时取用多个序号，一次渲染多个内容
同一布局可用数量	每个序号单例（仅一次）	可重复拖拽多个
样式控制	容器样式 + 元素样式配置项	全部在 React 代码内自行控制

组件代码在浏览器中编译执行，必须默认导出一个 React 组件，支持 JSX/TSX 与 ESM import（自动 JSX runtime，无需 import React）。
运行时组件收到 props.data 数据字典与 props.sdk 平台能力，详见下方 data 数据约定。
React 占位组件提供于平台页面模板（MetaPageTemplateCategory.MetaPage）与视图移动端渲染（MetaPageTemplateCategory.MetaView）两类模板的组件面板中；当前数据字典仅在视图移动端卡片渲染时注入。

配置项

配置项	说明
自定义代码	打开代码编辑器弹窗编写 React 组件代码，支持实时预览；未配置时组件在模板编辑器中显示占位提示框

data 数据约定

编译后的组件通过 props.data 取用数据：

键	类型	含义
`data.placeholders['field-placeholder-{n}']`	`ReactPlaceholderFieldData`：`{ meta: { name, code }, data: { text, value } }`	绑定到字段占位符 `{n}`（1–30）的字段数据中转模型，`meta.name` 为字段显示名、`meta.code` 为字段编码，`data.text` 为展示值、`data.value` 为实际值
`data.placeholders['button-placeholder-{n}']`	React 节点	绑定到按钮占位符 `{n}`（31–40）的行按钮组件，可直接放入 JSX 渲染
`data.objectData`	`ObjectData`	当前卡片对应的整条对象数据，可自行取任意字段

取值规则

字段只有在展示值与实际值不同时为空时才会写入字典，与字段占位符的渲染规则一致。
行按钮只有在未隐藏且满足显示条件时才会写入字典。
data.placeholders 与 data.objectData 之外的场景（如平台页面模板中直接使用该组件）字典为空对象、objectData 为 undefined，代码需做空值防护。

默认代码模板

/**
 * React placeholder widget entry component.
 * props.data.placeholders is keyed by the placeholder binding of the view:
 * - 'field-placeholder-1': the FieldData of the field bound to placeholder 1
 * - 'button-placeholder-31': the button React node bound to placeholder 31
 * props.data.objectData holds the whole current object data
 * JSX uses the automatic runtime, importing React is not required
 */
function Widget(props) {
  const { sdk, data } = props;
  const field = data?.placeholders?.['field-placeholder-1'];
  return (
    <div>Field 1: {field?.data?.text}</div>
  );
}

export default Widget;

使用场景

组合渲染：一个组件内同时取用多个字段/按钮，实现默认占位符无法完成的复杂排版。
按值自定义渲染：根据 data.objectData 中任意字段的取值，自行决定渲染什么内容与样式。
减少占位符数量：字段较多时不必拖入大量字段占位符，用一个 React 占位组件统一渲染。

下一步

占位组件 - 平台自动渲染的字段/按钮占位符，与 React 占位组件互补
平台页面模板 - 占位组件所属的模板分类与组件清单
列表数据列 - 字段的移动端占位符绑定（决定字典中的 field-placeholder-{n}）
行按钮 - 行按钮的移动端占位符绑定（决定字典中的 button-placeholder-{n}）

属性明细

以下内容面向技术实现与 AI 检索。

React 占位组件属性表

属性名	类型	含义	取值/存储值
`widgetType`	string	组件类型标识	`ReactPlaceholder`
`uid`	string	固定唯一标识	`c2d7a1f4-6b3e-4c8a-9d5e-1f0a8b2c4d7e`
`dragType` / `originalType`	string	拖拽分类	`Widget`
`meta.Script`	string	用户编写的 React 组件代码	必须默认导出一个 React 组件，可空（为空时用户态不渲染内容）

React 占位组件不在 SingleUseWidgetTypes 单例集合中，可重复拖拽、可复制；meta 中的代码字符串原样保存。

渲染与数据注入逻辑

编辑态：显示虚线占位框及组件名称；未配置代码时额外提示前往属性面板编辑，不执行用户代码。
设置面板：通过弹窗中的 ReactEditor 编辑代码并实时预览，确认后写入 meta.Script。
用户态：ReactRenderer 在浏览器中用 Babel 编译代码（结果按源码缓存），渲染于错误边界内；data 由 cmpParams.placeHolderData 提供。
数据构建：MetaViewMobileItem.buildPlaceHolders() 构建占位内容映射时同步构建数据字典 placeHolderData = { placeholders, objectData }，随 cmpParams 传入组件树。
data.placeholders 的值与占位序号绑定对应：字段键为 field-placeholder-{n}、按钮键为 button-placeholder-{n}，{n} 即字段/行按钮设置中「移动端占位符绑定」选择的序号。

异常与校验

场景	行为
未配置代码（`meta.Script` 为空）	编辑态显示占位提示框；用户态渲染为空
代码编译失败	`ReactRenderer` 渲染错误 Alert，显示错误信息，不影响页面其他部分
代码运行时抛错	错误边界捕获并渲染错误提示
字典中取不存在的键	`data.placeholders[key]` 为 `undefined`，代码需自行兜底

存储示例

React 占位组件作为节点保存在模板的 Layout 组件树中（数据表 system_metapagetemplate），以下示例为一个字段占位符与 React 占位组件并存的嵌套结构：

[
  {
    "id": "5e7f...",
    "uid": "c2d7a1f4-6b3e-4c8a-9d5e-1f0a8b2c4d7e",
    "dragType": "Widget",
    "originalType": "Widget",
    "widgetType": "ReactPlaceholder",
    "widgetTypeName": "React 占位符",
    "children": [],
    "meta": {
      "Script": "function Widget(props) {\n  const { data } = props;\n  const field = data?.placeholders?.['field-placeholder-1'];\n  return <div>{field?.Text}</div>;\n}\n\nexport default Widget;"
    }
  }
]

内容	位置
React 占位组件定义（编辑器 / 查看器 / 设置面板 / 默认代码模板）	`web/src/components/Widgets/PlaceholderWidgets/ReactPlaceholderWidget.tsx`
组件类型枚举与占位序号工具函数	`web/src/components/Widgets/WidgetType.tsx`
Widget 类型到实例的映射	`web/src/components/Widgets/WidgetSelector.tsx`
组件面板分组	`web/src/components/Widgets/WidgetSidebarItemConfig.tsx`
数据字典构建与注入	`web/src/components/PageCmps/MetaView/MetaViewMobileItem.tsx`
代码编译渲染器 / 编辑器	`web/src/components/CommonCmps/ReactRender/`（`ReactRenderer.tsx` / `reactCompiler.ts` / `ReactEditor.tsx`）

概述​

配置项​

data 数据约定​

默认代码模板​

使用场景​

下一步​

属性明细​

React 占位组件属性表​

渲染与数据注入逻辑​

异常与校验​

存储示例​

相关实现​

概述

配置项