voltra

## 变更内容 * refactor(core)：在 iOS 和 Android 客户端之间共享 useUpdateOnHMR hook，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/305 * refactor(types)：将共享平台类型整合到 @use-voltra/core，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/303 * refactor：移除未使用的内部模块，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/304 * refactor(android-client)：移除 addVoltraListener 中无用的相同分支，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/306 * fix(metro)：配置 Dynamic Widget 后停止 release 构建挂起，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/313 **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v2.3.1...v2.3.2

## 变更内容 * fix(release)：可靠地发布包并恢复失败的发布，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/236 * fix(android)：停止在 Android 11 及更早版本上崩溃的加速 widget 更新工作，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/291 * fix(cli)：对无法生效的 widget 配置发出警告，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/296 * fix(android)：刷新绘制刷新按钮的放置位置，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/297 * fix(release)：针对一个截止时间进行验证并完成半完成的发布，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/298 **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v2.3.0...v2.3.1

- **服务器驱动的 Dynamic Widgets** — Dynamic Widgets 现在可以按计划、按放置位置从你的服务器获取自己的 props，而不再依赖应用推送更新。 - **Android 上可配置的 widgets** — 每个放置的 widget 可以通过 `setWidgetInstanceConfiguration` 保存自己的设置（例如一个显示伦敦，另一个显示纽约），并且这些设置在启动器备份/恢复后仍然保留。 - **Dynamic Live Activities（实验性，iOS）** — Live Activities 现在可以通过小的 JSON prop 更新来驱动，而不是每次重新渲染完整 payload，并且在你构建时支持热重载。 - **Android 的 `ArcProgressIndicator`** — 一个新的确定性弧形仪表 widget 组件，具有可配置的描边宽度、角度、圆角/平角端点和渐变填充。 ## 变更内容 * feat(ios)：添加 dynamic Live Activities，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/239 * docs(v2)：为清晰起见精简、去重并拆分文档，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/241 * fix(cli)：按构建配置应用 iOS 更改，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/245 * feat(cli)：接受按构建配置的 iOS 值，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/246 * docs(v2)：记录按构建配置的 iOS 值，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/247 * ci：在针对任意基础分支的 pull request 上运行 CI，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/258 * fix(android)：支持 Android 7.0-11（API 24-30）上的 widgets，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/250 * fix(android)：保护 API 26 通知构建器并声明真实的 minSdk 下限，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/251 * fix(android)：保护剩余的 NewApi lint 发现，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/252 * ci(android)：运行 Android Lint 并让其使构建失败，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/254 * fix(android)：始终输出 widget 的 minWidth 和 minHeight，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/253 * feat(android)：支持 widget 调整大小边界，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/256 * fix：从包元数据推导 Voltra 版本，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/238 * fix(ios)：在 widget 时间线重新加载之间保留最后一次服务器响应，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/260 * fix(android)：当 applicationId 与 namespace 不同时的 widget receiver，由 @Minishlink 提交于 https://github.com/callstackincubator/voltra/pull/259 * fix(android)：在更新前解析 widget kind 并隔离 Dynamic 占位符读取，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/261 * refactor(android)!：将 payload 驱动的和 Dynamic widget 代码拆分为单独的包，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/262 * fix(cli)：在生成的 widget bundle 中导入 VoltraRuntime 模块，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/265 * fix(ios)：在 Dynamic Live Activities 中对 small family 应用 activityBackgroundTint，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/267 * docs(adr)：服务器驱动的 Dynamic Widgets，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/266 * feat：服务器驱动的 Dynamic Widgets，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/271 * feat：在 widget 代码中支持 react-native 导入，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/270 * feat(android)：添加 ArcProgressIndicator widget 组件，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/268 * feat(charts)：将 y 轴缩放到数据并添加 yScale prop，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/269 * feat(ios)：添加 widget `kind` 选项以在迁移期间保留已放置的 widgets，由 @rlods 提交于 https://github.com/callstackincubator/voltra/pull/272 * fix(ios)：停止配置插件丢弃应用的 URL schemes，由 @rlods 提交于 https://github.com/callstackincubator/voltra/pull/280 * feat(android)：按放置实例配置 Dynamic Widgets，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/285 * feat：按配置获取服务器驱动的 Dynamic Widget props，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/286 * feat(android)：在启动器恢复后保留实例配置，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/288 * refactor(ios)：在不使用 SwiftUI 的情况下编译 payload AST，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/281 * fix(ios)：在 payload 引用到达元素身份之前解析它们，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/282 ## 新贡献者 * @Minishlink 在 https://github.com/callstackincubator/voltra/pull/259 中做出了他们的首次贡献 * @rlods 在 https://github.com/callstackincubator/voltra/pull/272 中做出了他们的首次贡献 **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v2.2.0...v2.3.0

