企业官网建设流程全解析

1. 从一个真实踩坑说起：为什么自定义组件和动画在列表里会翻车

做 uni-app 项目的人，十有八九都会经历这么一个阶段：单页面写得挺顺，一旦开始拆组件、搞列表渲染，问题就扎堆冒出来。我自己接手过一个商品列表页，需求很朴素——每个商品卡片是一个独立组件，点击卡片时图标要有一个旋转展开的动画。听起来简单得不能再简单，结果我在这上面耗了整整一个下午。

第一个坑是组件传值。父页面把商品数据传给子组件，子组件里想改一下显示状态，直接改 props 报错，控制台一片红。第二个坑更隐蔽：我用uni.createAnimation()给每个卡片做动画，单个卡片测试的时候效果丝滑，一旦用v-for渲染成数组，点击任何一个卡片，要么全部一起动，要么干脆纹丝不动。当时我一度怀疑是框架的 bug，后来才明白，这俩问题本质上都是"作用域"和"实例引用"没搞对。

这篇内容就是把这半天的踩坑过程完整复盘一遍。我会从自定义组件的基本结构讲起，把父子传值、兄弟传值、跨级传值这几条链路捋清楚，然后重点拆解uni.createAnimation()在数组渲染场景下失效的根因和三种解法。适合已经能写 uni-app 页面、但一碰到组件化和动画就卡壳的朋友。看完你至少能少走我走过的那些弯路，遇到类似问题能自己定位。

2. 自定义组件到底该怎么拆：先想清楚边界再动手

2.1 什么样的内容值得抽成组件

很多人拆组件是凭感觉的，觉得"这块代码有点长，抽出去吧"。我早期也这样，结果抽出来的组件要么太碎，一个按钮都要单独一个文件，要么太肥，一个组件里塞了半页逻辑。后来我总结了一个判断标准：如果一个 UI 块在项目里出现了两次以上，或者它自身有独立的状态和交互逻辑，那就值得抽成组件。

拿商品卡片举例，它在首页、搜索页、收藏页都会出现，而且每张卡片有自己的展开/收起状态，这就是典型的该抽。反过来，一个纯展示的标题栏，如果全站样式统一、没有交互，那用个公共 class 就够了，没必要为它建一个组件文件。

组件拆分的粒度还跟传值成本有关。组件拆得越细，父子之间的数据传递就越频繁，props 和事件会像蜘蛛网一样缠在一起。我的经验是：一个组件对外暴露的 props 控制在 5 个以内，事件控制在 3 个以内，超过这个数就说明这个组件承担了太多职责，该考虑再拆或者合并了。

2.2 组件目录结构和注册方式的选择

uni-app 里组件的注册分两种：全局注册和局部注册。全局注册在main.js里用Vue.component()挂载，任何页面都能直接用；局部注册是在具体页面里import后写进components选项。

我的建议很明确：通用性极强的组件（比如自定义弹窗、加载指示器）走全局注册，业务相关的组件一律局部注册。原因有两个。一是全局注册的组件会被打进主包，项目大了之后首屏体积会明显变大；二是局部注册能让依赖关系一目了然，你打开一个页面文件，看 import 就知道它用了哪些组件，维护起来清爽得多。

目录上我习惯这样组织：

components/ common/ // 全局通用组件 my-modal.vue my-loading.vue business/ // 业务组件 goods-card.vue order-item.vue

easycom规范也值得提一句。uni-app 支持一种自动引入机制，只要组件放在components/组件名/组件名.vue这个路径下，页面里就能直接用，不用 import 也不用注册。这个特性能省掉大量样板代码，但代价是路径必须严格符合规范，一旦放错位置就找不到组件，而且报错信息不太友好。新手用之前最好先确认自己的目录结构能对上。

2.3 组件通信的三条链路和选型逻辑

组件传值这件事，本质上就三条链路：父传子、子传父、以及跨层级或兄弟之间传值。每条链路都有对应的标准做法，选错了就会写出又臭又长的代码。

父传子用 props，这是最基础的。props 是单向数据流，子组件只能读不能直接改。我见过太多新手在子组件里写this.msg = 'xxx'想改 props，然后被 Vue 的警告刷屏。正确做法是要么在子组件里用 data 复制一份，要么通过事件通知父组件去改。

