#指南

本接入指南主要是为有 React Native 面板开发经验，希望快速了解面板小程序对应功能的用户准备的。

在使用面板小程序开发之前，你不必完整阅读这些内容，可以在实际开发过程中按需查找。

如果你是新手，建议直接阅读 快速开始-面板小程序。

#快速入门

#一、搭建环境

区别：

• 需要额外安装 Tuya MiniApp IDE，但不再需要安装 cli 工具。

优势：

• 内置打包构建、调试及发布功能。

注意事项：

• 无。

#二、体验面板

区别：

• 无。

优势：

• 除了 脚手架 和 功能组件体验 Demo，还提供了一系列 功能模块示例项目。

注意事项：

• 无。

#三、创建产品

区别：

• 无。

优势：

• 无。

注意事项：

• 无。

#四、初始化工程

区别：

• 面板小程序需要从 Tuya MiniApp IDE 中创建工程并关联对应的产品及其面板小程序，用于后续的设备调试及发布。

优势：

• 部分工程模板提供了配套的 Codelab 教程。

注意事项：

• 面板小程序废弃了部分 RN 已过时的模板，如有需求，可通过 社区论坛 寻求帮助和支持。

#五、开发调试

区别：

• 面板小程序可直接使用智能生活 App 或 OEM App 进行调试。
• 面板小程序可通过 Tuya MiniApp IDE 在 PC 端进行开发调试。

优势：

• 内置 面板开发工具 和 AI 插件。
• 无需额外安装调试 App，使用智能生活 App 或 OEM App 即可。

注意事项：

• 最终上线务必经过 iOS 和安卓双端真机测试，PC 端因为环境限制无法保证行为 100% 一致。

#六、打包上传

区别：

• 面板小程序只需上传一个资源包。
• 面板小程序发布需涂鸦官方审核。
• 面板小程序需维护多区服务器域名、多区静态资源、云项目等信息。

优势：

• 支持多版本管理和灰度策略。
• 支持通过体验二维码，动态输入设备 ID 测试不同设备功能。
• 支持通过 Kit 能力 兼容适配不同 App 基线版本。

注意事项：

• 无。

#API

区别：

• 小程序对 API 进行了原子化拆分和拓展，因此在 API 数量上会有所增加。

优势：

• API 能力更加丰富以及灵活，能支持更多以往不支持的基础能力或业务场景，如 多设备控制、多媒体、物模型 等等。

注意事项：

• 由于 RN 的 API 数量较多，我们提供了一份 API 迁移指南 方便参照。

#脚手架

区别：

• 基于面板小程序方案及全新的面板 SDK 进行了相应的调整和设计。

优势：

• 部分工程模板提供了配套的 Codelab 教程。

注意事项：

• 面板小程序废弃了部分 RN 已过时的模板，如有需求，可通过 社区论坛 寻求帮助和支持。

#国际化多语言

区别：

• 面板小程序与 RN 的多语言 API 完全一致，仅引用包名不同，参考 多语言适配 上手使用。

优势：

• 支持面板小程序多语言的平台化管理，可以更好地应对多个产品关联在同一个面板下需要同时生效的多语言需求场景。

注意事项：

• 面板小程序的多语言逻辑与 RN 完全一致，但由于业务逻辑较复杂，建议提前阅读 多语言适配#常见问题。

#基础组件

区别：

• 提供了 基础组件 对应 RN 官方的基础组件。
• 提供了 SmartUI 组件库 对应涂鸦官方提供的组件库。

优势：

• 基于 WebView 作为渲染引擎，天然支持 CSS，在样式灵活性、社区生态及组件开发效率上更胜一筹。
• SmartUI 组件库在平台上提供了 Codesandbox 实时编辑预览的能力。

注意事项：

• RN 通过限制写法以及使用原生组件的方式，在原理上其性能是优于小程序的，为了弥补这部分差距，我们提供了如 SJS、RJS、eventChannel、原生组件、混合开发 等技术方案。

#值得注意的新特性

面板小程序相较于 RN 面板开发，有以下几个值得注意的新特性：

#面板开发工具

之前：

