json-render-react-native

@json-render/react-native

React Native 渲染器，可将 JSON 规范转换为原生移动端组件树，支持标准组件、数据绑定、可见性、操作和动态属性。

快速开始

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/react-native";
import { z } from "zod";

// Create catalog with standard + custom components
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Icon: {
      props: z.object({ name: z.string(), size: z.number().nullable(), color: z.string().nullable() }),
      slots: [],
      description: "Icon display",
    },
  },
  actions: standardActionDefinitions,
});

// Register only custom components (standard ones are built-in)
const { registry } = defineRegistry(catalog, {
  components: {
    Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
  } as Components<typeof catalog>,
});

// Render
function App({ spec }) {
  return (
    <StateProvider initialState={{}}>
      <VisibilityProvider>
        <ActionProvider handlers={{}}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}

标准组件

布局

• Container - 带内边距、背景和圆角的包装容器
• Row - 带间距和对齐方式的水平弹性布局
• Column - 带间距和对齐方式的垂直弹性布局
• ScrollContainer - 可滚动区域（垂直或水平）
• SafeArea - 适配刘海屏／主屏幕指示条的安全区域内边距
• Pressable - 可触摸的包装容器，按下时触发操作
• Spacer - 固定或可伸缩的间距
• Divider - 细线分隔符

内容

• Heading - 标题文本（级别 1–6）
• Paragraph - 正文
• Label - 小号标签文本
• Image - 支持多种尺寸模式的图片
• Avatar - 圆形头像图片
• Badge - 小型状态徽标
• Chip - 分类标签

输入

• Button - 支持多种样式的可按下按钮
• TextInput - 文本输入框
• Switch - 切换开关
• Checkbox - 带标签的复选框
• Slider - 范围滑块
• SearchBar - 搜索输入框

反馈

• Spinner - 加载指示器
• ProgressBar - 进度指示器

复合组件

• Card - 可带可选标题的卡片容器
• ListItem - 带标题、副标题和附属元素的列表行
• Modal - 底部弹出式模态框

可见性条件

在元素上使用 visible。语法：{ "$state": "/path" }、{ "$state": "/path", "eq": value }、{ "$state": "/path", "not": true }，使用 [ cond1, cond2 ] 表示 AND。

Pressable + setState 模式

对于标签栏等交互式 UI，可将 Pressable 与内置的 setState 操作搭配使用：

{
  "type": "Pressable",
  "props": {
    "action": "setState",
    "actionParams": { "statePath": "/activeTab", "value": "home" }
  },
  "children": ["home-icon", "home-label"]
}

动态属性表达式

任何属性值都可以是数据驱动的表达式，并在渲染时解析：

• { "$state": "/state/key" } - 从状态模型读取（单向读取）
• { "$bindState": "/path" } - 双向绑定：用于表单组件的自然值属性（value、checked、pressed 等）。
• { "$bindItem": "field" } - 双向绑定到重复项字段。在 repeat 作用域内使用。
• { "$cond": <condition>, "$then": <value>, "$else": <value> } - 条件值

{
  "type": "TextInput",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

组件不使用 statePath 属性进行双向绑定。请在自然值属性上使用 { "$bindState": "/path" }。

内置操作

setState 操作由 ActionProvider 自动处理，并直接更新状态模型，从而重新计算可见性条件和动态属性表达式：

{ "action": "setState", "actionParams": { "statePath": "/activeTab", "value": "home" } }

Providers

Provider	用途
StateProvider	在组件间共享状态（JSON Pointer 路径）。接受可选的 store 属性以使用受控模式。
ActionProvider	处理从组件分发的操作
VisibilityProvider	根据状态启用条件渲染
ValidationProvider	表单字段验证

外部 Store（受控模式）

将 StateStore 传递给 StateProvider（或 JSONUIProvider / createRenderer），以使用外部状态管理：

import { createStateStore, type StateStore } from "@json-render/react-native";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React re-renders automatically

提供 store 时，将忽略 initialState 和 onStateChange。

主要导出

导出	用途
defineRegistry	根据目录创建类型安全的组件注册表
Renderer	使用注册表渲染规范
schema	React Native 元素树架构
standardComponentDefinitions	所有标准组件的目录定义
standardActionDefinitions	标准操作的目录定义
standardComponents	预构建的组件实现
createStandardActionHandlers	为标准操作创建处理程序
useStateStore	访问状态上下文
useStateValue	从状态中获取单个值
useBoundProp	通过 $bindState/$bindItem 进行双向状态绑定
useStateBinding	(已弃用) 按路径进行旧式双向绑定
useActions	访问操作上下文
useAction	获取单个操作分发函数
useUIStream	从 API 端点流式传输规范
createStateStore	创建与框架无关的内存中 StateStore
StateStore	用于接入外部状态管理的接口