Valdi Codelab 从零入门:用 TypeScript 构建跨平台声明式 UI 的完整实践指南
Valdi Codelab 从零入门:用 TypeScript 构建跨平台声明式 UI 的完整实践指南
本指南基于 Valdi 官方 Codelab 学习路径(docs/docs/start-code-lab.md 及其链接的完整 getting_started 系列),面向从未接触过 Valdi 的开发者,带你从搭建环境、跑通 Hello World、体验热重载,一路深入到声明式渲染、控制流、组件状态、生命周期、触摸事件与单元测试。读完本文,你将掌握用 TypeScript 编写一次、在多平台原生渲染的 Valdi 组件,并具备独立构建与测试一个 Valdi 模块的完整实战能力。
Valdi 是什么,为什么要通过 Codelab 入门
Valdi 是一个允许你用 TypeScript 构建高性能、跨平台、声明式 UI 的框架。它的核心设计理念可以概括为三点(见 docs/codelabs/getting_started/1-introduction.md):
- 声明式而非命令式:你声明 UI 在某种状态下的样子,框架负责把界面从上一个布局更新到新布局;
- 热重载驱动迭代:Valdi 的热重载器(hotreloader)在你开发时实时更新已连接设备或模拟器上的 UI,显著加速开发循环;
- 轻松接入原生代码:你可以方便地 hook 进原生层,进行深度定制。
需要特别澄清一个常见误解:Valdi 不是渲染在 WebView 里的 TypeScript。Valdi 编译器会把 TypeScript 源码编译成 valdimodule 文件,由 Valdi 运行时在 Android、iOS、macOS、Linux 等平台上以原生方式渲染。也就是说,你写的是 TypeScript,跑起来的是原生控件。
原仓库中真实存在的 codelab 组件 apps/helloworld/src/valdi/hello_world/src/GettingStartedCodelab.tsx 就是本文所有练习的起点,它展示了最基础的 Component + onRender 形态:
import { Component } from 'valdi_core/src/Component';
import { systemBoldFont, systemFont } from 'valdi_core/src/SystemFont';
export class GettingStartedCodelab extends Component {
onRender() {
<layout padding={24} paddingTop={80}>
<label value="Getting started codelab!" font={systemBoldFont(16)} />
<label value="gitub.com/Snapchat/Valdi" font={systemFont(12)} />
</layout>;
}
}
官方推荐的学习路径
docs/docs/start-code-lab.md 把 Codelab 按推荐顺序组织,适合自学、循序渐进:
- TypeScript 语言入门(外部资源,可在 typescriptlang.org 官方文档的 Get Started 部分学习);
- 从零开始上手 Valdi(本文核心展开内容);
- Valdi 与原生代码的集成;
- 高级 UI。
前置条件
开始之前,你应该已经熟悉自己选择的目标平台(Android 或 iOS),也就是说你能独立构建并安装一个 Android 或 iOS 应用,并对其开发环境有基本理解。接下来请严格按照 INSTALL.md 的指引,把机器配置成可构建 Valdi 应用的状态——这会安装 Valdi CLI、Bazel 等构建依赖,是后续所有命令能跑通的前提。
第一个 Valdi 应用:Hello World
安装好工具链之后,最快的上手方式是通过仓库中的 helloworld 应用。它的源码位于仓库的 apps/helloworld 目录(入口文件是 apps/helloworld/src/valdi/hello_world/src/HelloWorldApp.tsx)。
启动一个你熟悉的模拟器或真机设备,然后用 valdi install 命令构建并安装。Android 的命令是:
valdi install android
然后选择 //apps/helloworld:hello_world_android 目标。
iOS 的命令是:
valdi install ios
然后选择 //apps/helloworld:hello_world_ios 目标。
构建完成后,helloworld 应用会自动在你的开发设备/模拟器上启动。至此你已经在真实设备上跑起了第一个 Valdi 应用。
热重载:迭代开发的加速器
接下来启动热重载器。它会监听 Valdi 源码的变化,重新编译并把变更后的 valdimodule 推送给已连接客户端,实时重渲染应用 UI:
valdi hotreload --module hello_world
CLI 参考:Valdi CLI 的完整命令说明见 Command Line References。
热重载进程在准备好接收变更时,会在控制台打印类似下面的日志:
[3.203] [INFO] Recompilation pass finished, waiting for file changes...
[3.203] [INFO] --------------------------------------------------------
第一次热重载体验:改背景色
在 VS Code 中打开 HelloWorldApp 的入口文件:
code apps/helloworld/src/valdi/hello_world/src/HelloWorldApp.tsx
找到描述背景的那个 <view>(对应源码中 onRender 方法里的 <view backgroundColor="white">,即 HelloWorldApp.tsx):
<view backgroundColor='white'>
把 backgroundColor 改成 blue(或其他任意受支持的 CSS 颜色值):
<view backgroundColor='blue'>
保存后,热重载进程会立刻开始重建变更的模块,并更新运行中的应用。你会看到类似下面的日志:
[387.506] [INFO] --- Files changed - starting recompilation pass
# ... additional logs
[387.823] [INFO] [Hot reloader] sending 2 updated resources to 1 connected client(s)...
[387.823] [INFO] Saving files
[387.823] [INFO] Compilation took 316ms
设备上运行的 helloworld 应用会即时反映你对 <view> 的修改——这就是热重载的典型工作流。值得一提的是,真实仓库的 HelloWorldApp.tsx 比 codelab 演示的版本更丰富:它引入了 Style<ScrollView>、accessibilityId(用于 instrumented 测试定位元素,见 apps/helloworld/androidTest)、tint 图片着色、ByteExactImageExample 子组件以及 onRootComponentCreated 原生回调,可作为你后续阅读参考的完整范例。
认识 Codelab 组件与声明式渲染
热重载跑通后,正式进入 codelab 主体。仓库在 helloworld 应用里预留了一个专门供你练习的组件 GettingStartedCodelab.tsx,把它在你的编辑器中打开:
import { Component } from "valdi_core/src/Component";
import { systemBoldFont, systemFont } from "valdi_core/src/SystemFont";
export class GettingStartedCodelab extends Component {
onRender(){
<layout padding={24} paddingTop={128}>
<label value='Getting started codelab!' font={systemBoldFont(16)} />
<label value='github.com/Snapchat/Valdi' font={systemFont(12)} />
</layout>
}
}
然后在 HelloWorldApp.tsx 中导入它,并在 onRender 里渲染:
import { GettingStartedCodelab } from './GettingStartedCodelab';
onRender(): void {
console.log('Hello World onRender!!!');
<view backgroundColor='white'>
<GettingStartedCodelab />
</view>
}
保存后热重载会自动重建应用,GettingStartedCodelab 组件就会出现在屏幕上。看到自己的修改生效,就说明开发闭环已完全打通。
声明式渲染的本质
传统命令式 UI(Android/iOS 的常规做法)是"创建一次、之后手动修改已存在的视图";而 Valdi 是声明式 UI:你不直接管理 UI,而是基于当前状态声明 UI 应该长什么样,框架负责把界面从上一个布局变更到目标布局。
Valdi 组件通过重写 onRender 函数来完成声明,该函数在 UI 每次需要更新时都会执行。把第一个 <label> 的 value 改成 'Declarative codelab':
onRender() {
<layout padding={24} paddingTop={80}>
<label value='DeclarativeCodelab!' font={systemBoldFont(16)} />
<label value='github.com/Snapchat/Valdi' font={systemFont(12)} />
</layout>;
}
保存后热重载会编译 TypeScript 并重建页面。需要强调:Valdi 在底层为 UI 优化做了大量工作,但你应该避免在 onRender 函数里做任何重量级计算——它可能被频繁调用。
TSX 与 JSX
<layout>、<label> 这些标签看起来像 HTML,但它们其实是 TSX——一种可嵌入的、XML 形态的语法,由 Valdi 工具链转换为合法的 TypeScript。在 Valdi 中,TSX 只能在 onRender 的调用栈内使用,即 onRender 内部或由 onRender 调用的函数内部。
Valdi 原生元素
Valdi 提供了一组映射到原生实现的元素,它们是 UI 的原子构件:
<layout>:自身不渲染任何东西,用于对子元素分组并指定布局方式;<label>:显示文本的文字标签;<view>:简单的矩形容器,可设置背景色、边框、响应手势事件,通常不单独使用;<image>、<spinner>、<scroll>:从命名即可理解其用途。
你也可以定义自己的原生视图,但这属于另一门 codelab 的课题。完整元素列表与属性见 API Reference。
自定义属性
渲染并不局限于字符串和常量,你可以为组件定义属性。在组件内新增一个 msg 属性:
export class GettingStartedCodelab extends Component {
private msg?: string;
这是 TypeScript 的私有属性声明,? 表示可选属性,其值可能为 undefined。随后实现 onCreate 并给 msg 赋值:
onCreate() {
this.msg = 'Hello Valdi on ' + new Date().toLocaleString();
}
onCreate 是 Component 生命周期的一部分,组件创建时只调用一次。然后在 onRender 中消费这个变量:
onRender() {
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
<label value={this.msg} font={systemFont(12)} />
</layout>;
}
在 TSX 中访问变量必须使用花括号 {}。
局部变量
你也可以在 onRender 里定义局部变量。先把 onCreate 中的 msg 缩短:
onCreate() {
this.msg = 'Hello Valdi on ';
}
再在 onRender 里拼接完整消息:
onRender() {
const fullMsg = this.msg + new Date().toLocaleString();
// ...
并把 label 的值换成新变量(toLocaleTimeString 会让时间每次刷新都变化,便于直观感受重渲染):
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
<label value={fullMsg} font={systemFont(12)} />
</layout>;
}
fullMsg 每次 onRender 运行时都会重新创建,因此时间戳会随之更新。
控制流与循环
动手前,你的组件应该接近下面这样:
import { Component } from "valdi_core/src/Component";
import { systemBoldFont, systemFont } from "valdi_core/src/SystemFont";
export class GettingStartedCodelab extends Component {
private msg?: string;
onCreate() {
this.msg = 'Hello valdi on ';
}
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout padding={24} paddingTop={80}>
<label value='Declarative codelab' font={systemBoldFont(16)} />
<label value={fullMsg} font={systemFont(12)} />
</layout>;
}
}
if 语句:条件渲染
新增一个 boolean 类型成员变量:
export class GettingStartedCodelab extends Component {
private msg?: string;
private kitten?: boolean;
...
然后在 onRender 中加一个 if:
onRender() {
if (this.kitten) {
<image height={50} width={50} src='https://placecats.com/300/300' />
} else {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
<label value={fullMsg} font={systemFont(12)} />
</layout>;
}
}
此时界面不会有变化——kitten 是可选变量且仍为 undefined,求值结果为 false。在 onCreate 中把它设为 true:
onCreate() {
this.msg = 'Hello valdi on ';
this.kitten = true;
}
现在你应该能看到一只小猫图片了。
内联循环:forEach
列表迭代可以直接写在 TSX 中间。先删掉 kitten 变量,改成一个猫咪 URL 数组:
export class GettingStartedCodelab extends Component {
private msg?: string;
private kittens = [
'https://placecats.com/300/300',
'https://placecats.com/300/301',
'https://placecats.com/300/302',
];
...
略微不同的尺寸会给你不同的小猫。然后用 forEach 迭代渲染:
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
<label value={fullMsg} font={systemFont(12)} />
{this.kittens.forEach(kitten => {
<image height={50} width={50} src={kitten} />;
})}
</layout>;
}
内联 if / for 的限制
你可能想当然地认为可以照葫芦画瓢,在 TSX 的花括号里写内联的 if 和 for——不可以。花括号块的内容必须是一个表达式,而目前 TypeScript 标准中 if 和 for 都不是表达式。想要实现类似效果,可以用下面几种方案。
when 表达式
回到 if 的示例。如果你想保留 "Declarative codelab" 标题、只替换第二行的内容,可以用 when 表达式。先导入工具:
import { when } from 'valdi_core/src/utils/When';
然后用它条件渲染:
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
{when(this.kitten, () => {
<image height={50} width={50} src='https://placecats.com/300/300' />;
})}
<label value={fullMsg} font={systemFont(12)} />
</layout>;
}
when 的第一个参数是条件,可以是求值为 boolean 的表达式或变量;第二个参数是条件为 true 时执行的 lambda。when 没有 else 子句,需要 else 语义时用 when(!conditional) 实现:
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemBoldFont(16)} />
{when(this.kitten, () => {
<image height={50} width={50} src='https://placecats.com/300/300' />;
})}
{when(!this.kitten, () => {
<label value={fullMsg} font={systemFont(12)} />;
})}
</layout>;
}
试着改变 this.kitten 的值,观察 UI 切换。
嵌套渲染函数
你还可以从 onRender 调用另一个函数。新建 onRenderMessage 并在 onRender 中调用:
onRenderMessage(message: string) {
// Render message
}
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value='Declarative codelab' font={systemFont(12)} />
{this.onRenderMessage(fullMsg)}
</layout>;
}
然后在 onRenderMessage 里用 if 在猫咪和文字之间切换:
onRenderMessage(message: string) {
if (this.kitten) {
<image height={50} width={50} src='https://placecats.com/300/300' />;
} else {
<label value={message} font={systemFont(12)} />;
}
}
这不仅解决了"条件不是表达式"的问题,还能让代码更可读、更可复用。
组件状态:ViewModel 与 State
到目前为止,我们一直在用局部变量并依赖热重载来重渲染。但生产环境下的组件是如何响应数据变化而更新视图的?答案是:当特定种类的状态发生变化时,Valdi 会自动重渲染组件。组件有两种主要状态:ViewModel 和 State。
ViewModel 与单向数据流
在 Valdi 中,数据沿组件树向下传播(父 → 子),父组件向子组件传数据的通道就是 ViewModel。对子组件而言,ViewModel 是不可变的——只能读取变量,不能修改。当父组件更新子组件的 ViewModel 后,子组件可以在下一次 onRender 或生命周期回调 onViewModelUpdate 中拿到新值。
ViewModel 定义为接口,并在 Component 上指定泛型。把接口定义在 import 语句下方、组件类之外:
export interface GettingStartedCodeLabViewModel {
header: string;
}
推荐命名约定为 NameOfComponentViewModel。然后在组件上指定泛型:
export class GettingStartedCodelab extends Component<GettingStartedCodeLabViewModel> {
在 onRender 中消费 ViewModel:
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value={this.viewModel.header} font={systemBoldFont(16)} />
{this.onRenderMessage(fullMsg)}
</layout>;
}
热重载刷新后,你可能会看到报错或缺失的标题——因为父组件在引用 <GettingStartedCodelab> 时没有提供 header。打开 HelloWorldApp.tsx,找到 onRender 中引入该组件的位置。VSCode 会给出类型错误提示:"Property 'header' is missing in type '{}' but required in type 'Readonly<GettingStartedCodeLabViewModel>'"。修复方式是在标签上传入属性:
<GettingStartedCodelab header='State codelab'></GettingStartedCodelab>
如果某些 ViewModel 变量不总是必需,可以在接口中把它们声明为可选:
export interface GettingStartedCodeLabViewModel {
header: string;
numKittens?: number;
}
State 与 StatefulComponent
State 对象用于跟踪组件的内部状态。和 ViewModel 一样,State 也是不可变的;但区别在于,State 可以通过组件的 setState() 函数修改,而调用 setState 会触发组件重渲染。
在 ViewModel 之后定义 State 接口:
interface GettingStartedCodeLabState {
elapsed: number;
kitten: boolean;
}
State 接口不需要 export,因为它只在本文件内使用。接下来改用 Valdi 专门处理 State 的组件——StatefulComponent,并把 State 接口作为第二个泛型:
import { StatefulComponent } from "valdi_core/src/Component";
/**
* @Component
*/
export class GettingStartedCodelab extends StatefulComponent<
GettingStartedCodeLabViewModel,
GettingStartedCodeLabState
> {
初始化 state 变量:
/**
* @Component
*/
export class GettingStartedCodelab extends StatefulComponent<
GettingStartedCodeLabViewModel,
GettingStartedCodeLabState
> {
state = {
elapsed: 0,
kitten: false,
};
现在让 elapsed 动起来。在 onCreate 里设置定时器,并用 interval 属性持有引用:
private interval?: number;
onCreate() {
this.msg = 'Hello valdi on ';
this.kitten = true;
this.interval = setInterval(() => {
this.setState({ elapsed: this.state.elapsed + 1 });
}, 1000);
}
setInterval 是 JavaScript 提供的工具,会按固定延迟反复调用指定函数。第一个参数是要调用的函数——这里是一个调用 setState 递增 elapsed 的 lambda。setState 做的是部分更新:它不会替换整个对象,只更新传入的字段,kitten 的值保持不变。第二个参数是时间长度,单位为毫秒。
setInterval 会一直运行,所以组件销毁时必须清理:
onDestroy() {
if (this.interval) {
clearInterval(this.interval);
}
}
clearInterval 清除 setInterval 创建的定时器;onDestroy 是 Component 生命周期函数,在组件被销毁时调用。
现在读取并展示这个状态变量,在 onRender 中再加一个 <label>:
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value={this.viewModel.header} font={systemBoldFont(16)} />
<label value={`Time Elapsed: ${this.state.elapsed} seconds`} />
{this.onRenderMessage(fullMsg)}
</layout>;
}
注意新 <label> 的值使用了模板字符串,这里的符号是反引号(backticks)而不是普通引号。让热重载刷新后,观察计时器每秒递增。
再玩一下另一个 State 变量。更新 setInterval,让 kitten 依据 elapsed % 5 变化:
this.interval = setInterval(() => {
this.setState({
elapsed: this.state.elapsed + 1,
kitten: this.state.elapsed % 5 == 0,
});
}, 1000);
这会让 kitten 在每满 5 秒时变为 true。然后在 onRenderMessage 中消费 state.kitten(顺便清理掉此前的局部 kitten 变量):
onRenderMessage(message: string) {
if (this.state.kitten) {
<image height={50} width={50} src='https://placecats.com/300/300' />;
} else {
<label value={message} font={systemFont(12)} />;
}
}
观察 UI:大部分时间显示问候消息,每 5 秒出现一只小猫。
组件生命周期
先停下来梳理一下 Component 的生命周期。onCreate、onRender 等函数由 Valdi 运行时调用,用以标识组件生命周期的特定阶段,你可以在组件中重写它们来利用这些时机(详见 docs/codelabs/getting_started/6-component_lifecycle.md)。
onCreate
组件首次创建时调用一次,此时 ViewModel 和 State 已设置完毕,但渲染尚未开始。适合在此初始化局部变量和启动各类任务。
onViewModelUpdate(previousViewModel?: ViewModelType)
在以下时机被调用:ViewModel 被设置时;父组件在上一次 onRender 之后更新了 ViewModel 时;以及父组件在初始化时提供了 ViewModel 时(此时它紧跟在 onCreate 之后被调用)。onRender 总是紧随其后调用。
onRender
组件需要渲染时被调用。TSX 标签只有在 onRender 的调用栈内才有效果。onRender 有三种触发场景:
onCreate之后、组件初始化阶段;onViewModelUpdate被调用之后;- 在
StatefulComponent中,setState被调用之后。
onDestroy
组件被销毁时调用一次。当父组件不再在其 onRender 中渲染该子组件时,子组件即被销毁。onDestroy 是清理长时间运行任务和资源的理想位置(例如前文用 clearInterval 清理定时器)。
组件事件:触摸回调
动手前,你的组件应该与 7-component_events.md 中的状态一致:
import { StatefulComponent } from 'valdi_core/src/Component';
import { systemBoldFont, systemFont } from 'valdi_core/src/SystemFont';
export interface GettingStartedCodeLabViewModel {
header: string;
numKittens?: number;
}
interface GettingStartedCodeLabState {
elapsed: number;
kitten: boolean;
}
export class GettingStartedCodelab extends StatefulComponent<
GettingStartedCodeLabViewModel,
GettingStartedCodeLabState
> {
state = {
elapsed: 0,
kitten: false,
};
private msg?: string;
private kitten?: boolean;
private kittens = [
'https://placecats.com/300/300',
'https://placecats.com/300/301',
'https://placecats.com/300/302',
];
private interval?: number;
onCreate() {
this.msg = 'Hello valdi on ';
this.kitten = true;
this.interval = setInterval(() => {
this.setState({
elapsed: this.state.elapsed + 1,
kitten: this.state.elapsed % 5 == 0,
});
}, 1000);
}
onDestroy() {
if (this.interval) {
clearInterval(this.interval);
}
}
onRenderMessage(message: string) {
if (this.state.kitten) {
<image height={50} width={50} src='https://placecats.com/300/300' />;
} else {
<label value={message} font={systemFont(12)} />;
}
}
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value={this.viewModel.header} font={systemBoldFont(16)} />
<label value={`Time Elapsed: ${this.state.elapsed} seconds`} />
{this.onRenderMessage(fullMsg)}
</layout>;
}
}
触摸事件回调与"按钮"
部分元素暴露了处理触摸事件的 handler,你可以在元素上为特定事件注册回调。我们来做一个"添加小猫"的按钮。
首先在 State 中加一个记录猫咪数量的变量:
interface GettingStartedCodeLabState {
elapsed: number;
kitten: boolean;
numKittens: number;
}
初始化一个合理值:
state = {
elapsed: 0,
kitten: false,
numKittens: 1,
};
在 onRenderMessage 中消费该变量:
onRenderMessage(message: string) {
if (this.state.kitten) {
for (let i = 0; i < this.state.numKittens; i++) {
<image height={50} width={50} src='https://placecats.com/300/300' />;
}
} else {
<label value={message} font={TextStyleFont.BODY} />;
}
}
这个 for 循环会渲染 numKittens 张猫咪图片。为了更新 numKittens,在 onRender 里加一个按钮:
<layout>
<label value={this.viewModel.header} font={TextStyleFont.TITLE_1} />
<label value={`Time Elapsed: ${this.state.elapsed} seconds`} />
<view margin={20} backgroundColor='grey' borderRadius={8} padding={16}>
<label value='Add kitten' />
</view>
{this.onRenderMessage(fullMsg)}
</layout>;
是的,这个"按钮"其实是一个 <view>——它拥有实现按钮行为所需的全部回调。Valdi 的 CoreUI 组件库中也有风格化的现成按钮组件,但那是另一门 codelab 的主题。
现在点击按钮没有任何反应,因为还没有注册 onTap handler。先创建回调函数:
private buttonTapped = () => {
this.setState({ numKittens: this.state.numKittens + 1 });
};
交互回调应实现为 lambda(箭头函数),以确保回调不会在每次渲染时被重新创建——如果忘了写,linter 会提醒你。然后把它接到 onTap 上:
<view margin={20} backgroundColor='grey' borderRadius={8} padding={16} onTap={this.buttonTapped}>
<label value='Add kitten' />
</view>
多次点击按钮,观察 UI 中的小猫数量如何增长。
完整解决方案
7-component_events.md 末尾给出了完整的组件代码,供对照参考:
import { StatefulComponent } from 'valdi_core/src/Component';
import { systemBoldFont, systemFont } from 'valdi_core/src/SystemFont';
export interface GettingStartedCodeLabViewModel {
header: string;
numKittens?: number;
}
interface GettingStartedCodeLabState {
elapsed: number;
kitten: boolean;
numKittens: number;
}
export class GettingStartedCodelab extends StatefulComponent<
GettingStartedCodeLabViewModel,
GettingStartedCodeLabState
> {
state = {
elapsed: 0,
kitten: false,
numKittens: 1,
};
private msg?: string;
private kitten?: boolean;
private kittens = [
'https://placecats.com/300/300',
'https://placecats.com/300/301',
'https://placecats.com/300/302',
];
private interval?: number;
onCreate() {
this.msg = 'Hello valdi on ';
this.kitten = true;
this.interval = setInterval(() => {
this.setState({
elapsed: this.state.elapsed + 1,
kitten: this.state.elapsed % 5 == 0,
});
}, 1000);
}
onDestroy() {
if (this.interval) {
clearInterval(this.interval);
}
}
onRenderMessage(message: string) {
if (this.state.kitten) {
for (let i = 0; i < this.state.numKittens; i++) {
<image height={50} width={50} src='https://placecats.com/300/300' />;
}
} else {
<label value={message} font={systemFont(12)} />;
}
}
onRender() {
const fullMsg = this.msg + new Date().toLocaleTimeString();
<layout>
<label value={this.viewModel.header} font={systemBoldFont(16)} />
<label value={`Time Elapsed: ${this.state.elapsed} seconds`} />
<view margin={20} backgroundColor='grey' borderRadius={8} padding={16} onTap={this.buttonTapped}>
<label value='Add kitten' />
</view>
{this.onRenderMessage(fullMsg)}
</layout>;
}
private buttonTapped = () => {
this.setState({ numKittens: this.state.numKittens + 1 });
};
}
单元测试:验证 UI 行为
UI 写好了,如何确保它按预期工作?Valdi 使用 Jasmine 测试框架(详见 docs/codelabs/getting_started/8-unittest.md)。
测试文件放哪里
测试通常放在模块内部独立的 test 目录中。本 codelab 的测试位于 apps/helloworld/src/valdi/hello_world/test。创建测试文件:
cd apps/helloworld/src/valdi/hello_world
mkdir test
touch test/GettingStartedCodelab.spec.tsx
测试骨架
用下面这个最简结构替换文件内容:
import 'jasmine/src/jasmine';
import { valdiIt } from 'valdi_test/test/JSXTestUtils';
describe('GettingStartedCodelab', () => {
valdiIt('creates component', async driver => {
// Test logic goes here.
throw new Error('not implemented');
});
});
这段代码导入了测试框架,建立了一个名为 GettingStartedCodelab 的测试分组,并创建了一个名为 creates component 的测试。valdiIt 是 Valdi 提供的测试工具,为渲染组件提供额外能力。好的实践是:保持单元测试短小、命名具描述性。
更新 BUILD.bazel
运行测试需要把测试文件纳入模块。打开 apps/helloworld/src/valdi/hello_world/BUILD.bazel,更新 srcs 以包含 test 文件:
valdi_module(
name = "hello_world",
srcs = glob([
"src/**/*.ts",
"src/**/*.tsx",
"test/**/*.ts",
"test/**/*.tsx",
]) + [
"tsconfig.json",
],
并更新 deps 加入 valdi_test 依赖:
deps = [
"//src/valdi_modules/src/valdi/valdi_core",
"//src/valdi_modules/src/valdi/valdi_tsx",
"//src/valdi_modules/src/valdi/valdi_test",
"//src/valdi_modules/src/valdi/foundation",
],
(valdi_test 的源码位于 src/valdi_modules/src/valdi/valdi_test,包含 JSXTestUtils、IRenderedElementViewClass 等测试基础设施。)
运行测试
bazel build //apps/helloworld/src/valdi/hello_world:test
首次构建拉取测试依赖可能较慢。由于测试体里抛了 Not implemented 错误,预期会看到失败的输出:
//apps/helloworld/src/valdi/hello_world:test FAILED in 0.2s
Executing tests from //apps/helloworld/src/valdi/hello_world:test
-----------------------------------------------------------------------------
Randomized with seed 40852
Started
[0.065: INFO] [JS] - Jasmine execution started (1 specs)
[0.065: INFO] [JS] -------------------------------------
[0.065: INFO] [JS] -- Suite started: GettingStartedCodelab
[0.065: INFO] [JS] ---- Spec started: creates component
F[0.072: INFO] [JS] -- Suite passed: GettingStartedCodelab
[0.072: INFO] [JS] -------------------------------------
-------------------- Failures start:
1) GettingStartedCodelab creates component
Message:
Error: Not implemented
渲染一个 layout
测试能跑通后,把被测组件加载进来。在 creates component 测试中渲染组件:
describe('GettingStartedCodelab', () => {
valdiIt('creates component', async driver => {
const nodes = driver.render(() => {
<GettingStartedCodelab header='Stuff and things' />;
});
});
});
driver.render 会渲染你的组件并返回输出的引用,它可以渲染任意 TSX(类似 onRender),非常适合测试组件在不同尺寸容器下的布局表现。然后断言输出:
expect(nodes.length).toBe(1);
expect(nodes[0].component instanceof GettingStartedCodelab).toBeTruthy();
这里检查了两件事:只渲染了一个东西,且它是 GettingStartedCodelab。保存文件,热重载脚本会重新运行测试。
渲染单个组件并检查 header
如果只关心组件本身,用 createComponent 更简单。新建一个测试:
valdiIt('sets header', async driver => {
const instrumentedComponent = createComponent(GettingStartedCodelab, { header: 'Something' });
const component = instrumentedComponent.getComponent();
});
createComponent 会创建一个插桩(instrumented)组件,通过 getComponent() 拿到组件引用。然后取出 <label> 进行断言:
const labels = elementTypeFind(componentGetElements(component), IRenderedElementViewClass.Label);
VSCode 可能找不到这些导入,需要时手动补充:
import { IRenderedElementViewClass } from 'valdi_test/test/IRenderedElementViewClass';
import { componentGetElements } from 'foundation/test/util/componentGetElements';
import { elementTypeFind } from 'foundation/test/util/elementTypeFind';
elementTypeFind 找出所有特定类型的元素(元素即 Valdi 的原生类型,例如 <label> 对应 IRenderedElementViewClass.Label);对 Component 有类似的 componentTypeFind。这里我们从 GettingStartedCodelab 的所有子元素中筛选出 Label 类型。已知实现里第一个 <label> 就是 header,检查它:
const header = labels[0].getAttribute('value');
expect(header).toBe('Something');
然后通过 setViewModel 更新 ViewModel 并再次验证:
instrumentedComponent.setViewModel({ header: 'Something else' });
const header2 = labels[0].getAttribute('value');
expect(header2).toBe('Something else');
测试按钮逻辑
确认点击按钮会增加小猫数量。测试设置与前一个相同:
valdiIt('adds kittens', async driver => {
const instrumentedComponent = createComponent(GettingStartedCodelab, { header: 'Kittens' });
const component = instrumentedComponent.getComponent();
});
先确认初始数量正确:
expect(component.state.numKittens).toBe(1);
按钮是一个 view,所以取出所有 view 并取第一个:
const button = elementTypeFind(componentGetElements(component), IRenderedElementViewClass.View)[0];
onTap 只是元素上的一个属性,可以取出来并作为函数指针执行:
button.getAttribute('onTap')?.();
? 是空值检查,末尾的括号才是真正的函数调用。然后验证数量:
expect(component.state.numKittens).toBe(2);
保存文件,让热重载运行测试。
完整测试解决方案
8-unittest.md 末尾给出了完整的测试代码:
import 'jasmine/src/jasmine';
import { IRenderedElementViewClass } from 'valdi_test/test/IRenderedElementViewClass';
import { valdiIt, createComponent } from 'valdi_test/test/JSXTestUtils';
import { componentGetElements } from 'foundation/test/util/componentGetElements';
import { elementTypeFind } from 'foundation/test/util/elementTypeFind';
import { GettingStartedCodelab } from 'playground/src/GettingStartedCodelab';
describe('GettingStartedCodelab', () => {
valdiIt('creates component', async driver => {
const nodes = driver.render(() => {
<GettingStartedCodelab header='Stuff and things' />;
});
expect(nodes.length).toBe(1);
expect(nodes[0].component instanceof GettingStartedCodelab).toBeTruthy();
});
valdiIt('sets header', async driver => {
const instrumentedComponent = createComponent(GettingStartedCodelab, { header: 'Something' });
const component = instrumentedComponent.getComponent();
const labels = elementTypeFind(componentGetElements(component), IRenderedElementViewClass.Label);
const header = labels[0].getAttribute('value');
expect(header).toBe('Something');
instrumentedComponent.setViewModel({ header: 'Something else' });
const header2 = labels[0].getAttribute('value');
expect(header2).toBe('Something else');
});
valdiIt('adds kittens', async driver => {
const instrumentedComponent = createComponent(GettingStartedCodelab, { header: 'Kittens' });
const component = instrumentedComponent.getComponent();
expect(component.state.numKittens).toBe(1);
const button = elementTypeFind(componentGetElements(component), IRenderedElementViewClass.View)[0];
button.getAttribute('onTap')?.();
expect(component.state.numKittens).toBe(2);
});
});
后续学习路径与求助渠道
到这里,你已经完成了从环境搭建、Hello World、热重载、声明式渲染、控制流、状态管理、生命周期、触摸事件到单元测试的完整 Valdi 入门闭环。接下来可以沿着 start-code-lab.md 的推荐顺序继续深入:
- Valdi 与原生代码的集成:学习如何从 TypeScript 侧 hook 原生能力;
- 高级 UI:探索更复杂的界面构建技巧;
- 系统化文档见 docs/docs 目录 下的 core、advanced、workflow、stdlib 等系列文档。
如果在练习中遇到 UI 不更新或其他问题,先检查热重载进程日志,再查阅 How to get help 寻求帮助。另外,真实的 helloworld 应用(apps/helloworld)与其 Bazel 配置(apps/helloworld/BUILD.bazel)、package.json,以及 src/valdi_modules/src/valdi/valdi_test 下的测试工具源码,都是极佳的后续阅读材料——把文档练习与仓库源码对照阅读,能让你对 Valdi 的编译、渲染与测试机制有更立体的理解。