子传父用$emit触发自定义事件。子组件里this.$emit('change', payload)，父组件里@change="handleChange"接收。这里有个细节：事件名建议用 kebab-case（短横线），因为 HTML 里属性名不区分大小写，用驼峰容易在某些平台出问题。

跨级和兄弟传值，小项目用uni.$emit/uni.$on这种全局事件总线就够了，大项目建议上 Vuex 或 Pinia。事件总线的坑在于：页面销毁时一定要记得uni.$off取消监听，否则会内存泄漏，而且下次进页面会触发多次回调，这个 bug 特别隐蔽，我调过好几次才养成习惯。

3. 组件传值实战：把商品卡片这个场景做透

3.1 父传子：props 的定义、校验和默认值

先看父页面怎么用子组件。假设我们有个商品列表页，数据从接口拿到后存在goodsList里：

<template> <view class="page"> <goods-card v-for="(item, index) in goodsList" :key="item.id" :goods="item" :index="index" @toggle="onCardToggle" /> </view> </template> <script> import GoodsCard from '@/components/business/goods-card.vue' export default { components: { GoodsCard }, data() { return { goodsList: [] } }, methods: { onCardToggle(payload) { console.log('卡片状态变化', payload) } } } </script>

子组件这边，props 的定义我强烈建议写完整对象形式，而不是数组形式：

<script> export default { name: 'GoodsCard', props: { goods: { type: Object, required: true, default: () => ({}) }, index: { type: Number, default: 0 } } } </script>

为什么要写这么细？因为数组形式的 props 没有任何类型校验，父组件传个字符串进来你也不知道，等到用的时候才报错，排查成本很高。对象形式能明确类型、是否必填、默认值，相当于给组件加了一层文档。特别是对象和数组类型的默认值，必须用工厂函数返回，直接写default: {}会导致所有实例共享同一个对象引用，一个组件改了数据，其他组件跟着变，这个坑非常经典。

3.2 子传父：事件命名和参数设计

子组件里点击卡片要通知父组件，用$emit：

<template> <view class="card" @click="handleClick"> <text>{{ goods.name }}</text> <view class="icon" :animation="animationData" @click.stop="toggleIcon"> <text>箭头</text> </view> </view> </template> <script> export default { name: 'GoodsCard', props: { goods: { type: Object, required: true }, index: { type: Number, default: 0 } }, data() { return { expanded: false, animationData: {} } }, methods: { handleClick() { this.$emit('card-click', { id: this.goods.id, index: this.index }) }, toggleIcon() { this.expanded = !this.expanded this.$emit('toggle', { id: this.goods.id, expanded: this.expanded }) } } } </script>

这里有个设计上的取舍：事件参数到底传什么？我的习惯是传一个对象，把相关字段都包进去，而不是传多个平铺参数。原因是以后要加字段的时候，父组件的接收函数不用改签名，兼容性更好。另外事件名我用的是card-click和toggle，短横线风格，跨平台更稳。

还有一个细节值得说：@click.stop里的.stop修饰符。因为图标在卡片内部，点击图标会冒泡触发卡片的点击事件，加上.stop才能阻止冒泡。这个在列表场景里特别重要，不然点一下图标会同时触发两个事件，逻辑就乱了。

3.3 跨级传值：事件总线的正确打开方式

有些场景父子关系隔了好几层，比如页面 → 列表容器 → 卡片 → 卡片内的按钮，按钮要通知页面做某件事。一层层$emit传上去太累，这时候用全局事件总线：

// 发送方（深层子组件） uni.$emit('cart-add', { goodsId: 123, count: 1 }) // 接收方（页面） onLoad() { uni.$on('cart-add', this.handleCartAdd) }, onUnload() { uni.$off('cart-add', this.handleCartAdd) }, methods: { handleCartAdd(payload) { console.log('加入购物车', payload) } }

注意：uni.$off一定要在onUnload里调用，而且最好带上具体的事件名和回调函数。如果只写uni.$off('cart-add')会把该事件的所有监听都清掉，万一别处也监听了同一个事件，就被误伤了。

事件总线虽然方便，但它把组件之间的依赖关系藏起来了，代码读起来不知道谁发的谁收的。所以我的原则是：能用 props 和 emit 解决的，绝不用事件总线。只有在跨层级且关系确实松散的时候才用它。

4. uni.createAnimation() 在数组渲染中失效的根因剖析

