常见问题
本指南汇总 BlueOS 应用开发中的常见概念和排错方法。可以根据症状定位黑屏、数据不更新、路由失败和样式异常等问题。
- 已安装 BlueOS Studio。
- 已创建 BlueOS 应用工程。
- 建议先完成构建待办应用，以便理解页面、路由和系统 API 的基本配置。
蓝河和 BlueOS 是什么关系？
Section titled “蓝河和 BlueOS 是什么关系？”蓝河是 vivo 面向智能手表等穿戴设备的操作系统，英文名为 BlueOS。两词指同一平台。产品介绍参见蓝河官网。
蓝河应用用什么开发？
Section titled “蓝河应用用什么开发？”BlueOS 内核基于 Rust。应用侧采用类 Web 开发范式，使用 UI 组件构建页面、使用样式定义视觉效果，并使用 JavaScript 编写业务逻辑。应用支持与 Vue2 相似的模型—视图—视图模型（MVVM）模式，通过数据绑定更新 UI。
页面写在包含 script、template 和 style 的 .ux 文件中，应用配置写在 manifest.json 中。模板语法与 Vue 相似，但运行时不是 Vue，也不提供 document 或 DOM。
蓝河和 HarmonyOS / Wear OS 有什么区别？
Section titled “蓝河和 HarmonyOS / Wear OS 有什么区别？”它们是不同的操作系统和应用平台，不是同一套系统的不同名称。蓝河应用使用 BlueOS Studio、.ux 页面、manifest.json 和 BlueOS API；HarmonyOS 与 Wear OS 各有自己的运行时、开发工具、组件和系统 API。三者的应用包不能直接互装，现有项目通常也不能原样运行；迁移时只能复用不依赖平台的业务思路或部分纯逻辑代码，界面、配置和设备能力需要按目标平台重写。
蓝河能不能用 Vue、npm 包或 DOM？
Section titled “蓝河能不能用 Vue、npm 包或 DOM？”- Vue： 不能直接运行 Vue 应用。BlueOS 的模板和数据绑定与 Vue2 相似，但指令、事件和组件规则不同。
- npm： 可以使用
npm安装工程依赖，也可以评估不依赖浏览器或 Node.js 原生能力的纯 JavaScript 包。不得假设任意 npm 包都能运行，还需控制手表端的应用包体积。 - DOM： 没有浏览器的
document、window、querySelector等 API。界面通过.ux组件和数据绑定更新，设备能力通过@blueos.*API 获取。
迁移网页代码前，先阅读与 Vue2 的差异。
卡片和快捷卡片是一回事吗？
Section titled “卡片和快捷卡片是一回事吗？”不完全是。当前文档中的“卡片”通常指智慧服务卡片，分为包含 JavaScript 逻辑的标准卡和依赖外部数据的轻卡。具体区别参见智慧服务卡片概述。旧文档中的“快捷卡片”是已弃用的旧方案，不应与当前卡片体系混用。新项目应选择标准卡或轻卡。
模拟器预览不出来怎么办？
Section titled “模拟器预览不出来怎么办？”按以下顺序排查：
- 保存全部文件。
- 确认 BlueOS Studio 已完成 安装依赖。
- 选择 重新启动编译。
- 查看编译输出和 DevTools 中的第一条错误。
- 修复编译错误。
- 确认首页和当前页面已配置在
manifest.json的router.entry和router.pages中。 - 确认页面目录名与
router.pages中的键一致。 - 暂时将页面内容缩减为
<text>Hello World</text>。 - 确认基础页面可以显示。
- 逐段恢复事件、数据和样式，定位出现问题的部分。
- 如果只有设备能力没有返回结果，检查模拟器是否支持该能力。
- 对模拟器不支持的能力使用模拟数据或真机验证。
如果预览仍然黑屏、数据不更新或样式异常，请对照下方的开发排错表格。
designWidth 750 和 466 怎么选？
Section titled “designWidth 750 和 466 怎么选？”designWidth 是样式数值的设计基准宽度，不是设备的物理分辨率。新建手表应用建议使用 466，这也是 manifest.json 参考文档中的推荐值。部分样式文档以默认的 750 为基准，因此示例中的尺寸数值更大。
设计稿按照哪个宽度标注，工程就应使用对应的设计基准，并在整个项目中保持一致。如果页面已基于 750 完成，不得只将 manifest.json 改为 466，否则所有 px 尺寸都会按照新基准缩放。此时应继续使用 750，或在改为 466 时同步换算全部尺寸。参见布局与样式中的尺寸基准说明。
新手应该从哪里开始？
Section titled “新手应该从哪里开始？”从快速入门开始，依次完成安装与首个应用和构建待办应用。查询组件属性或 API 字段时，使用侧边栏中的参考文档。
根据症状查找原因，再应用对应的修复方法。
| 症状 | 原因 | 修复方法 |
|---|---|---|
黑屏，日志包含 create_function: value is not an object | 事件绑定表达式中使用了 {{ }} | 改为 onclick="openDetail(item)" |
| 数据更新后界面未变化 | 字段未在 data 中声明，或未通过 $set 添加 | 先声明 data: { title: '' }，再执行 this.title = 'x' |
修改 todos[i].done 后列表未刷新 | 修改嵌套字段未触发更新 | 创建新数组并执行 this.todos = next |
| 文字未显示 | 文案直接写在 <div> 中 | 使用 <text>内容</text> |
router.push 未打开目标页面 | 页面未在 manifest.router.pages 中登记 | 使页面目录名与 pages 的键一致 |
storage 或 fetch 调用失败 | 未声明 features，或未处理 fail | 在 manifest.json 中声明能力，并为每次调用添加 fail |
| 圆角未显示 | 仅设置了 border-radius | 同时设置 border-width 和 border-color，或分别设置四个角的半径 |
| 布局异常或间距未生效 | 使用了 gap、display: block，或 Tailwind 生成了 flex: 1 1 0% | 使用 flex 和子元素 margin；需要时手写 flex: 1 |
for 的变量顺序错误 | 按照 Vue 写成 (item, index) | 改为 (index, item)，将下标放在前面 |
- 参见与 Vue2 的差异理解事件、循环和运行时限制。
- 参见页面结构与应用配置检查路由和
features。 - 参见布局与样式检查尺寸单位和 CSS 支持范围。
- 完成排错后，通过探索更多进入组件、API、智慧服务卡片、表盘和性能文档。