【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说明

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

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

传递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自动重新渲染

关键导出

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

使用示例

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

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: []
}
}
};