4.1 先搞懂 createAnimation 的工作机制

要理解为什么数组渲染会失效，得先明白uni.createAnimation()到底干了什么。它返回一个动画实例，你在实例上链式调用translate、rotate、opacity等方法，最后调step()提交，再通过export()把动画数据导出来，赋值给模板里绑定的:animation属性。

const animation = uni.createAnimation({ duration: 300, timingFunction: 'ease' }) animation.rotate(90).step() this.animationData = animation.export()

关键点在于：一个动画实例对应一个:animation绑定。动画数据是通过export()导出的一个对象，这个对象里记录了当前动画的状态。当你把它赋值给某个元素的:animation时，这个元素就会按照数据执行动画。

问题就出在这里。在v-for渲染的列表里，如果你只创建了一个动画实例，然后把它export()出来的数据赋值给一个公共的 data 字段，那么所有卡片绑定的都是同一个数据源。你点击某一张卡片，改的是这个公共数据，所有卡片都会跟着变。这就是"点一个全动"的原因。

4.2 为什么"不动"比"全动"更常见

更常见的情况是"点了没反应"。这通常是因为动画实例在循环里被反复创建，或者export()的时机不对。

我见过一种典型写法：

// 错误示范 onShow() { this.goodsList.forEach((item, index) => { const animation = uni.createAnimation() // ... 这里创建了一堆实例，但没地方存 }) }

在循环里创建实例，但每个实例创建完就丢了，没有跟具体的列表项关联起来。等到点击的时候，根本找不到对应的实例，自然没反应。

还有一种情况是export()调用后没有触发视图更新。因为export()返回的是一个新对象，如果你赋值的方式不对，Vue 检测不到变化。比如直接给数组的某一项赋值this.list[index].animationData = data，在 Vue 2 里这种直接改数组项属性的方式是不响应式的，得用this.$set。

4.3 根因总结：实例与数据的一对一关系被破坏

把上面这些现象归纳一下，核心就一句话：数组渲染要求每个列表项有独立的动画实例和独立的动画数据字段，而很多人的写法是共享一个实例或一个数据字段，破坏了这种一对一关系。

具体表现有三种：

理解了根因，解法就清晰了：要么给每个列表项准备独立的动画数据字段，要么换一种不依赖实例绑定的动画方案。

5. 三种可落地的解决方案与选型建议

5.1 方案一：为每个列表项维护独立的动画数据

这是最贴合createAnimation原生用法的方案。思路是在数据里给每个列表项加一个animationData字段，点击时只更新对应项的数据。

