Valdi TSX 组件模式编译校验测试指南:用 Bazel 守护 valdi-tsx skill 的核心写法

原创2026-09-21 14:13:031,635 阅读
文章标签:跨平台UI组件前端移动开发

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。

具体分三步:

  1. 改测试:按新 API 更新 tests/src/reference.tsx 中的 import 路径、类型签名或模式写法;
  2. 跑构建:在仓库根目录执行 bazel build //ai-skills/skills/valdi-tsx/tests:tests,确认 Build completed successfully;
  3. 同步文档:将修正后的写法回写 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';
  • 在 @ExportModel ViewModel 中使用 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 组件开发的一道标准回归门槛。

登录后查看全文
Valdi