Valdi TSX 组件模式编译校验测试指南:用 Bazel 守护 valdi-tsx skill 的核心写法
Valdi TSX 组件模式编译校验测试指南:用 Bazel 守护 valdi-tsx skill 的核心写法
Valdi 是一套采用 TSX/JSX 语法、却直接编译为原生代码的跨平台 UI 框架。valdi-tsx skill 的 tests 目录提供了一份可编译的 reference.tsx,把 skill 中传授的每一个核心组件模式固化成可被 Bazel 构建验证的“编译检查样本”。本文以 ai-skills/skills/valdi-tsx/tests/README.md 为主体,结合 tests/src/reference.tsx、tests/BUILD.bazel 与 valdi-tsx skill 规范,讲解如何运行这套编译检查、它到底验证了哪些模式,以及当 Valdi API 演进时如何更新维护它。
这套测试的定位:把 skill 文档“可执行化”
valdi-tsx skill 的 tests 目录只做一件事:对 skill.md 中传授的核心 TSX 组件模式做编译检查(README 原文即 “Compile check for the core TSX component patterns taught in skill.md”)。它不运行单元测试、不渲染 UI,而是通过让一份精心编写的 reference.tsx 通过 Valdi TypeScript 编译器,来证明文档里的写法在当前 API 下依然成立。
这正是 Valdi 反幻觉机制的一部分:Valdi 不是 React,AI 助手常把 useState、函数组件、this.props 等 React 模式带进 Valdi 代码。而 reference.tsx 里每一条“✅ 正确写法”一旦因 API 变更而无法编译,构建就会失败,从而第一时间暴露 skill 文档与真实 API 之间的漂移。
ai-skills/skills/valdi-tsx/
├── skill.md # 组件规则文档(被测试守护的“内容”)
└── tests/
├── README.md # 测试说明(本文主体)
├── BUILD.bazel # Bazel 构建定义
├── tsconfig.json # 继承 valdi 基础 tsconfig
└── src/
└── reference.tsx # 编译检查样本(全部模式的载体)
如何运行编译检查
README 给出的命令为:
bazel build //ai-skills/skills/valdi-tsx/tests:tests
预期结果是 Build completed successfully(README 原文 Expected: Build completed successfully)。该目标定义在 tests/BUILD.bazel:
load("//bzl/valdi:valdi_module.bzl", "valdi_module")
valdi_module(
name = "tests",
srcs = glob([
"src/**/*.ts",
"src/**/*.tsx",
]) + [
"tsconfig.json",
],
android_output_target = "release",
ios_module_name = "SCCValdiTsxRef",
ios_output_target = "release",
visibility = ["//visibility:public"],
deps = [
"//src/valdi_modules/src/valdi/valdi_core",
"//src/valdi_modules/src/valdi/valdi_tsx",
],
)
从构建定义可以确认两点事实:
- 它使用
valdi_module宏构建,同时产出 Android(android_output_target = "release")与 iOS(ios_output_target = "release")目标,说明该样本必须对双端编译链路都成立; - 它的依赖只有
valdi_core与valdi_tsx两个模块——这正是reference.tsx中所有 import 的来源,也意味着测试范围被刻意收敛在核心 TSX API 上,不引入任何额外运行时依赖。
注意:README 中的
cd client/src/open_source是仓库内部布局下的历史路径说明。在本开源仓库中,BUILD.bazel位于ai-skills/skills/valdi-tsx/tests/下,只需在仓库根目录执行上述bazel build即可(确保已按 docs/setup/linux_setup.md 或 docs/setup/macos_setup.md 完成环境配置)。
tests/tsconfig.json 只有一行,继承自 Valdi 模块统一的基础配置:
{"extends": "../../../../src/valdi_modules/src/valdi/_configs/base.tsconfig.json"}
也就是说,编译检查运行在与业务模块完全相同的 TypeScript 配置下,模式写法的有效性结论可以直接迁移到 src/valdi_modules/、apps/、modules/ 等实际业务代码。
被验证的核心组件模式(逐一解读)
reference.tsx 按照 README 的 “What's tested” 清单,分块展示了九类核心模式。下面逐项结合 skill.md 与 valdi_core 源码说明其要点。
1. 无状态 Component<VM> 与返回 void 的 onRender()
interface GreetingViewModel {
name: string;
}
class Greeting extends Component<GreetingViewModel> {
onRender(): void {
// onRender returns void — no return statement
<label value={`Hello, ${this.viewModel.name}`} />;
}
}
要点:onRender() 返回值是 void,JSX 是语句而非返回值,绝不能 return <view />;。props 通过 this.viewModel 读取而非 this.props。valdi_core/src/Component.ts 中的基类注释明确说明 onRender() 在渲染阶段被调用,只有在该回调里才能执行 JSX 调用;onCreate() 在组件首次创建、首次渲染完成前调用;onViewModelUpdate() 在 viewModel 变化时调用(若组件被赋予初始 viewModel,则紧跟 onCreate() 之后触发);onDestroy() 在组件被移出层级时调用。
2. StatefulComponent、state/setState 与完整生命周期
class Counter extends StatefulComponent<CounterViewModel, CounterState> {
state: CounterState = { count: 0, inputText: '' };
onCreate(): void {
this.setTimeoutDisposable(() => {
this.setState({ count: 1 });
}, 5000);
}
onViewModelUpdate(previous?: CounterViewModel): void {
if (this.viewModel.label !== previous?.label) {
this.setState({ count: 0 });
}
}
onDestroy(): void {
// cleanup
}
// ...
}
要点:
- 状态以类字段
state = { ... }声明,更新必须走this.setState(...),直接改state不会触发重渲染; onViewModelUpdate收到previous参数用于比较新旧 props 变化;onDestroy用于释放资源。Component.ts 中setState对已销毁组件会打印警告:"Can't call setState on a destroyed component ... This operation does nothing, but it signals a potential memory leak",并提示应在onDestroy中取消所有订阅与异步任务。
3. 事件处理器必须用类箭头函数
// Class arrow functions — never inline lambdas in JSX props
private handleIncrement = (_event: unknown): void => {
this.setState({ count: this.state.count + 1 });
};
private handleTextChange = (event: { text: string }): void => {
this.setState({ inputText: event.text });
};
要点:事件处理器定义为类箭头函数字段,而不是 JSX 里的内联 lambda。交互元素用元素级回调,如 <label onTap={...}>、<button onPress={...}>、<textfield onChange={...} onEditEnd={...}>。Valdi 不支持 window.addEventListener、document.addEventListener、keydown 等全局 DOM 事件;macOS 桌面端键盘输入需通过 polyglot <custom-view> 绑定原生 NSView 的 keyDown: 事件。
4. setTimeoutDisposable 自动清理定时器
onCreate(): void {
// Timer auto-cancels on destroy
this.setTimeoutDisposable(() => {
this.setState({ count: 1 });
}, 5000);
}
要点:组件内的定时器一律用 this.setTimeoutDisposable(),它会在组件销毁时自动失效,避免内存泄漏。其底层实现在 Component.ts:内部调用 setTimeoutInterruptible 拿到 timerId,再通过 registerDisposable 注册销毁回调 clearTimeout(timerId)。因此不要直接用裸 setTimeout/setInterval——它们不会自动清理。循环任务用递归 setTimeoutDisposable 实现,而非 setInterval。
5. 列表渲染用 forEach 而非 map
class ItemList extends Component<ItemListViewModel> {
onRender(): void {
<scroll>
{this.viewModel.items.forEach(item => {
// Stable key from data ID — not array index
<view key={item.id}>
<label value={item.title} />;
</view>;
})}
</scroll>;
}
}
要点:渲染列表用 forEach 块,key 取数据自带的稳定 ID(key={item.id})而非数组下标。注意 <scroll>(ScrollView)不支持 flexDirection,始终纵向滚动,其 Style 中写 flexDirection: 'column' 会触发构建错误。
6. <layout> 撑位与模块级 Style 对象
const styles = {
card: new Style<View>({
backgroundColor: '#fff',
borderRadius: 8,
padding: 12,
flexDirection: 'column',
}),
spacer: new Style<Layout>({ height: 8 }),
title: new Style<Label>({
color: '#000',
font: systemFont(16), // Label uses font string, NOT fontSize
}),
};
// ...
<view style={styles.card}>
<label value={`${this.viewModel.label}: ${this.state.count}`} />;
<layout style={styles.spacer} />;
// ...
</view>;
要点:
Style对象放在模块顶层(“Module-level styles (NOT inside onRender)”),而非onRender内;<layout>是纯布局元素(无原生视图),可用作垂直/水平撑位,这里用new Style<Layout>({ height: 8 })制造 8pt 间距;Style<View>只能用于<view>,Style<Label>只能用于<label>,类型不匹配会编译报错;Style<Layout>对任何布局元素都合法(view/label 都继承 Layout);- Label 的字体用
font: 'system 20'或systemFont(16)辅助函数,不是fontSize。系统字体现已支持 medium、semibold、italic 等变体(systemMediumFont、systemSemiboldFont、systemItalicFont等),但system-light仍不存在; - 组合样式用
Style.merge(...)/.extend({...}),不能 merge 不兼容的元素类型。
7. Provider 依赖注入模式
const ThemeProvider = createProviderComponentWithKeyName<ThemeService>('ThemeProvider');
interface ThemedViewModel extends ProvidersValuesViewModel<[ThemeService]> {
text: string;
}
class ThemedLabel extends Component<ThemedViewModel> {
onRender(): void {
const [theme] = this.viewModel.providersValues;
<label value={this.viewModel.text} />;
void theme; // reference theme to satisfy compiler
}
}
const ThemedLabelWithProvider = withProviders(ThemeProvider)(ThemedLabel);
class AppRoot extends Component {
private theme = new ThemeService();
onRender(): void {
<ThemeProvider value={this.theme}>
<ThemedLabelWithProvider text="Hello" />;
</ThemeProvider>;
}
}
要点:Provider 组件用 createProviderComponentWithKeyName 创建并作为模块级常量保存;渲染 <Provider value={...}> 提供依赖;消费方让 ViewModel 继承 ProvidersValuesViewModel<[...]>,再用 withProviders(Provider)(Component) 包装成 HOC,即可在 this.viewModel.providersValues 中按序解出依赖。
底层原理可从源码确认:createProvider.tsx 中 createProviderComponentWithKeyName 用唯一 key 名创建 ProviderKey 后交给 createProviderComponent;Provider 本身是 StatefulComponent,在 onViewModelUpdate 中把新值写入 provider source 并通过 setState 触发子树重渲染,onRender 输出 <slot key={providerValueKey}> 以重建消费方。而 withProviders.tsx 只是把 Provider 类映射为 ProviderKey 后转调 withProviderKeys,后者生成的包装组件在 onCreate 中通过 resolveProviderValue 解析 provider 值,再在 onRender 中透传 providersValues 给内部组件。
8. Device 平台检测
class MediaPlayer extends Component<MediaPlayerViewModel> {
onRender(): void {
<view>
{Device.isIOS() && <label value="iOS player" />}
{Device.isAndroid() && <label value="Android player" />}
{Device.isDesktop() && <label value="macOS player" />}
</view>;
}
}
要点:可用守卫包括 Device.isIOS()、Device.isAndroid()、Device.isDesktop()、Device.isWeb()。Device.isDesktop() 对 macOS 桌面应用(preview/standalone app)为真;不存在 Device.isMacOS()。在 <custom-view> 等未全平台实现的元素前必须先做平台守卫。
9. @ExportModel ViewModel 的导出限制
type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
/**
* @ViewModel
* @ExportModel
*/
interface GameViewModel {} // Don't put Direction here — it can't be exported
interface GameState {
direction: Direction; // Type aliases are fine in State (not exported)
score: number;
}
要点:被 @ViewModel @ExportModel 注解、导出到原生代码的 ViewModel 只能包含原始类型(string/number/boolean)与其他 @ExportModel 接口;自定义 type alias(如 type Direction = 'UP' | 'DOWN')会触发编译器 "Unrecognized type" 错误。自定义类型应放进不导出的 State 中。
更新维护流程:API 变更时如何同步
README 的 “Updating” 一节给出了明确的维护约定:
当 Valdi API 发生变更(import 路径、类型签名)时,更新
src/reference.tsx使其保持可编译,同时把修正后的模式同步回../skill.md。
具体分三步:
- 改测试:按新 API 更新 tests/src/reference.tsx 中的 import 路径、类型签名或模式写法;
- 跑构建:在仓库根目录执行
bazel build //ai-skills/skills/valdi-tsx/tests:tests,确认Build completed successfully; - 同步文档:将修正后的写法回写 ai-skills/skills/valdi-tsx/skill.md,保证文档、测试与真实 API 三者一致。
这一约定把“文档更新”变成了“先有编译证据、再改文字”的流程:任何会破坏既有模式的 API 变更,都会先让构建红掉,从而强制文档维护者同步修正 skill 内容。反过来,新增模式时也应先在 reference.tsx 中落地可编译样本,再写入 skill.md,避免文档出现无法编译的“幻觉代码”。
与 anti-hallucination 机制的关系
AGENTS.md 与 skill.md 汇总了最常见的 React 模式误用,本测试正是这些规则的“机器可执行”版本:
onRender()返回 JSX → 应为 void,JSX 是语句;- 忘用
setState()直接改 state → 不触发重渲染; - 用
this.props→ 应为this.viewModel; - 生命周期叫 mount/update/unmount → 应为
onCreate/onViewModelUpdate/onDestroy; - 用
scheduleRender()→ 已废弃,改用StatefulComponent + setState(); - 用
addEventListener→ 用onTap/onPress/onChange等元素回调; - 裸用
setTimeout/setInterval→ 用this.setTimeoutDisposable(); - 用
paddingHorizontal/paddingVertical→ 用padding: '0 20'/padding: '10 0'(gap/rowGap/columnGap已随 Yoga 升级可用); - 用
flex: 1→flex在 View 上不存在,用flexGrow: 1; - 在 Label 上用
fontSize→ 用font: 'system 20'字符串; - 用
overflow: 'hidden'→ View 只接受'visible' | 'scroll'; - 在
@ExportModelViewModel 中使用 type alias → 编译器不识别; - 在 ScrollView 上设
flexDirection→ 不支持,始终纵向滚动。
凡是出现在这个清单里的错误写法,都不可能在 reference.tsx 中通过编译——这正是该测试作为“Valdi 写法红线”的守护价值。
小结
valdi-tsx skill 的 tests 目录用一份文件、一条 Bazel 命令,把 skill 文档中九类核心 TSX 模式(无状态/有状态组件、生命周期、箭头函数事件、自动清理定时器、forEach 列表、<layout> 撑位、模块级 Style、Provider 注入、平台检测、@ExportModel 约束)固化为可持续验证的编译检查。日常使用中,它是确认“这种写法在当前 Valdi API 下是否成立”的最快途径;在 API 演进时,它又是强制文档与实现同步的护栏。无论是 AI 辅助编码、代码审查还是框架升级,bazel build //ai-skills/skills/valdi-tsx/tests:tests 都值得作为 Valdi 组件开发的一道标准回归门槛。