json-render-react-native

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@json-render/react-native

React Native renderer that converts JSON specs into native mobile component trees with standard components, data binding, visibility, actions, and dynamic props.

这是一款React Native渲染器，可将JSON规范转换为包含标准组件、数据绑定、可见性控制、操作处理和动态属性的原生移动组件树。

Quick Start

快速开始

typescript

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>
  );
}

typescript

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";

// 创建包含标准组件和自定义组件的目录
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,
});

// 仅注册自定义组件（标准组件已内置）
const { registry } = defineRegistry(catalog, {
  components: {
    Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
  } as Components<typeof catalog>,
});

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

Standard Components

标准组件

Layout

布局类

```
Container
```
- wrapper with padding, background, border radius
```
Row
```
- horizontal flex layout with gap, alignment
```
Column
```
- vertical flex layout with gap, alignment
```
ScrollContainer
```
- scrollable area (vertical or horizontal)
```
SafeArea
```
- safe area insets for notch/home indicator
```
Pressable
```
- touchable wrapper that triggers actions on press
```
Spacer
```
- fixed or flexible spacing
```
Divider
```
- thin line separator

```
Container
```
- 带内边距、背景和圆角的容器
```
Row
```
- 带间距和对齐设置的水平弹性布局
```
Column
```
- 带间距和对齐设置的垂直弹性布局
```
ScrollContainer
```
- 可滚动区域（垂直或水平）
```
SafeArea
```
- 适配刘海屏/底部指示条的安全区域
```
Pressable
```
- 可触摸容器，点击时触发操作
```
Spacer
```
- 固定或自适应间距组件
```
Divider
```
- 细线条分隔符

Content

内容类

```
Heading
```
- heading text (levels 1-6)
```
Paragraph
```
- body text
```
Label
```
- small label text
```
Image
```
- image display with sizing modes
```
Avatar
```
- circular avatar image
```
Badge
```
- small status badge
```
Chip
```
- tag/chip for categories

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

Input

输入类

```
Button
```
- pressable button with variants
```
TextInput
```
- text input field
```
Switch
```
- toggle switch
```
Checkbox
```
- checkbox with label
```
Slider
```
- range slider
```
SearchBar
```
- search input

```
Button
```
- 带多种样式的可点击按钮
```
TextInput
```
- 文本输入框
```
Switch
```
- 开关切换组件
```
Checkbox
```
- 带标签的复选框
```
Slider
```
- 范围滑块
```
SearchBar
```
- 搜索输入框

Feedback

反馈类

```
Spinner
```
- loading indicator
```
ProgressBar
```
- progress indicator

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

Composite

复合类

```
Card
```
- card container with optional header
```
ListItem
```
- list row with title, subtitle, accessory
```
Modal
```
- bottom sheet modal

```
Card
```
- 可选头部的卡片容器
```
ListItem
```
- 包含标题、副标题和附属元素的列表行
```
Modal
```
- 底部弹窗组件

Pressable + setState Pattern

Pressable + setState 模式

Use

Pressable

with the built-in

setState

action for interactive UIs like tab bars:

json

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

结合

Pressable

和内置的

setState

操作，可实现标签栏等交互式UI：

json

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

Dynamic Prop Expressions

动态属性表达式

Any prop value can be a data-driven expression resolved at render time:

{ "$path": "/state/key" }
- reads from data model

{ "$cond": <condition>, "$then": <value>, "$else": <value> }
- conditional value

json

{
  "color": {
    "$cond": { "eq": [{ "path": "/activeTab" }, "home"] },
    "$then": "#007AFF",
    "$else": "#8E8E93"
  }
}

Components receive already-resolved props. No changes needed to component implementations.

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

{ "$path": "/state/key" }
- 从数据模型中读取值

{ "$cond": <condition>, "$then": <value>, "$else": <value> }
- 条件判断值

json

{
  "color": {
    "$cond": { "eq": [{ "path": "/activeTab" }, "home"] },
    "$then": "#007AFF",
    "$else": "#8E8E93"
  }
}

组件会接收已解析完成的属性，无需修改组件实现代码。

Built-in Actions

内置操作

The

setState

action is handled automatically by

ActionProvider

and updates the state model directly, which re-evaluates visibility conditions and dynamic prop expressions:

json

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

setState

操作由

ActionProvider

自动处理，直接更新状态模型，进而重新评估可见性条件和动态属性表达式：

json

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

Providers

提供者组件

Provider	Purpose
`StateProvider`	Share state across components (JSON Pointer paths)
`ActionProvider`	Handle actions dispatched from components
`VisibilityProvider`	Enable conditional rendering based on state
`ValidationProvider`	Form field validation

提供者组件	用途
`StateProvider`	在组件间共享状态（使用JSON Pointer路径）
`ActionProvider`	处理组件触发的操作
`VisibilityProvider`	支持基于状态的条件渲染
`ValidationProvider`	表单字段验证

Key Exports

核心导出项

Export	Purpose
`defineRegistry`	Create a type-safe component registry from a catalog
`Renderer`	Render a spec using a registry
`schema`	React Native element tree schema
`standardComponentDefinitions`	Catalog definitions for all standard components
`standardActionDefinitions`	Catalog definitions for standard actions
`standardComponents`	Pre-built component implementations
`createStandardActionHandlers`	Create handlers for standard actions
`useStateStore`	Access data context
`useStateValue`	Get single value from data
`useStateBinding`	Two-way data binding
`useActions`	Access actions context
`useAction`	Get a single action dispatch function
`useUIStream`	Stream specs from an API endpoint

导出项	用途
`defineRegistry`	从组件目录创建类型安全的组件注册表
`Renderer`	使用注册表渲染规范内容
`schema`	React Native元素树的规范 schema
`standardComponentDefinitions`	所有标准组件的目录定义
`standardActionDefinitions`	标准操作的目录定义
`standardComponents`	预构建的组件实现
`createStandardActionHandlers`	创建标准操作的处理函数
`useStateStore`	访问数据上下文
`useStateValue`	从数据中获取单个值
`useStateBinding`	双向数据绑定
`useActions`	访问操作上下文
`useAction`	获取单个操作的触发函数
`useUIStream`	从API端点流式获取规范内容