<template> <view class="page"> <view v-for="(item, index) in goodsList" :key="item.id" class="card" > <text>{{ item.name }}</text> <view class="icon" :animation="item.animationData" @click="toggle(index)"> <text>箭头</text> </view> </view> </view> </template> <script> export default { data() { return { goodsList: [] } }, onLoad() { this.loadData() }, methods: { loadData() { // 模拟接口数据，初始化时为每项加上动画数据字段 const raw = [ { id: 1, name: '商品A' }, { id: 2, name: '商品B' }, { id: 3, name: '商品C' } ] this.goodsList = raw.map(item => ({ ...item, expanded: false, animationData: {} })) }, toggle(index) { const item = this.goodsList[index] const animation = uni.createAnimation({ duration: 300, timingFunction: 'ease' }) item.expanded = !item.expanded if (item.expanded) { animation.rotate(180).step() } else { animation.rotate(0).step() } // 关键：用 $set 保证响应式 this.$set(this.goodsList, index, { ...item, animationData: animation.export() }) } } } </script>

这个方案的关键点有三个。第一，动画数据字段是挂在每个列表项上的，天然隔离。第二，每次点击只操作当前项，其他项不受影响。第三，用$set或者展开运算符重建对象来保证响应式更新。

提示：animation.export()每次调用都会清空之前的动画队列，所以每次点击都要重新创建实例或者重新调用 step。如果你想让动画可逆，记得在同一个实例上根据状态设置不同的旋转角度。

这个方案的优点是逻辑清晰、可控性强，缺点是每个列表项都要多存一个动画数据对象，列表很长时内存占用会上升。列表超过几百项的话，建议配合虚拟列表或者只对可见项做动画。

5.2 方案二：用 CSS 类切换替代 JS 动画

如果你的动画只是简单的旋转、位移、透明度变化，我强烈建议直接用 CSS transition 配合类名切换，完全绕开createAnimation的实例管理问题。

<template> <view class="page"> <view v-for="item in goodsList" :key="item.id" class="card"> <text>{{ item.name }}</text> <view class="icon" :class="{ 'icon-rotated': item.expanded }" @click="toggle(item)" > <text>箭头</text> </view> </view> </view> </template> <style> .icon { transition: transform 0.3s ease; } .icon-rotated { transform: rotate(180deg); } </style>

toggle(item) { item.expanded = !item.expanded }

就这么几行，效果和 JS 动画一模一样，而且性能更好，因为 CSS transform 走的是合成层，不占用主线程。数组渲染的问题根本不存在，因为每个元素的类名是独立的，状态也是独立的。

这个方案我用了很多次，实测下来在 App 端和 H5 端都很稳。唯一需要注意的是，CSS transition 对某些属性（比如height: auto）支持不好，涉及高度变化的动画还是得用 JS 或者max-height技巧。

5.3 方案三：用 wxs 或 renderjs 处理复杂动画

如果动画逻辑特别复杂，比如要根据手指滑动实时计算位移，那 CSS 和createAnimation都不太够用。App 端可以考虑 renderjs，它能在视图层直接操作 DOM，性能接近原生。

不过 renderjs 的学习成本不低，而且只在 App-vue 端生效，H5 和小程序都不支持。除非你的项目就是纯 App 且动画要求极高，否则我不建议一上来就用它。大部分业务场景，方案一和方案二已经绰绰有余。

5.4 三种方案的选型对照

我的实际选择顺序是：先看能不能用 CSS 解决，能就用 CSS；CSS 搞不定的再上独立动画数据；只有极端性能要求才考虑 renderjs。这个顺序能帮你避开 80% 的坑。

6. 常见问题排查速查表与避坑心得

6.1 组件传值高频问题速查

6.2 动画相关的独家避坑技巧

技巧一：动画数据初始化要给空对象。列表项初始化时animationData一定要给{}，不能给null或undefined。某些平台下绑定 null 会导致渲染异常，虽然不报错但动画就是不生效，这个坑我踩过。

技巧二：连续点击要防抖。用户手快的时候会连点，每次点击都创建新实例、执行动画，容易造成动画队列堆积，表现为动画卡顿或者状态错乱。加一个简单的节流：

toggle(index) { if (this.animating) return this.animating = true // ... 执行动画 setTimeout(() => { this.animating = false }, 300) }

技巧三：列表 key 一定要用唯一 id。用 index 当 key 在列表增删时会导致组件复用错乱，动画状态会串到别的项上。这个不是动画特有的问题，但在动画场景下表现特别明显。

技巧四：App 端动画结束后记得重置。有些情况下动画执行完，animationData还保留着最后的状态，下次触发时会有跳变。可以在动画结束后把数据重置一下，或者用animation.step()的配置项控制。

6.3 我个人的组件化经验总结

做了这么多项目，我在组件化上最大的体会是：不要为了组件化而组件化。组件的价值在于复用和隔离，如果一个 UI 块只用一次、逻辑也不复杂，那放在页面里反而更好维护。我见过一些项目，一个页面拆出十几个组件，改一个需求要跳七八个文件，效率反而更低。

传值方面，我的原则是数据往下流，事件往上走，跨级慎用总线。props 和 emit 能覆盖 90% 的场景，剩下的 10% 再考虑其他方案。事件总线虽然方便，但它让数据流向变得不可追踪，调试的时候很痛苦。

动画方面，能用 CSS 就别用 JS。CSS 动画性能好、代码少、跨平台一致，是首选。createAnimation适合那些 CSS 表达不了的复杂场景，但用的时候一定要记住实例和数据的对应关系，数组渲染尤其要注意隔离。

最后说一个心态上的建议。uni-app 的跨平台特性意味着同一段代码在不同端表现可能不一样，遇到问题先别急着怀疑框架，多半是写法上踩了某个平台的坑。多端测试、多看控制台、多查官方文档的兼容性说明，这三件事能帮你省下大量时间。我那个商品列表的动画问题，最后就是用 CSS 方案解决的，代码从三十多行缩到五行，效果还更好。有时候退一步换个思路，比死磕一个 API 要划算得多。