# Valdi框架开发技巧使用 Valdi 开发跨平台应用程序的专业指南，Valdi 是 Snapchat 的本机 UI 框架，可将 TypeScript/TSX 编译为本机 iOS、Android 和 macOS 视图。 ## 概述 Valdi 不是基于 WebView 的框架。它将 TypeScript 组件直接编译为本机平台代码，无需 JavaScript 桥即可提供本机性能。该框架已在 Snap 的生产应用程序中使用了 8 年多。 ## 何时使用此技能在以下情况下调用该技能： * 从事任何 Valdi 框架项目 * 创建新的 Valdi 组件或模块 * 为 Valdi 配置 Bazel 构建文件 * 实现本机绑定（CppModule、NativeModule） * 调试跨平台渲染问题 * 设置Valdi开发环境 * 了解 Valdi 的 TSX 元素系统 ## 关键原则 ### 1\. Bazel 是强制性的 Valdi 专门使用 Bazel 进行构建。切勿建议替代构建系统。 **常用命令：** # 全局安装CLI pnpm 安装-g @snap/valdi # 设置开发环境瓦尔迪开发设置 # 检查环境健康状况瓦尔迪医生 # 引导新项目瓦尔迪引导程序 # 安装平台依赖项瓦尔迪安装ios 瓦尔迪安装安卓 # 开发期间启用热重载瓦尔迪热重载 # 同步项目配置瓦尔迪项目同步 ### 2\.组件架构 Valdi 组件是基于类的，具有生命周期方法：从 'valdi_core' 导入 { Component, ComponentContext }; 接口视图模型{ 标题：字符串；计数：数量； } 类 MyComponent 扩展 Component { onCreate(): 无效 { // 初始化组件 console.log('组件已创建'); } onMount(): 无效 { // 组件挂载以查看层次结构 } onUnmount(): 无效 { // 删除前清理 } onRender() { 返回（ <视图样式={styles.container}> {this.viewModel.title} ）； } } ### 3\.本地 TSX 元素 Valdi 提供原生 UI 元素（不是 HTML）：元素|目的 ---|--- `<视图>` |容器视图（如 div） `<布局>` | Flexbox布局容器 `<滚动>` |可滚动容器 `<标签>` |文字显示 `<图像>` |图像展示 `<视频>` |视频播放器 `<插槽>` |内容投影 **元素属性使用本机样式，而不是 CSS：** 常量样式 = { 容器：{ 对齐项目：'居中'， justifyContent: '中心', 背景颜色: '#FFFFFF', 填充：16， }, 标题：{ 字体大小：24，字体粗细：'粗体'，颜色：'#000000'， }, }; ### 4\.项目结构标准 Valdi 项目布局：我的项目/ ├── BUILD.bazel # 主 Bazel 构建文件 ├── package.json # 节点依赖（使用pnpm） ├── .eslintrc.js # ESLint 配置 ├── app_assets/ # 应用程序资产 │ └── 图片/ ├── src/ │ ├── android/ # Android 专用代码 │ ├── cpp/ # C++ 原生模块 │ ├── ios/ # iOS 专用代码 │ └── valdi/ # Valdi TypeScript/TSX │ ├── _configs/ # Valdi 配置 │ ├── tsconfig.json │ ├── .terserrc.json │ └── my_module/ # 你的模块 │ ├── BUILD.bazel │ ├── tsconfig.json │ ├── res/ # 模块资源 │ └── src/ │ ├── 索引.ts │ └── MyComponent.tsx └──standalone_app/ # 独立应用程序配置 ### 5\. Bazel 构建配置 **应用程序BUILD.bazel：** 加载（“//bzl：valdi.bzl”，“valdi_application”，“valdi_exported_library”） valdi_应用程序（名称 =“我的应用程序”， title = "我的 Valdi 应用程序", 版本=“1.0.0”， ios_bundle_id = "com.example.myapp", ios_device_families = [“iPhone”]， android_theme = "主题.MyApp.Launch", android_app_icon = "应用程序图标", root_component = "App@my_module/src/MyApp", 资产 = glob(["app_assets/**/*"]), deps = [“//路径/到/src/valdi/my_module”]，） valdi_exported_library（名称 =“my_app_export”， ios_bundle_id = "com.example.myapp.lib", Bundle_name = "我的应用程序", deps = [“//路径/到/src/valdi/my_module”]，） **模块BUILD.bazel：** 加载（“//bzl：valdi.bzl”，“valdi_module”） valdi_模块（名称 =“我的模块”， srcs = glob(["src/**/*.ts", "src/**/*.tsx"]) + ["tsconfig.json"], 资产 = glob(["res/**/*.{jpeg,jpg,png,svg,webp}"]), 安卓 = 结构（ class_path = "com.example.valdi.modules.my_module", native_deps = ["//path/to/android:native_module"], 释放=真， ), ios = 结构( module_name = "SCCMyModule", native_deps = [“//路径/到/ios：native_module”]，释放=真， ), 本机 = 结构（ deps = ["//路径/到/cpp:native_module_cpp"], ), 部门 = [ “//src/valdi_modules/valdi_core”， “//src/valdi_modules/valdi_tsx”， ], 可见性 = ["//可见性:公开"], ） ### 6\.本机绑定 Valdi 支持与本机代码的类型安全绑定： **CppModule.d.ts：** 声明模块'CppModule'{ 导出函数 PerformCalculation(value: number): number; 导出函数 getNativeString(): string; } **NativeModule.d.ts：** 声明模块 'NativeModule' { 导出函数 showNativeAlert(message: string): void; 导出函数 getPlatformInfo(): { os: string;版本：字符串}； } **在组件中的用法：** 从“CppModule”导入*作为CppModule；从“NativeModule”导入*作为NativeModule；类 MyComponent 扩展 Component { onMount() { const 结果 = CppModule.performCalculation(42); const 平台 = NativeModule.getPlatformInfo(); } } ### 7\.跨平台最佳实践 **所有更改必须适用于 iOS、Android 和 macOS：** * 提交前在多个平台上进行测试 * 特定于平台的代码位于专用目录中（src/ios/、src/android/） * 使用Valdi的抽象层来处理平台差异 * 检查存储库中的 AGENTS.md 以获取特定于平台的指导 **性能至关重要：** * Valdi强调渲染效率 * 通过 Valdi 的池化系统使用视图回收 * 组件独立渲染（没有父级重新渲染） * 视口感知渲染以实现高效滚动 ### 8\.开发流程 **初始设置：** # 安装 Valdi CLI pnpm 安装-g @snap/valdi # 设置开发环境（第一次需要10-20分钟）瓦尔迪开发设置 # 验证安装瓦尔迪医生 **创建一个新项目：** mkdir my_project && cd my_project 瓦尔迪引导程序 valdi 安装 ios # 或 android **开发周期：** # 启动热重载以进行实时更新瓦尔迪热重载 # 更改依赖项或资源后瓦尔迪项目同步 **编辑器设置（VSCode/光标）：** 1. 从编辑器安装 shell 命令 2. 安装 Valdi 版本的扩展： * `valdi-vivaldi.vsix`（设备日志、语言支持） * `valdi-debug.vsix` （JavaScript 调试器） 3.配置TypeScript工作区版本 ## 常见陷阱 ### 1\.使用 Web/React 模式 **问题：** 像 React 或 Web 开发一样对待 Valdi。 // 错误 - HTML 元素不存在

