注意事项

uvx-ui 运行在 uni-app x 的原生渲染体系中。遇到只在某个平台出现的问题时，先检查以下约束，再排查组件本身。

工具与版本

使用较新的 HBuilderX 稳定版，并安装 sass/scss 编译插件。
每个组件的平台最低版本可能不同，以组件文档中的兼容性表格为准。
组件库以 Vapor 模式为主要开发目标，非 Vapor 工程通过条件编译兼容，但个别样式能力会有差异。
修改字体、原生插件、条件编译代码或 manifest.json 后，应重新编译，不要只依赖热更新。

页面滚动

App 非 Vapor 模式下页面本身不可滚动，可滚动内容应放在 scroll-view、list-view 或 waterflow 中。

推荐使用 uvx-page 作为页面根容器。它在 App 端使用 scroll-view，在 Web 和小程序端使用普通 view，同时提供主题作用域。

嵌套滚动容器可能产生手势冲突。页面已经使用 uvx-page 时，仅在确实需要独立滚动区域的场景中再嵌套滚动组件。

布局与样式

App 端布局以 Flex 为主，默认主轴方向为纵向；需要横向排列时显式设置 flex-direction: row。
优先使用类选择器。伪元素、复杂选择器和部分 Web 专有 CSS 在 App 端不可用。
文字应放在 text 或文字类组件中，字号、颜色等文字样式直接设置在文字节点上。
App 原生渲染不保证文字样式从父容器继承，不要依赖浏览器中的继承结果。
主题相关颜色优先使用 --uvx-* CSS 变量，避免写死只适合亮色模式的色值。
Web 预览不能替代 App 与小程序真机测试。

UTS 类型

变量在使用前初始化，需要空值时使用 null，不要使用 undefined。
条件表达式必须是布尔值，不使用 JavaScript 的 truthy/falsy 隐式转换。
对象数据优先定义顶层 type，避免依赖 TypeScript 的结构化类型推断。
函数、变量和类型先声明后使用，不依赖声明提升。
平台专用 API 使用条件编译包围，避免影响其他平台编译。

uts

// #ifdef APP-ANDROID
const platformName: string = "Android";
console.log(platformName);
// #endif

组件使用

easycom 组件可以直接使用，无需导入。
非 easycom 自定义组件需要调用公开方法时，按 uni-app x 约定通过组件实例的 $callMethod 调用。
平台开放能力、权限和回调参数以对应平台文档为准。
组件提供属性、CSS 变量或 external class 时，优先使用公开扩展点，不依赖内部节点结构。

全局名称与依赖

uvx-ui 会占用应用全局属性 $uvx，业务代码不要覆盖同名属性。
不要删除插件市场随 uvx-ui 安装的 lime-dayuts 和 uvx-tools 依赖。
项目根目录的三个业务语言包是入口导入项，文件不存在会导致编译失败。

排查顺序

查看控制台中的第一条编译错误，不从连带错误开始处理。
对照组件文档确认平台和 HBuilderX 最低版本。
检查依赖、全局样式、语言包和页面注册是否完整。
清理构建缓存并重新编译目标平台。
在最小页面中只保留问题组件，排除业务样式和嵌套容器影响。

更多基础约束见 uni-app x 官方文档。