Valdi Codelab 从零入门:用 TypeScript 构建跨平台声明式 UI 的完整实践指南

原创2026-09-21 16:44:011,325 阅读
文章标签:跨平台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 按推荐顺序组织,适合自学、循序渐进:

  1. TypeScript 语言入门(外部资源,可在 typescriptlang.org 官方文档的 Get Started 部分学习);
  2. 从零开始上手 Valdi(本文核心展开内容);
  3. Valdi 与原生代码的集成;
  4. 高级 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 的推荐顺序继续深入:

如果在练习中遇到 UI 不更新或其他问题,先检查热重载进程日志,再查阅 How to get help 寻求帮助。另外,真实的 helloworld 应用(apps/helloworld)与其 Bazel 配置(apps/helloworld/BUILD.bazel)、package.json,以及 src/valdi_modules/src/valdi/valdi_test 下的测试工具源码,都是极佳的后续阅读材料——把文档练习与仓库源码对照阅读,能让你对 Valdi 的编译、渲染与测试机制有更立体的理解。

登录后查看全文
Valdi