我是 uni-app 老用户了，从最早十几年前的版本就开始用。以前学 uni-app，手册虽然短，但完整、稳定、前后一致。我可以花一个月边角料时间看一遍，再花一个月看第二遍，心里就有底了，然后写项目遇到问题一查手册就能解决。这套方法我用了很多年，从来没出过问题。
但 uni-app x 真的让我卡住了。
问题一：文档前后矛盾，不知道该信谁。
CSS 文档写：“App 原生页面默认不能滚动，必须用 scroll-view 包起来。”
页面介绍文档写：“蒸汽模式下页面默认可滚动，建议去掉 #ifdef APP 包裹 scroll-view 的代码。”
一个说必须包，一个说建议删掉。我到底听谁的？
onPageScroll 也是。CSS 文档说“页面根节点不是 scroll-view 就不生效”，但蒸汽模式的更新日志里又在修复 onPageScroll。既然蒸汽模式页面默认可滚，它到底依不依赖 scroll-view？文档没说。
问题二：文档以 VDOM 为主体，蒸汽模式差异全靠猜。
CSS 的 flex-shrink 默认值、overflow 支持范围、样式隔离策略，全都没有标注“这是 VDOM 的规则”还是“蒸汽模式也适用”。我只能靠猜。今天记的笔记，明天可能发现是错的。
我本来想把 CSS、API、组件认真过一遍，做点笔记。但现在不敢做了。不知道哪些是 VDOM 的，哪些蒸汽模式也适用，哪些已经废弃。学了可能白学。
问题三：UTS 和 JS/TS 的边界不明确。
以前手册全是 UTS，我花了很多时间学。后来官方说蒸汽模式可以用 JS/TS 了，我很高兴，以为终于不用死抠 UTS 了。但手册没有告诉我：哪些地方必须用 UTS？哪些地方可以用 JS/TS？特殊类型什么时候出现？
我担心写到一半突然被告知“这里必须用 UTS”，那就等于踩坑了。
我的真实感受：
我不是不想学，我是不敢学。手册不可靠，我心里就没底，就不敢写项目。
我知道官方在快速迭代，文档跟不上可以理解。但至少不要让同一份文档里前后打架。这真的让人很崩溃。
建议：
既然公司现在主推蒸汽模式，HBuilderX 新建项目都默认蒸汽了，手册就应该围绕蒸汽模式来写。VDOM 和 UTS 作为特殊说明标注即可。
具体来说：
- 出一份单独的蒸汽模式手册，或者把现有手册全面适配蒸汽模式，让蒸汽模式成为叙述主体。
- 凡是和蒸汽模式冲突的段落，直接标注“此规则仅适用于 VDOM，蒸汽模式请忽略”或“蒸汽模式行为为……”。
- 明确 UTS 和 JS/TS 的使用边界，告诉开发者什么时候必须用 UTS。
- 兼容性表格的 Vapor 列要更显眼，正文和表格要互相呼应。
结尾：
我是真的想把 uni-app x 用起来，也愿意等。但希望官方能尽快处理文档问题，不要让开发者靠猜来学习。
如果你也遇到同样的问题，帮忙顶一下，让官方看到。谢谢。
0 个回复