【Vercel实用Skill】json-render-react-native 技能

json-render的React Native渲染器,将JSON规范转换为原生移动UI。当使用@json-render/react-native、从JSON构建React Native UI、创建移动组件目录或在移动设备上渲染AI生成的规范时使用此技能。

技能概述

json-render-react-native 技能是一个专门用于移动应用开发的渲染器,它将JSON规范转换为React Native组件树。这个技能非常适合构建跨平台的移动应用UI,支持标准组件、数据绑定、可见性条件、操作和动态属性。通过定义JSON规范,开发者可以快速创建原生移动界面,无需编写大量的原生代码。

下载地址:https://github.com/vercel-labs/json-render

主要功能

• 原生移动UI渲染: 将JSON规范转换为React Native组件树
• 标准组件库: 提供布局、内容、输入、反馈和复合组件
• 数据绑定: 支持单向和双向数据绑定
• 可见性条件: 基于状态的条件渲染
• 动态属性表达式: 支持在运行时解析的动态属性
• 内置操作: 自动处理setState等内置操作
• 状态管理: 支持外部状态管理库集成

触发条件

在以下情况下应该调用此技能:

• 用户需要使用@json-render/react-native包
• 需要从JSON构建React Native UI
• 需要创建移动组件目录
• 需要在移动设备上渲染AI生成的规范
• 需要构建跨平台移动应用

标准组件

布局组件

• Container: 包装器,支持padding、background、border radius
• Row: 水平弹性布局,支持gap、alignment
• Column: 垂直弹性布局,支持gap、alignment
• ScrollContainer: 可滚动区域(垂直或水平)
• SafeArea: 安全区域插入,用于刘海屏/底部指示器
• Pressable: 可触摸包装器,在按下时触发操作
• Spacer: 固定或灵活的间距
• Divider: 细线分隔符

内容组件

• Heading: 标题文本(级别1-6)
• Paragraph: 正文文本
• Label: 小标签文本
• Image: 图像显示,支持多种尺寸模式
• Avatar: 圆形头像图像
• Badge: 小状态徽章
• Chip: 分类标签/芯片

输入组件

• Button: 可按下按钮,支持变体
• TextInput: 文本输入字段
• Switch: 切换开关
• Checkbox: 复选框
• Slider: 范围滑块
• SearchBar: 搜索输入

反馈组件

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

复合组件

• Card: 卡片容器,可选标题
• ListItem: 列表行,包含title、subtitle、accessory
• Modal: 底部抽屉模态框

处理过程

1. 创建目录

使用标准组件定义创建移动应用目录:

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
standardComponentDefinitions,
standardActionDefinitions,
} from "@json-render/react-native/catalog";
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: "图标显示",
},
},
actions: standardActionDefinitions,
});

2. 定义注册表

注册自定义组件实现:

import { defineRegistry, type Components } from "@json-render/react-native";

const { registry } = defineRegistry(catalog, {
components: {
Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
} as Components<typeof catalog>,
});

3. 渲染应用

使用Provider和Renderer渲染应用:

import {
Renderer,
StateProvider,
VisibilityProvider,
ActionProvider
} from "@json-render/react-native";

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

动态属性表达式

任何属性值都可以是在运行时解析的动态表达式:

• {"{ \"$state\": \"/state/key\" }"}: 从状态模型读取值(单向读取)
• {"{ \"$bindState\": \"/path\" }"}: 双向绑定,用于表单组件的自然值属性
• {"{ \"$bindItem\": \"field\" }"}: 双向绑定到重复项字段
• {"{ \"$cond\": <condition>, \"$then\": <value>, \"$else\": <value> }"}: 条件值

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

可见性条件

使用visible属性基于状态控制元素显示:

• {"{ \"$state\": \"/path\" }"}: 真值检查
• {"{ \"$state\": \"/path\", \"eq\": value }"}: 相等检查
• {"{ \"$state\": \"/path\", \"not\": true }"}: 否定检查
• [cond1, cond2]: 隐式AND

Pressable + setState模式

使用Pressable与内置setState操作创建交互式UI:

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

Provider说明

外部状态存储(受控模式)

传递StateStore到StateProvider以使用外部状态管理:

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

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

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

store.set("/count", 1); // React自动重新渲染

关键导出

使用示例

示例: 创建简单的登录表单

const loginFormSpec = {
root: "container",
elements: {
container: {
type: "Container",
props: {
padding: 20,
backgroundColor: "#f5f5f5"
},
children: ["heading", "emailInput", "passwordInput", "loginButton"]
},
heading: {
type: "Heading",
props: {
text: "登录",
level: 1
},
children: []
},
emailInput: {
type: "TextInput",
props: {
placeholder: "邮箱",
value: { "$bindState": "/form/email" },
keyboardType: "email-address",
autoCapitalize: "none"
},
children: []
},
passwordInput: {
type: "TextInput",
props: {
placeholder: "密码",
value: { "$bindState": "/form/password" },
secureTextEntry: true
},
children: []
},
loginButton: {
type: "Button",
props: {
label: "登录",
variant: "primary",
disabled: {
"$cond": {
"$or": [
{ "$state": "/form/email", "eq": "" },
{ "$state": "/form/password", "eq": "" }
]
},
"$then": true,
"$else": false
}
},
on: {
"press": { "action": "submit" }
},
children: []
}
}
};

最佳实践

1. 使用SafeArea: 在应用顶部和底部使用SafeArea组件处理刘海屏和底部指示器
2. 状态管理: 使用$bindState进行表单输入的双向绑定
3. 条件渲染: 使用visible属性控制组件的显示和隐藏
4. 性能优化: 对于长列表,考虑使用虚拟化列表组件
5. 样式一致性: 在目录中定义统一的样式主题
6. 操作处理: 使用ActionProvider集中处理用户交互