Valdi 框架入门指南:用 TypeScript 构建原生级性能的跨平台 UI
Valdi 框架入门指南:用 TypeScript 构建原生级性能的跨平台 UI
Valdi 是一个跨平台 UI 框架与视图抽象层,让你用 TypeScript 以声明式方式表达复杂视图,并通过编译与原生渲染获得接近甚至优于传统原生开发的性能与迭代速度。本指南将带你理解 Valdi 的核心概念、编译到原生渲染的完整链路、与 iOS/Android 原生代码的多种集成方式,以及它的分层架构与设计原则,读完即可上手编写第一个跨平台组件。
Valdi 是什么:构建原生、跨平台、高性能的 UI
Valdi 的核心定位是框架 + 视图抽象层:开发者用声明式语法表达复杂视图,Valdi 在"性能"与"灵活性"之间取得平衡——声明式视图会被深度优化,而事件驱动的业务逻辑则用 TypeScript 编写,兼顾表达力与执行效率。
从工程链路来看,Valdi 的实际运行方式非常直接:
- Valdi Compiler 接收 TypeScript 源码;
- 编译为
.valdimodule模块文件; - Valdi Runtime 读取这些模块文件,在 iOS、Android、macOS、Web 等平台上原生渲染。
关键事实是:Valdi 不使用任何 WebView。这一点从编译器源码中可以得到印证——在 Constants.swift 中定义了完整的受支持文件扩展名体系(.ts、.tsx、.valdimodule、.assetpackage 等),其中 .valdimodule 正是编译器产物;而在 internals-runtime.md 的 Runtime Internals 文档中明确说明,Valdi 无法直接求值原始 .js 文件,必须从编译器产出的 .valdimodule 归档中加载模块代码,这也保证了运行时链路的封闭性与可优化性。
核心价值:用 TypeScript 声明式创建视图
Valdi 采用 React 风格的 JSX/TSX 语法构建视图树,用 Flexbox 进行布局,用 TypeScript 处理事件与业务逻辑。这意味着 Web 开发者可以几乎无缝迁移到移动原生开发。
下面是官方文档给出的最简示例——一个黄底黑字的 Hello World 视图:
import { Component } from 'valdi_core/src/Component';
class HelloWorld extends Component {
onRender() {
const message = 'Hello World! 👻';
<view backgroundColor='#FFFC00' padding={30}>
<label color='black' value={message} />
</view>;
}
}
这里有几个值得注意的细节:
<view>是 Valdi 内建的原生元素(对应 AndroidViewGroup/ iOSUIView),支持布局属性(如padding)与视图属性(如backgroundColor);<label>用于展示文本,对应 AndroidTextView/ iOSUITextView,通过value传入字符串内容;- TSX 标签只在
onRender()的调用栈内生效,这是 Valdi 渲染模型的核心约束。
Component 基类位于 Component.ts,它提供了一组可覆写的生命周期方法:onCreate()(组件首次创建时调用)、onRender()(渲染时调用,用于声明视图树)、onDestroy()(组件销毁时清理资源)、onViewModelUpdate(previous?)(视图模型变化时调用),并提供了 registerDisposable、setTimeoutDisposable、animate 等工具方法,用于资源管理与动画编排。
与原生集成的两种方式
Valdi 的"跨平台"并非封闭的抽象——它提供了双向的原生集成通道,让团队可以复用已有的原生代码或把 Valdi 视图嵌入既有原生页面。
方式一:在 Valdi 中嵌入原生视图(<custom-view>)
当你已经用平台原生技术实现了一个复杂视图(例如系统级视图),想直接复用到 Valdi 布局中时,可以使用 <custom-view> 标签。官方文档示例:
import { Component } from 'valdi_core/src/Component';
class HelloWorld extends Component {
onRender() {
const myParamPassedToNativeView = 'hello';
<custom-view
iosClass="MyNativeView"
androidClass="com.snap.myfeature.MyNativeView"
paramForNativeView={myParamPassedToNativeView}
/>
}
}
<custom-view> 在 iOS 上对应 UIView、Android 上对应 View(同时支持 macOS 的 NSView 与 Web 的 DOM 元素),详见 native-customviews.md。文档中还展示了更工程化的用法:通过 ViewFactory 与 MyCustomViewAttributesBinder 把原生视图的创建逻辑和属性绑定注入到组件 Context 中,实现类型安全的参数传递。
方式二:在原生代码中嵌入 Valdi 视图
反过来,Valdi 视图也可以作为原生视图层级的一部分被宿主页面直接使用。TSX 侧通过 @Component 与 @ExportModel 注解声明导出:
import { Component } from 'valdi_core/src/Component';
/**
* @Component
* @ExportModel({
* ios: 'SCValdiHelloWorldView',
* android: 'com.snap.hello_world.HelloWorldView'
* })
*/
class HelloWorld extends Component {
...
}
iOS 侧(Objective-C):
// In iOS
#import "valdi/ios/SCValdiRuntimeManager.h"
#import <SCValdiModule/SCValdiHelloWorldView.h>
SCValdiRuntimeManager* runtimeManager = [[SCValdiRuntimeManager alloc] init];
UIView *view = [[SCValdiHelloWorldView alloc]
initWithViewModel:nil
componentContext:nil
runtime:runtimeManager.mainRuntime];
Android 侧(Kotlin):
// In Android
import com.snap.valdi.support.SupportValdiRuntimeManager
import com.valdimodule.HelloWorldView
val runtimeManager = SupportValdiRuntimeManager.createWithSupportLibs(this.applicationContext)
val view: View = HelloWorldView.create(
runtime = runtimeManager.mainRuntime
)
可以看出两端使用同一套运行时管理对象 SCValdiRuntimeManager / SupportValdiRuntimeManager 的 mainRuntime 来实例化组件视图,注解则驱动编译器生成对应平台的强类型绑定代码。更完整的 Context/注解通信机制参见 native-bindings.md 与 native-annotations.md。
借助热重载快速原型迭代
Valdi 支持全平台热重载(hot reload),包括真机设备上。修改视图代码后无需重新编译整个应用,即可看到内容实时重渲染,这对"把视图调到像素级完美"的迭代过程帮助巨大。
从编译器源码可以印证这套机制并非空谈:在 Constants.swift 中定义了完整的调试端口体系——reloaderServiceDiscovery(13253)、reloaderStandalone(13591)、reloaderOverUSB(13592)、valdiDebugger(13594)与 hermesDebugger(13595),分别服务于热重载服务发现、独立模式、USB 连接调试与 JS 引擎调试。而在运行时侧,internals-runtime.md 提到 RootComponentsManager 会注册对 TypeScript 模块的观察者,一旦模块或其依赖被替换,就解析新的构造函数并触发受影响组件层级的重渲染——这正是热重载得以生效的底层机制。
相比传统原生开发的优势
Valdi 的定位不是"又一个跨端框架",而是直接挑战传统原生 UI 开发的效率瓶颈:
- 单代码库构建跨平台 UI:一份 TypeScript 视图代码同时产出 iOS 与 Android 原生界面;
- 原生视图编写慢、手工且易错:Valdi 以声明式方式替代手写布局与视图膨胀代码;
- UI 迭代通常很慢:热重载 + 编译期优化显著缩短反馈回路;
- 原生 API 难以优化布局与视图膨胀:Valdi 在编译期优化声明式视图,把优化工作前移。
Valdi 的设计原则
Valdi 的五条设计原则定义了整个框架的取舍基线,也是评估任何新功能的准绳:
- 开发速度应显著快于传统原生代码;
- 运行性能应等于或优于传统原生代码;
- UI 永远不应崩溃——渲染层错误被隔离,不让业务代码的异常拖垮整个界面;
- iOS 与 Android 上看到的效果应一致——跨平台一致性是硬性要求;
- 应该能构建任何 UI 或动画——框架能力不以牺牲表达力为代价。
分层架构
Valdi 以职责清晰的分层架构组织,从高层业务到底层平台实现依次为:
| 层级 | 技术栈 | 职责 |
|---|---|---|
| Feature Layer | TypeScript | 特性级业务逻辑与 UI,使用高层 TypeScript API |
| Framework Layer | TypeScript/C++ | 通用渲染框架,管理组件与元素生命周期 |
| Core Layer | C++ | Valdi Runtime:集成 JavaScript 引擎、Yoga 布局引擎,处理 UI 更新 |
| Integration Layer | C++/Obj-C/Swift/Kotlin | 平台特定原生元素实现(如 <label> 在 iOS 上成为 SCValdiLabel) |
这套架构在源码与文档中都有具体落点:
- Core Layer 的运行时:以 C++ 为核心,集成 JavaScript 引擎(Android/Desktop 为 QuickJS,iOS 为 JavaScriptCore)与 Yoga 跨平台布局引擎,负责处理来自 TypeScript 框架层的更新命令,详见 internals-runtime.md;
- 跨桥数据表示:运行时用 128 位的
Valdi::Value统一表示跨桥数据(64 位数据 + 64 位类型元数据),不可变、线程安全、引用计数,并配合字符串驻留(Interned Strings) 优化内存与比较性能,这也是保证"原生级性能"的重要底牌; - 渲染协议:TypeScript
Renderer完成一次渲染后,会以RenderRequest形式向 C++ 运行时提交treeId+ 二进制命令描述符 + 非可序列化值数组,每个命令仅 4 字节头部(1 字节命令类型 + 3 字节元素 ID),把跨桥开销压到最低。
对架构感兴趣的读者,可以继续深入阅读 internals-runtime.md(运行时内部)、internals-renderer.md(diffing 算法与 slot 优化)、internals-compiler.md(编译管线与 TSX 变换)、internals-native-integration.md(视图工厂、池化与属性绑定)等系列文档。
从入门到实战:下一步
本文是 Valdi 系列指南的起点。接下来可以按此路径继续深入:
- 安装与上手:start-install.md 与 start-code-lab.md 提供环境搭建与手把手 Code Lab;
- 核心概念:阅读 core-component.md 深入了解组件生命周期,core-flexbox.md 掌握布局,core-styling.md 了解
Style<>系统; - 直接跑示例:仓库 apps/helloworld 是一个带热重载的最小完整工程,apps/navigation_example 展示导航模式,apps/valdi_gpt 演示运行时动态渲染 AI 驱动的 UI;
- 构建与发布:workflow-bazel.md 介绍 Valdi 的 Bazel 规则,command-line-references.md 是 CLI 命令速查。
掌握本文的编译链路、双向原生集成与分层架构后,你就拥有了用 Valdi 构建"一套代码、原生体验"跨平台应用所需的完整认知框架。