仅能通过开发者平台的 设备调试 功能进行调试。

现在：

1. 在开发者平台的设备调试功能之外，可在 面板工具 中直接进行设备调试。

2. 同时支持 复杂协议 功能点调试。

#智能设备模型

之前：

面板 SDK 仅提供了基础的设备 API 包装，通常需要通过 redux 等状态管理库来管理设备状态。

import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { useDispatch } from 'react-redux';
import { useSelector } from '@models';

export default function Home() {
  const dispatch = useDispatch();
  const power = useSelector(state => state.dpState.power);

  const handleTogglePower = () => {
    dispatch(actions.common.updateDp({ power: !power }));
  };

  return (
    <View style={{ flex: 1 }}>
      <Text>power: {power}</Text>
      <TouchableOpacity onPress={handleTogglePower}>
        <Text>toggle power</Text>
      </TouchableOpacity>
    </View>
  );
}

现在：

1. 面板 SDK 提供了 useProps 和 useActions 两个 hooks，可直接用于获取设备状态和对设备进行控制。

import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions } from '@ray-js/panel-sdk';

export default function Home() {
  const power = useProps((props) => props.power);
  const actions = useActions();
  return (
    <View style={{ flex: 1 }}>
      <View>power: {power}</View>
      <View onClick={actions.power.toggle}>toggle power</View>
    </View>
  );
}

2. 通过 智能设备的描述文件（即原 RN SDK 中 TYSdk.devInfo.schema）配合 TS 类型推导，可获得更优雅的设备开发体验。

3. 面板 SDK 中内置了功能点处理拦截器（即 dp-kit），内置支持解析 & 反解析复杂类型 DP 功能点，下发节流、防抖、过滤等功能。

#支持多设备及更丰富的能力

之前：

1. 仅支持单设备控制：

TYSdk.device.putDeviceData({ switch_1: true });

2. 仅支持以下有限的能力：

• 原生方法
• 移动方法
• 设备方法
• ...

现在：

1. 所有 API 及事件均支持指定设备的控制或响应：

// 设备控制
publishDps({
  // 可以通过指定 deviceId 控制家庭下的指定设备
  deviceId: 'vdevoxxxxx',
  dps: { switch_1: true },
  success: res => {
    console.log(res);
  },
  fail: error => {
    console.log(error);
  },
});

// 设备监听
onDpDataChange((res)=>{
  console.log(res);
  // 可以通过判断指定的 deviceId 监听家庭下的指定设备
  // {
  //   deviceId: "vdevo169477319679442",
  //   dps: {
  //     1: true
  //   },
  //   gwId: ''
  // }
})

2. 支持更丰富的基础或设备能力，详见 API

#平台拓展能力（体验二维码、数据统计、性能质量）

之前：

1. 产品 A 当前关联了面板 A，想要切换到新开发的面板 B 上，只能将产品 A 直接切换到面板 B 上，存在一定的风险。

现在：

1. 产品 A 当前关联了面板 A，想要切换到新开发的面板 B 上，只需在生成指定设备 id 的体验二维码即可，无需关联产品 A，可在测试完毕后再关联产品 A。

2. 小程序平台内置提供了数据统计、性能质量等能力，可在开发者平台中查看分析。

#值得关注的进阶技术点

面板小程序相较于 RN 面板开发，有以下几个值得关注的进阶技术点：

#SJS

• 应用场景：用于应对频繁用户交互的场景，类似 RN 中的 setNativeProps。
• 参考文档：SJS 响应事件、SJS 语法参考
• 参考示例：tuya-miniapp-demo/sjs

#RJS

• 应用场景：用来处理高频的绘图需求，提高视图的动画渲染性能，如 Canvas 图表渲染，WebGL 图形渲染等。
• 参考文档：Render Script
• 参考示例：tuya-miniapp-demo/rayRjsPlugin

#混合开发

• 应用场景：在 Ray 框架中直接引用原生小程序语法开发的组件或者微信小程序生态的三方组件，用于提升性能或开发效率。
• 参考文档：混合开发
• 参考示例：tuya-miniapp-demo/rayUseAx