Valdi

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

📷 原文此处有图片，请前往 GitHub 仓库查看完整内容。
[!注意]
Beta状态： Valdi在过去8年中已广泛应用于Snap的生产应用程序。我们称其为Beta版本，是因为我们的工具和文档在开源世界中需要更多的实战测试。当我们对开发者体验满意时，Valdi将退出Beta。

Valdi是一款跨平台UI框架，能够在不牺牲开发者效率的情况下提供原生性能。 只需在声明式TypeScript中编写UI，它即可直接编译为iOS、Android和macOS上的原生视图——无需Web视图，无需JavaScript桥接器。

快速示例

一个基本的 Valdi 组件：

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>;
  }
}

快速开始

先决条件: Node.js 18 或更高版本（推荐 22），在 macOS 上需 Xcode 26.5 或 27。valdi dev_setup 将安装其余部分。请参阅 安装指南。

# Install Valdi CLI
npm install -g @snap/valdi

# One-command setup (installs all dependencies)
valdi dev_setup

# Create your first project
mkdir my_project && cd my_project
valdi bootstrap
valdi install ios  # or android

[!提示]
编辑器设置：不需要 Valdi 特定的扩展。请参阅 VSCode/光标设置 将您的编辑器指向工作区的 TypeScript 版本。

快速链接

• 入门指南
• 文档
• 编码实验室
• API 参考
• 常见问题
• 组件库
• GitHub 讨论
• 路线图

示例应用

apps/ 目录包含可运行的示例：

为什么选择Valdi？

Valdi 是一个跨平台的 UI 框架，旨在解决跨平台开发的根本问题：速度与运行时性能。8 年来，它为 Snap 大部分生产应用提供了动力。

真正的原住民表演

与依赖网页视图或 JavaScript 桥接的框架不同，Valdi 将声明式渲染的 TypeScript 组件编译为平台原生视图。Valdi 还包含其他若干性能优势：

• 自动视图回收 - 全局视图池系统在所有屏幕间重用原生视图，大幅减少膨胀延迟
• 优化组件渲染 - 组件独立重新渲染，不触发父重新渲染，实现快速增量更新
• 优化布局引擎 - C 语言布局引擎运行在主线程上，最小的编组开销
• 视口感知渲染 - 只有可见视图被放大，使无限滚动默认表现良好

在我们的性能优化指南中了解更多信息。

开发者体验，追求速度

Valdi 消除了传统的编译-测试-调试循环，这种循环会拖慢原生开发：

• 即时热重载 - 在iOS、Android或桌面端无需重新编译即可在毫秒级内看到变化
• 完整的 VSCode 调试 - 在 VSCode 中设置断点、检查变量、性能分析并捕获堆转储
• 熟悉的语法- TSX组件采用TypeScript以实现类型安全

灵活采用模式

Valdi 可以轻松集成到现有应用中 - 可以从小规模开始，根据需要扩展：

• 在原生中嵌入 Valdi - 将 Valdi 组件放入现有的 UIKit 或 Android 视图层次结构中
• 在 Valdi 中嵌入原生 - 通过 <custom-view> 在 Valdi 布局中使用特定平台视图
• 多语言模块 - 用 C、Swift、Kotlin 或 Objective-C 编写性能关键代码，并与 TypeScript 进行类型安全绑定
• 全栈架构 - 在 Valdi 中构建完整功能，通过工作线程进行后台处理，无需平台特定桥接代码

深度原生集成

Valdi 生成 TypeScript 与原生平台之间的类型安全绑定：

• 自动代码生成 - TypeScript 接口编译为 Kotlin、Objective-C 和 Swift 绑定
• 原生 API 访问 - 通过多语言模块直接访问平台 API 和第三方原生库
• 双向通信 - 在 TypeScript 和原生代码之间安全传递复杂数据结构和回调
• 原生 protobuf 支持 - 与 protobuf 无缝集成，实现高效数据序列化

经过大规模验证

• 在 Snap 应用生产环境中支持关键功能。
• 支持 高级动画、实时渲染和 复杂手势系统

功能亮点

• Flexbox 布局系统，自动支持从右到左布局
• 工作线程 用于多线程 JavaScript 执行
• 原生动画，提供原生外观和体验
• 高级手势识别，采用平台原生处理
• 内置测试框架，支持组件级单元测试
• Bazel 集成 用于可重现的增量构建

需要帮助？

• GitHub 讨论 — 提问并分享你正在构建的内容
• GitHub 问题 — 报告错误并请求功能

贡献

请遵循贡献指南。

许可

Valdi 根据 MIT 许可证 提供。