uni-app 微信小店组件 store-home 使用指南：属性、兼容性与实战要点-二趣网

uni-app 微信小店组件 store-home 使用指南：属性、兼容性与实战要点

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

store-home 是 uni-app 中用于在微信小程序页面内直接嵌入「微信小店首页」的组件，让开发者无需自建商城页面即可将店铺主页以组件形式挂载到小程序中。本文以仓库文档 docs/component/store-home.md 为主体，结合仓库源码与变更记录，完整讲解其属性、兼容性、获取 appid 的方法、动态绑定注意事项以及与 store-product 组件的配套关系，帮助你快速落地微信小店场景。

store-home 组件是什么

store-home 是 uni-app 面向微信小程序平台提供的开放能力组件，作用是在小程序页面中直接展示微信小店的店铺首页。它与微信「视频号小店 / 微信小店」生态打通，适合需要把店铺流量引入小程序、或在 App 与小程序间做用户导流的业务场景。

从 docs/component/store-home.md 的定义看，该组件本质上是微信小店开放能力的载体，组件通过一个appid属性即可完成店铺绑定，属于"配置即用"型组件，不需要自建商品体系。

兼容性：仅微信小程序平台可用

原文档明确给出了该组件的跨端兼容性矩阵：

| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | x | x | x |

其中4.41为微信小程序平台支持的 uni-app 版本号起点，x表示不支持。这意味着：

store-home仅在微信小程序平台可用，且需要 uni-app 版本 ≥ 4.41；
Web、App-Android、App-iOS、App-HarmonyOS 均不支持，在项目中使用时建议通过条件编译隔离，避免其他平台编译报错或渲染异常。

uni-app 的条件编译注释（详见 docs/uts/conditional.md）是隔离这类平台专属组件的最常用手段，例如：

<!-- #ifdef MP-WEIXIN --> <store-home appid="微信小店appid" /> <!-- #endif -->

这样写可以保证非微信小程序平台不会引入该组件。

属性详解：appid 微信小店ID

store-home 组件目前仅有一个业务属性，完整参数如下（摘自 docs/component/store-home.md）：

| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | appid | string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 小店 appid。获取方式：小店后台 - 店铺管理 - 基础信息 - 账号信息 - 微信小店ID |

appid 的作用

appid是微信小店的唯一标识，store-home 组件渲染时通过它向微信侧请求并渲染对应店铺的首页内容。开发者并不直接持有该 ID 的业务逻辑，只需把后台分配的小店 ID 原样传给组件即可。

如何获取微信小店ID

按原文档指引，获取路径为：

登录微信小店后台；
进入「店铺管理」；
打开「基础信息」；
在「账号信息」中查看「微信小店ID」。

将得到的 ID 作为appid传入组件。注意这里的appid是微信小店的 ID，与小程序自身的 AppID 是两个不同的概念，不要混淆。

使用示例

将 store-home 放入页面 template，并绑定 appid 即可。下面是一个配合条件编译的完整页面写法（基于 uni-app 组件规范与仓库示例页面的通用结构）：

<template> <view> <!-- #ifdef MP-WEIXIN --> <store-home :appid="storeAppid" /> <!-- #endif --> <!-- #ifndef MP-WEIXIN --> <text>store-home 组件仅支持微信小程序平台</text> <!-- #endif --> </view> </template> <script setup lang="uts"> // 从配置或接口获取小店ID，也可以写死为固定值 const storeAppid = ref('微信小店ID') </script>

几点实践建议：

appid可以静态绑定，也可以使用:appid="xxx"动态绑定；
若店铺首页需要跟随用户或运营策略变化，可在页面逻辑中动态更新storeAppid；
由于该组件只在微信小程序端生效，务必配合条件编译，保证其他平台构建产物干净。

动态绑定 appid 的注意事项

仓库 CHANGELOG.md 记录了相关历史问题：

微信小程序平台修复 store-home 组件动态绑定 appid 不生效的 Bug

也就是说，早期版本中:appid="..."这种动态绑定方式存在不生效的缺陷，该问题已在后续版本修复。如果你使用的 uni-app 版本较旧，遇到"组件没有展示对应店铺"的情况，可优先检查是否踩中了动态绑定 appid 不生效的问题，并考虑升级版本或改用静态绑定。

与 store-product 组件配套使用

同属微信小店开放能力体系的还有商品组件 store-product，其文档见 docs/component/store-product.md。两者关系为：

store-home：展示整个小店首页，仅需appid；
store-product：展示单个商品，除appid外还需product-id（商品 id）与可选的product-promotion-link（带货商品跟佣信息）。

store-product 的属性全表如下（引自 docs/component/store-product.md）：

两个组件兼容性完全一致（微信小程序 4.41+），共享同一套appid配置来源，适合在"店铺首页 + 单品直达"的营销组合场景中一起使用。

底层实现佐证：自定义节点与版本演进

从仓库 CHANGELOG.md 可以看到 uni-app 对这两个组件的编译层支持过程：

微信小程序平台修复补充 store-home、store-product 自定义节点

这说明 uni-app 在编译到微信小程序时，需要将store-home/store-product识别并转换为微信侧的自定义节点，才能正确透传属性并渲染。从源码结构看，这类"补充自定义节点"的修复意味着组件支持是随编译器（src 目录下的编译相关代码）逐步完善的——因此使用该组件时，建议将 HBuilderX / uni-app 依赖升级到较新版本，以获得完整的节点支持与 Bug 修复。

全局属性与事件支持

store-home 与其他组件一样，天然继承 uni-app 的组件全局属性与事件体系，相关内容见 docs/component/common.md。常用全局能力包括：

id：组件唯一标识，避免使用uni-、uni.前缀；
class/style：样式类与内联样式，支持动态绑定；
data-*：自定义属性，可在事件回调中通过target/currentTarget获取；
ref：Vue 引用，用于获取组件实例（在小程序端受平台限制，部分能力仅能通过createSelectorQuery等 API 获取）；
@tap、@click、@longpress、@touchstart等全局事件。

在编写使用 store-home 的页面时，如需监听用户点击店铺区域、或通过data-*传递业务参数，可参照 docs/component/common.md 中的全局事件规范。

小结

store-home 是 uni-app 微信小程序平台专属的微信小店首页嵌入组件，核心用法可归纳为三点：

确认平台：仅微信小程序 4.41+ 可用，其他平台需条件编译隔离；
配置 appid：从小店后台「店铺管理 - 基础信息 - 账号信息」获取微信小店ID，静态或动态绑定均可（动态绑定需注意版本 Bug，建议使用新版本）；
组合扩展：搭配 store-product 实现店铺首页 + 单品直达，共享同一套小店 ID。

企业官网建设流程全解析