你好

// 正确 - 使用 Valdi 原生元素 <视图样式={styles.container}> <标签>你好 ### 2\. CSS 风格样式 **问题：** 对样式使用 CSS 语法。 // 错误 - CSS 语法常量样式 = { 容器：{ '背景颜色': '#fff', '字体大小': '16px', } }; // 正确 - 驼峰式大小写，数值常量样式 = { 容器：{ 背景颜色: '#FFFFFF', 字体大小：16， } }; ### 3\.修改自动生成的代码 **问题：** 直接编辑 Djinni 生成的本机绑定。 **解决方案：** 始终修改源文件，从不生成代码。源更改后重新生成绑定。 ### 4\.错误的构建系统 **问题：** 使用 npm/yarn 脚本、webpack 或其他捆绑器。 **解决方案：** Valdi 专门使用 Bazel。使用“valdi”CLI 命令。 ### 5\.缺少平台测试 **问题：** 仅在一个平台上进行测试。 **解决方案：** 始终验证更改是否适用于 iOS、Android 和 macOS（如果适用）。 ## ESLint 配置标准 Valdi ESLint 设置： // .eslintrc.js 模块. 导出 = { 解析器：'@typescript-eslint/解析器'，解析器选项：{ 项目：'./tsconfig.json'， ecma版本：2020，源类型：'模块'， ecma 功能：{ jsx：正确， }, }, 插件：[ '@typescript-eslint', 'eslint-插件-valdi', 'rxjs', '导入', '未使用的进口'， ], 延伸：[ 'eslint：推荐'， '插件：@typescript-eslint/推荐', ], 规则：{ // Valdi 特定规则 }, }; ## TypeScript 配置 Valdi 模块的标准 tsconfig.json： { “扩展”：“../../_configs/tsconfig.json”， “编译器选项”：{ “jsx”：“反应”， "jsxFactory": "Valdi.createElement", “严格”：真实， "moduleResolution": "节点", “esModuleInterop”：true }, “包括”：[“src / ** / *”] } ## 可用的库 Valdi 提供以下核心模块：模块|目的 ---|--- `valdi_core` |核心组件系统、生命周期 `valdi_tsx` | TSX/JSX 支持 `valdi_protobuf` | Protobuf序列化 `valdi_http` | HTTP客户端 `valdi_storage` |持久加密存储 `valdi_navigation` |导航系统 `valdi_rxjs` | RxJS 集成 ## 调试 **使用 Hermes 调试器：** * 可用于 JavaScript 调试 * 使用 valdi-debug 扩展在 VSCode 中设置断点 **使用 Valdi 检查器：** * 检查UI层次结构 * 查看组件状态 * 性能分析 ## 快速参考 ### CLI 命令命令 |目的 ---|--- `valdi dev_setup` |设置开发环境 `瓦尔迪医生` |检查环境健康状况 `valdi 引导程序` |创建新项目 `valdi 安装 [平台]` |安装平台依赖项 `valdi 热重载` |启用实时更新 `valdi 项目同步` |同步项目配置 ### 生命周期方法方法|被叫时 ---|--- `onCreate()` |组件初始化 `onMount()` |添加到视图层次结构 `onUnmount()` |从层次结构中删除之前 `onRender()` |渲染组件 UI ### 原生元素元素| HTML 等效项 ---|--- `<视图>` | `

` `<布局>` |弹性盒容器 `<滚动>` |可滚动div `<标签>` | `<跨度>` / `

` `<图像>` | `` `<视频>` | `<视频>` ## 参考文献欲了解更多详情： * `references/component-patterns.md` \- 高级组件模式 * `references/bazel-configuration.md` \- 详细的 Bazel 设置 * `references/native-bindings.md` \- 原生代码集成 ## 其他资源 * Valdi GitHub： * AI 编码指南存储库中的 AGENTS.md * Discord 社区寻求支持 * docs/ 中的 Codelabs 用于指导教程 ** ** **记住：** Valdi 编译为本机代码 - 考虑本机代码，而不是 Web。使用 Bazel 进行构建，使用 pnpm 进行 Node 依赖项，并在所有目标平台上进行测试。

选择了

包含技能