## 变更内容 * fix(ios)：加固 Podfile widget-target 生成，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/212 * fix(ios)：停止因预先存在的应用扩展导致 Xcode 项目损坏，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/211 * fix：加固 Android 构建和打包流水线，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/210 * fix：在 Android 上支持 RN 0.81.5 及以下 Hermes prefab target，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/217 * refactor(ios)!：统一 widget Xcode 流水线、按配置签名、版本传递，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/213 * docs：添加 agent 贡献指南，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/225 * fix(android)：确保 16 KB ELF 对齐，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/233 * feat：在 Dynamic Widgets 中支持运行时 props，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/229 * feat(android)：当超出布局子项限制时发出警告，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/228 * ci：添加 npm 发布工作流，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/219 * fix(metro)：在 widget 打包器中监视项目根目录，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/234 * fix(release)：解除发布推送阻塞并停止虚假的主版本号提升，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/235 **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v2.1.1...v2.2.0

此版本引入了 **Dynamic Widgets**，由 Voltra 新的原生端渲染引擎提供支持。 你的 Voltra 组件现在会被单独打包，并在专用的 JS VM 实例中渲染，使它们即使在你的应用未运行时也能响应环境变化。这意味着你可以根据 props 或环境变量动态调整布局，例如 iOS 渲染模式：全彩或强调色。 **此功能被标记为实验性，需要显式选择启用。** 有关如何使用 Dynamic Widgets 的更多信息，请参阅以下资源： [iOS 文档](https://www.use-voltra.dev/ios/development/dynamic-widgets) [Android 文档](https://www.use-voltra.dev/android/development/dynamic-widgets)

此版本的 Voltra 侧重于引入重大架构变更，并为即将推出的功能准备更好的基础。 * 你现在可以在 bare React Native 项目中使用 Voltra，因为它不再需要 Expo Modules。 * 我们完全重构了代码以使用 Turbo Modules，它们内置于 React Native 本身。 * 我们还将 Voltra 分解为一组更小的包，因此你的服务器安装不再拉取数百个移动端依赖项。 Live Activities 使用的 Voltra 协议没有改变。相同的 payload 可以由旧版和新版 Voltra 传递并正确解码。 **需要进行迁移。有关变更详情，请参阅[迁移指南](https://www.use-voltra.dev/getting-started/migration-v2)。**

大家好！ 好久不见！我们一直忙于将 Voltra 从 Expo Modules 迁移到 Turbo Modules，并为 bare React Native 实现一部分 Expo Config Plugins，这样你也可以在非 Expo 应用中使用 Voltra。我们相信我们非常接近发布，并希望在发布前获得你的反馈。 v2.0.0 RC 现已在 npm 上提供 🎉 如果你能试用并报告遇到的任何问题，我们将不胜感激。 请注意，已发布的文档仅适用于最新的稳定版本。请务必改用 GitHub 上的文档，因为它包含最新的说明。 有关此版本的讨论，请参阅 https://github.com/callstackincubator/voltra/discussions/177。

## 变更内容 * fix：iOS 上的 widget 背景，由 @MikitasK 提交于 https://github.com/callstackincubator/voltra/pull/124 * fix(android)：在文本渲染器中遵循 maxLines/numberOfLines，由 @hsravat-4590 提交于 https://github.com/callstackincubator/voltra/pull/140 ## 新贡献者 * @MikitasK 在 https://github.com/callstackincubator/voltra/pull/124 中做出了他们的首次贡献 * @hsravat-4590 在 https://github.com/callstackincubator/voltra/pull/140 中做出了他们的首次贡献 **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v1.4.0...v1.4.1

## 亮点 你可以发布**Android 主屏幕 widgets**，它们会自动匹配每个用户手机的外观：浅色、深色或与壁纸关联的**动态 Material You** 颜色——让 widgets 感觉像是系统的一部分，而不是外挂面板。 **Android 常驻（持久）通知**已得到端到端支持：你可以显示更丰富、可更新的通知 UI，远程刷新它，并在服务器上渲染 payload，使内容与你的 Voltra 技术栈其余部分保持一致。**Expo 插件**和文档会引导你在典型应用工作流中配置和操作这些通知。 该库在你的应用中仍然以 **`voltra`** 的形式使用；内部包拆分不会改变你正常集成时导入的内容。 ## 功能 - 在 Android 上添加了感知主题和壁纸的 widget 颜色（包括 Material You）。 - 添加了 Android 常驻通知支持（更丰富的内容、远程更新、服务器端 payload 渲染、Expo 插件集成和文档）。 - 将更多实现移入 `@use-voltra/*` 包；`voltra` 仍然是总入口。 ## 修复 - 改进了压缩/release 构建中的 Android widget payload 处理。 - 修复了 iOS Live Activity 命名，使命名活动在应用启动之间可靠复用。

# ⚡️ Voltra 1.3.1 https://github.com/user-attachments/assets/2f3f97b1-17f0-4ca1-99a7-681a3bc1576b _[视频由 @DorianMazur 提供](https://x.com/dorian__mazur/status/2034673754815553684)_ 我很高兴宣布 **Voltra 1.3.0**！此版本为 Voltra 带来了两个重大新增功能：**服务器驱动的 widgets** 和**图表**。它们共同让你更容易构建保持新鲜、感觉动态并以更丰富方式呈现实时数据的 widgets。 --- ## 💎 亮点 ### ☁️ 服务器驱动的 widgets（iOS 和 Android） Voltra 现在在 iOS 和 Android 上都支持**服务器驱动的 widgets**。通过新的 `serverUpdate` 配置，widgets 可以直接从你的后端获取新鲜内容，即使应用已关闭。 这开启了一整类新的 widgets。天气、投资组合、比分、仪表盘以及其他快速变化的体验现在可以通过计划的后台刷新保持最新，Voltra 会为你处理客户端管道。 此版本还包括支持该流程所需的服务器端辅助工具，以及感知主题的请求和对原生刷新按钮的支持，以便用户可以按需手动触发更新。 ### 📈 图表（iOS 和 Android） Voltra 现在包含用于 widgets 和 Live Activities 的新 **Chart** 组件系列，使构建视觉丰富、数据驱动的体验变得更加容易。 支持的图表类型包括折线图、面积图、柱状图、点图、规则线和饼图/环形图。图表与服务器驱动的 widgets 搭配使用时尤其强大，让你可以从后端获取实时数据，并以更具表现力、更易浏览的格式呈现。 --- ## ✨ 功能 - **服务器驱动 widgets 的原生刷新按钮（iOS 和 Android）：** Widgets 现在可以通过 `serverUpdate.refresh` 显示内置刷新操作，让用户立即获取新鲜内容。 - **感知主题的服务器请求：** 服务器驱动的 widget 请求现在包含当前系统主题，允许你的后端返回感知浅色或深色的内容。 - **Android widgets 中的自定义字体：** 添加了对在 Android Glance widgets 中渲染自定义字体的支持。 --- ## 🛠 修复 - **图表渲染改进：** 改进了图表尺寸和裁剪，使图表在 widgets 内渲染得更干净。 - **Android widget 预览修复：** 修复了 `VoltraWidgetPreview` 中的文本截断和空白预览问题。 - **Expo 插件可靠性：** 修复了使用 pnpm 和 bun 符号链接 `node_modules` 设置时的 `pod install` 失败。 - **计时器渲染修复（iOS）：** 修复了相对倒计时和秒表计时器中的数字偏移。 - **Live Activity token 处理（iOS）：** 修复了在活动生命周期变化期间发出重复 push-to-start token 事件的问题。 - **图片预加载错误（iOS）：** 修复了错误传播，使图片预加载失败能够被正确报告。 --- ## 🙏 贡献者 感谢所有使此版本成为可能的贡献者： @V3RON @DorianMazur @bartoszboruta @ludwig-pro --- **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v1.2.0...v1.3.1

# ⚡️ Voltra 1.2.0 我很高兴宣布 **Voltra 1.2.0**！此版本为 iOS 引入了强大的新布局引擎、增强的 Expo 支持，以及对 widgets 和媒体的开发者控制方面的重大改进。 --- ## 💎 亮点 ### 🍱 Flexbox（iOS） 我通过 `Voltra.View` 引入了一个新的布局系统，将 React Native 风格的 Flexbox 能力直接带入你的视图。这完全是可选启用的；`VStack` 和 `HStack` 继续使用标准 SwiftUI 布局，但当你需要复杂的对齐、换行或间距控制时，`Voltra.View` 现在是你最好的朋友。 支持的属性包括：`flexDirection`、`justifyContent`、`alignItems`、`gap`、`flex` 等。 > ⚠️ **注意：** Flexbox 支持目前是**实验性**的，仍在进行中。某些功能（例如绝对定位）尚缺失，但会在即将发布的版本中添加。如果你遇到任何边缘情况，请不要犹豫，提交 issue 报告；你的反馈有助于我让它变得坚如磐石。 ### 📍 相对和绝对定位（iOS） 你现在可以在布局中混合使用**相对**和**绝对**定位。这解锁了更灵活的设计模式和叠加能力，而无需与布局系统对抗。 ### 🖼️ 可自定义的图片回退（iOS 和 Android） 告别默认占位符。你现在可以提供自定义视图，在图片加载失败时渲染，确保即使网络不可用，你的 UI 也能保持一致和品牌化。 ### 🔌 Expo Config Plugin 和 EAS Expo 插件已完全重构，以确保与 **EAS（Expo Application Services）** 无缝集成。在云端构建由 Voltra 驱动的应用现在更加顺畅和可靠。 ### 🎛️ 新 API：`getActiveWidgets`（iOS 和 Android） 你现在可以使用 `Voltra.getActiveWidgets()` 以编程方式查询当前哪些 widgets 处于活动状态。这非常适合在你的逻辑中直接响应 widget 状态或调试活动实例。 --- ## ✨ 改进和修复 - **计时器重写（iOS）：** Timer 组件已从头重建，并考虑了布局约束，从而实现更可靠的渲染。 - **文本和堆栈对齐（iOS）：** 修复了文本和堆栈组件中的各种对齐边缘情况。 - **行高（iOS）：** 为 `VoltraTextStyle` 添加了 `lineHeight` 支持，以完全控制垂直文本节奏。 - **进度标签（iOS）：** Linear 和 Circular Progress Views 现在支持 `currentValueLabel`，允许直接在指示器上显示值。 - **Widget 图标（iOS）：** 修复了 widget 扩展构建设置中的应用图标继承。 - **时间线修剪（iOS）：** 更新了逻辑，以确保在修剪时保留*最近的过去*时间线条目，防止数据缺口。 --- ## 🙏 贡献者 感谢所有使此版本成为可能的贡献者： @alex-vance @bartoszboruta @chukwumaokere @V3RON --- **完整变更日志**：https://github.com/callstackincubator/voltra/compare/v1.1.2...v1.2.0

# 发布说明 - v1.1.1 **发布日期：** 2026 年 1 月 28 日 **上一版本：** v1.1.0（2026 年 1 月 28 日） ## 🐛 Bug 修复 - 恢复了在 Android 重写期间意外覆盖的 ESM 兼容性补丁。

# 发布说明 - v1.1.0 **发布日期：** 2026 年 1 月 28 日 **上一版本：** v1.0.1（2026 年 1 月 16 日） ## ✨ 功能 ### Android 支持 - **完整的 Android widget 支持**（#45） - 完整的 Android widgets 实现 - Android 代码库位于 `voltra/android`，包含 `voltra/android/client` 和 `voltra/android/server` 子目录 - 为 iOS 和 Android 平台分别提供文档页面 ### iOS 增强 - **iOS Link 组件**（#47） - 新的 iOS `Link` 组件，可创建在按下时打开指定 URL 的自定义按钮 - **iOS 18+ 的补充活动系列支持**（#13） - 支持 iOS 18 补充活动系列 - 允许从单个配置生成多个活动变体 - **Widget 调度**（#19） - 调度多个 widget 状态以在不同时间自动显示 - 非常适合天气预报、日历事件或任何需要在一天中更改内容的应用 - 自动清理孤立的 widget 数据和过期时间线条目的 UserDefaults - 对超过 50KB 的 payload 和超过 100KB 的时间线发出大小验证警告 - **自定义字体支持**（#9） - 类似 expo-font 的自定义字体加载 API - 基于 expo-font 基础 - **可配置的 widget 扩展 target 名称**（#33） - `ConfigPluginProps` 中可选的 `targetName` prop，用于自定义 widget 扩展 target 名称 - **Timer 组件增强**（#22） - 为 `Voltra.Timer` 组件添加了 `showHours` prop 支持 - 允许控制当持续时间超过 60 分钟时计时器是否显示小时 - **Group identifier 改进**（#10） - 使 group identifier 真正可选，如文档所述 ## 🐛 Bug 修复 - **ESM 模块兼容性**（#30） - 修复了导致 EAS 构建期间构建失败的 ESM 模块兼容性问题 - **使用 && 运算符的可选 JSX 元素**（#26） - 修复了布尔值处理以匹配 React Native 的行为 - 布尔值现在在非 Text 组件中被忽略，从而支持 `{condition && }` 等模式 - 在 Text 组件中，布尔值渲染为空字符串（与 React Native 匹配） ## 🙏 贡献者 感谢所有使此版本成为可能的贡献者： - @tarikfp - ESM 模块兼容性修复（#30）、可配置 targetName 功能（#33）和 iOS 26 SDK 文档（#34） - @mrevanzak - 补充活动系列支持（#13）和 Timer showHours prop（#22） - @lukebrandonfarrell - README 链接更新（#44） - @bartoszboruta - Token 监听器文档修复（#40）

## 变更内容 * fix：widgets 未使用样式，由 @V3RON 提交于 https://github.com/callstackincubator/voltra/pull/18 **变更日志**：https://github.com/callstackincubator/voltra/compare/v1.0.0...v1.0.1

Voltra 来了，有了它，就不再需要接触 Swift 了。 在其文档站点了解更多关于 Voltra 的信息：https://www.use-voltra.dev/ 一如既往，欢迎随意试用、玩得开心，并报告你遇到的任何问题。 编码愉快！