opensource-ecommerce-mobile-app 实战指南将 Bagisto 商城快速封装为 Flutter 移动电商 App【免费下载链接】opensource-ecommerce-mobile-appThis open-source mobile ecommerce app seamlessly transforms your Bagisto store into a powerful mobile platform, providing real-time synchronization of products and categories.项目地址: https://gitcode.com/gh_mirrors/op/opensource-ecommerce-mobile-app导读本文是一份围绕 Bagisto 官方开源移动电商 App仓库根目录README.md编写的一站式部署与配置指南。该 App 基于 Flutter 构建通过 GraphQL 与 BagistoLaravel后端实时同步商品与分类覆盖首页、搜索、多类型商品、暗色模式、推送通知、优惠券、访客结账、心愿单、订单与评价等完整移动购物链路。读完本文你将掌握从环境准备、克隆编译、服务端参数对接到主题换色、推送通知、启动页与多语言本地化的全部实操方法并理解其底层实现API 常量、GraphQL 客户端、主题令牌、启动引导等。一、项目概览一个 App 打通 Bagisto 全链路opensource-ecommerce-mobile-app 是 Bagisto 生态的官方移动端解决方案。它的核心价值在于实时同步商品与分类数据通过 Bagisto 的 GraphQL API 实时拉取后端改动即时反映到移动端开箱即用基于成熟的 Laravel/Bagisto 技术栈封装无需为移动端单独开发业务接口只需正确配置bagistoEndpoint与storefrontKey覆盖完整电商闭环首页、分类浏览、商品详情含可配置/组合/预订/分组商品、购物车、优惠券、访客结账、订单追踪、商品评价、心愿单、最近浏览、图片搜索与语音搜索等。从仓库目录结构可以印证这一点lib/features 下按account、auth、cart、category、checkout、home、product、search、splash划分业务域每个域遵循 data模型/仓库→ presentationbloc/页面/组件的清晰分层lib/core 则沉淀了 GraphQL 客户端、主题、本地化、货币、通知、导航等跨域能力。交互式首页与搜索上图为 App 首页与搜索功能界面示意图片来源Docs/features_images。已支持的功能矩阵首页与搜索交互式首页、分类轮播、商品卡片、语音搜索、基于相机/相册的图片搜索由 lib/features/search 下的 ML Kit 视觉服务与图片识别仓库支撑全类型商品简单商品、可配置商品、组合bundle、分组grouped、预订/票务等对应 lib/features/product/presentation/widgets 下的各分区组件暗色模式与推送通知主题由 lib/core/theme/theme_cubit.dart 管理通知由 lib/core/notifications 的 FCM 服务实现折扣优惠券与访客结账结账流程位于 lib/features/checkout心愿单与商品分类心愿单状态由 lib/core/wishlist/wishlist_cubit.dart 统一维护订单详情与商品评价位于 lib/features/account含订单、发票、收货与发货明细、评价等页面。二、环境准备与版本要求在开始安装前请确认开发环境满足以下版本要求以仓库README.md为准依赖版本要求Bagisto后端v2.0.0 或更高Android StudioMeerkat | 2024.3.2Flutter3.38.9Dart3.10.8Xcode26.3Swift6.1同时仓库要求先安装并正确配置Bagisto API 模块bagisto-api移动端所有数据均经由该模块暴露的 GraphQL 端点获取。重要前提建议先运行一个简单的 Flutter Hello World 程序验证开发环境已正确搭建再继续本项目避免将环境问题与项目问题混淆。仓库本身的运行约束还可以在 pubspec.yaml 中看到environment: sdk: ^3.10.8即 Dart SDK 需为 3.10.8 及以上。依赖方面值得关注的核心库包括graphql_flutterGraphQL 通信、flutter_bloc状态管理、firebase_core/firebase_messaging/flutter_local_notifications推送、google_mlkit_image_labeling/google_mlkit_object_detection端侧图片识别、dio/http网络、shared_preferences本地存储等完整清单见 pubspec.yaml。最低支持系统版本AndroidAPI 22iOS15.5三、安装步骤1. 克隆仓库打开终端或命令提示符进入希望保存项目的目录执行git clone https://github.com/bagisto/opensource-ecommerce-mobile-app.git如需通过镜像克隆可使用https://gitcode.com/gh_mirrors/op/opensource-ecommerce-mobile-app。2. 安装依赖进入项目目录后运行cd opensource-ecommerce-mobile-app flutter pub getflutter pub get会根据 pubspec.yaml 拉取全部依赖其中generate: true表示本地化代码由 ARB 文件自动生成详见后文「多语言配置」。3. 连接设备或模拟器真机开启 USB 调试用数据线连接电脑模拟器用 IDE 或命令行工具启动 Android/iOS 模拟器。4. 运行项目flutter run该命令会完成构建、安装并启动 App。首次启动时 lib/main.dart 的main()会依次执行Firebase 初始化 → Hive 缓存初始化 →ChannelBootstrapService从 Bagisto 拉取渠道/本地化信息 → FCM 服务初始化 → 渲染SplashScreen并进入主界面lib/features/splash/presentation/splash_screen.dart 中 3 秒后跳转至 lib/features/home/presentation/pages/main_shell.dart 主框架。四、服务端对接配置第一步必做App 与 Bagisto 后端的所有通信都建立在两个关键常量之上配置文件位于 lib/core/constants/api_constants.dart。核心常量/// Bagisto API endpoint const String bagistoEndpoint https://your-bagisto-domain.com/graphql; /// Storefront key for Bagisto API const String storefrontKey your_storefront_key_here; /// Default channel code used by request headers. const String channelCode default; /// Default Bagisto channel ID used during app bootstrap. const int channelId 1; /// Company name const String companyName Your Company Name;各字段说明常量类型是否必填说明bagistoEndpointStringURL是所有 GraphQL 请求的端点地址形如https://bagisto.yourdomain.com/graphqlstorefrontKeyString是标识商店前台storefront的 API 密钥在 Bagisto 后台「设置 → 渠道Settings → Channels」中获取channelCodeString否请求头X-CHANNEL使用的默认渠道代码channelIdint否应用启动引导阶段使用的默认 Bagisto 渠道 IDcompanyNameString否公司名称仅作元数据使用配置步骤打开 lib/core/constants/api_constants.dart将bagistoEndpoint替换为你的 Bagisto GraphQL 端点将storefrontKey替换为 Bagisto 后台渠道页签中分配的密钥按需更新companyName与渠道相关的channelCode/channelId如与你的渠道不一致也一并修改。关于服务端配置的补充说明可参考 Docs/ServerConfig.md。五、GraphQL 客户端底层通信机制App 与后端的通信由 lib/core/graphql/graphql_client.dart 统一管理理解它能帮助你排查配置与网络问题。客户端能力一览能力配置HTTP 超时连接与接收均 60 秒TimeoutHttpClient见 graphql_client.dart认证携带Bearertoken 的AuthLink仅登录用户使用动态请求头X-STOREFRONT-KEY、X-LOCALE、X-CURRENCY、X-CHANNEL缓存HiveStore异常时回退InMemoryStore日志Debug 模式下输出请求/响应与耗时LoggingHttpClient拉取策略networkOnly查询绕过缓存始终取最新数据两类客户端标准客户端GraphQLClientProvider.client供游客/未登录用户使用见 graphql_client.dart认证客户端GraphQLClientProvider.authenticatedClient(accessToken)供已登录用户使用自动拼接Bearer token请求头见 graphql_client.dart。所有请求头默认包含Content-Type: application/json与X-STOREFRONT-KEY: {storefrontKey}来自 api_constants.dart 的storefrontKeyLoggingHttpClient还会从SharedPreferences动态读取本地化与货币偏好附加X-LOCALE、X-CURRENCY、X-CHANNEL头见 graphql_client.dart。缓存清理退出登录时需要清空缓存防止用户数据残留await GraphQLClientProvider.clearCache();该方法重置HiveStore实现见 graphql_client.dart。在 lib/main.dart 中切换语言或货币时也会调用clearCache()并刷新首页、分类与购物车数据。六、主题与颜色配置App 采用 Material 3 设计规范支持明暗双主题全部设计令牌集中在 lib/core/theme/app_theme.dart。主色修改在AppColors类中定位主色并替换class AppColors { // Primary Colors static const Color primary500 Color(0xFFFF6900); // 主色橙色 static const Color primary600 Color(0xFFF54900); // 按压态深色变体 // Neutral Colors - Light Theme static const Color neutral50 Color(0xFFFAFAFA); static const Color neutral100 Color(0xFFF5F5F5); static const Color neutral200 Color(0xFFE5E5E5); static const Color neutral300 Color(0xFFD4D4D4); static const Color neutral400 Color(0xFFA1A1A1); static const Color neutral500 Color(0xFF737373); static const Color neutral600 Color(0xFF525252); static const Color neutral700 Color(0xFF404040); static const Color neutral800 Color(0xFF262626); static const Color neutral900 Color(0xFF171717); // Status Colors static const Color successGreen Color(0xFF00A63E); static const Color success50 Color(0xFFF0FDF4); static const Color success500 Color(0xFF00C950); static const Color success700 Color(0xFF008236); // Process / Info Colors static const Color process600 Color(0xFF155DFC); static const Color process700 Color(0xFF1447E6); // Static Colors static const Color white Color(0xFFFFFFFF); static const Color black Color(0xFF000000); }换色步骤将primary500的0xFFFF6900替换为你期望的主色将primary600调整为同一主色稍深的变体用于按压等交互状态。明暗主题AppTheme类app_theme.dart提供两套ThemeData浅色主题白底 neutral900文字深色主题neutral900底 neutral200文字。两套主题均启用 Material3、使用 Roboto 字体并对 AppBar、底部导航栏、卡片圆角 12px等组件做了统一设计。主题切换状态由 lib/core/theme/theme_cubit.dart 管理并持久化到本地。更详细的颜色体系说明参见 Docs/ColorSetUp.md。七、推送通知Firebase FCM配置推送通知依赖 Firebase Cloud Messaging需要将仓库中的占位配置文件替换为你的 Firebase 项目配置当前文件均为 dummy 值不替换则推送不可用。Android文件android/app/google-services.json打开 Firebase 控制台 → 项目设置 → 常规点击「添加应用」→ Android下载google-services.json替换 android/app/ 下的同名文件。iOS文件ios/Runner/GoogleService-Info.plistFirebase 控制台 → 项目设置 → 常规点击「添加应用」→ iOS下载GoogleService-Info.plist替换 ios/Runner/ 下的同名文件。底层接入点从源码看推送链路为lib/core/notifications/firebase_service.dart负责Firebase.initializeApp()若 Firebase 不可用会优雅降级App 继续运行但无推送lib/core/notifications/fcm_service.dart负责前台/后台消息处理、设备 Token 获取与本地通知展示lib/core/notifications/device_token_service.dart设备 Token 的上报与持久化lib/main.dart应用启动时按「Firebase → FCM → Token」的顺序完成初始化并注册后台消息处理器。main()中的测试通知日志还给出了服务端推送负载data 字段的约定格式例如分类跳转notificationType: category、categoryId、categoryName商品跳转notificationType: product、productUrlKey或productId、productName订单跳转notificationType: order或type: order_status、orderId、orderNumber。点击通知后lib/main.dart 的_navigateFromNotification/_navigateFromNotificationData会根据这些字段深链到分类页、商品详情页或订单详情页订单端点需要认证代码中会在游客客户端不可用时自动回退到认证客户端。更完整的接入细节含 APNs 证书、前后台消息、深链等可参阅 Docs/Android_Firebase_Setup.md、Docs/iOS_Firebase_Setup.md 与 Docs/Firebase_Notifications_Guide.md。八、应用名称、启动页与应用图标应用名称Android编辑 android/app/src/main/AndroidManifest.xml修改application标签的android:label属性当前默认值为Mobikul Bagisto Laravel Appapplication android:labelYour App Name android:name${applicationName} android:iconmipmap/ic_launcheriOS打开 Xcode在 General → Identity 中修改 Display Name或直接编辑 ios/Runner/Info.plist 中的CFBundleDisplayName键值。启动页Splash Screen以图片作为启动页将图片放到assets/images/splash.png。无需修改任何常量——lib/features/splash/presentation/splash_screen.dart 会直接加载assets/images/splash.png全屏展示 3 秒后进入主界面图片资源目录在 pubspec.yaml 中已声明为assets/images/。Android 原生启动背景可调整 android/app/src/main/res/drawable-v21/launch_background.xml 的背景图层iOS 原生启动图替换 ios/Runner/Assets.xcassets/LaunchImage.imageset/ 下的 1x/2x/3x 三张图同时更新 ios/Runner/Assets.xcassets/splash.imageset/ 供 Flutter 启动页使用。应用图标Android用 Android Studio 打开android文件夹右键app→ New → Image Asset导入自定义图标图标资源位于 android/app/src/main/res/mipmap-xxxhdpi/iOS替换 ios/Runner/Assets.xcassets/AppIcon.appiconset/ 下的图标文件推荐在 Xcode 的 AppIcon 模板中按规范尺寸生成。九、多语言与本地化配置App 内置完整的 Flutter 本地化支持并已接入 Bagisto 的 locale 数据。当前支持的语言ar阿拉伯语、de德语、en英语、es西班牙语、fr法语、it意大利语、nl荷兰语、ru俄语、tr土耳其语、uk乌克兰语。这些 locale 由 lib/l10n/ 下的 ARB 文件自动生成。核心文件与职责用途文件启用 Flutter 本地化生成pubspec.yamlgenerate: true本地化生成器配置l10n.yaml基础翻译模板lib/l10n/app_en.arb生成的 supportedLocales 与委托lib/l10n/app_localizations.dart将 locale 应用到 MaterialApplib/main.dart保存所选语言lib/core/locale/locale_cubit.dart启动时从 Bagisto 引导渠道语言lib/core/channel/channel_bootstrap_service.dart将语言写入 GraphQL 请求头lib/core/graphql/graphql_client.dart语言选择 UIlib/features/account/presentation/pages/preferences_bottom_sheet.dart工作流程启动时 ChannelBootstrapService 从 Bagisto 拉取渠道支持的语言与默认语言选中的语言代码由 LocaleCubit 存入 SharedPreferenceslib/main.dart 结合AppLocalizations.delegate与AppLocalizations.supportedLocales应用该语言用户在设置界面切换语言后App 更新 locale、清空 GraphQL 缓存并刷新首页/分类/购物车所有 GraphQL 请求携带X-LOCALE头Bagisto 据此返回对应语言的翻译内容。注意当前实现基于en、fr、ar这类简单语言代码。若需要pt_BR、en_GB这类带区域后缀的代码需修改语言存储与比较逻辑。新增语言的完整步骤参见 Docs/LanguageConfiguration.md。十、运行时权限配置为保证图片搜索、语音搜索等功能的完整可用需配置以下权限。Androidandroid/app/src/main/AndroidManifest.xml!-- 图片搜索所需的相机 -- uses-feature android:nameandroid.hardware.camera android:requiredfalse / uses-permission android:nameandroid.permission.CAMERA/ uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE/ uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE/ uses-permission android:nameandroid.permission.READ_MEDIA_IMAGES/ !-- 语音识别所需的麦克风 -- uses-permission android:nameandroid.permission.RECORD_AUDIO/ !-- 网络访问 -- uses-permission android:nameandroid.permission.INTERNET/iOSios/Runner/Info.plist!-- 图片搜索相机 -- keyNSCameraUsageDescription/key stringThis app needs camera access to capture photos for image-based product search./string !-- 语音搜索麦克风 -- keyNSMicrophoneUsageDescription/key stringThis app needs microphone access for voice search functionality./string !-- 相册访问 -- keyNSPhotoLibraryUsageDescription/key stringThis app needs access to your photo library to select images for product search./string keyNSPhotoLibraryAddOnlyUsageDescription/key stringThis app needs permission to save photos from your camera./string !-- 语音识别 -- keyNSSpeechRecognitionUsageDescription/key stringThis app uses speech recognition for voice search./string十一、配置清单速查表配置项文件路径API 端点 / Storefront Keylib/core/constants/api_constants.dart主题 / 颜色lib/core/theme/app_theme.dartAndroid 应用名称android/app/src/main/AndroidManifest.xmliOS 应用名称ios/Runner/Info.plistAndroid 图标android/app/src/main/res/mipmap-xxxhdpi/iOS 图标ios/Runner/Assets.xcassets/AppIcon.appiconset/Android 启动背景android/app/src/main/res/drawable-v21/launch_background.xmliOS 启动图ios/Runner/Assets.xcassets/LaunchImage.imageset/Flutter 启动图assets/images/splash.png见 lib/features/splash/presentation/splash_screen.dartAndroid Firebase 配置android/app/google-services.jsoniOS Firebase 配置ios/Runner/GoogleService-Info.plist本地化 ARB 文件lib/l10n/本地化生成器配置l10n.yaml语言状态管理lib/core/locale/locale_cubit.dart渠道语言引导lib/core/channel/channel_bootstrap_service.dartGraphQL 客户端lib/core/graphql/graphql_client.dartAndroid 权限android/app/src/main/AndroidManifest.xmliOS 权限ios/Runner/Info.plist依赖清单pubspec.yaml十二、常见问题与排障思路App 启动后无数据优先检查 api_constants.dart 中bagistoEndpoint是否可访问、storefrontKey是否与 Bagisto 后台渠道一致推送收不到确认已替换 android/app/google-services.json 与 ios/Runner/GoogleService-Info.plist仓库内为占位值并按 Docs/Android_Firebase_Setup.md、Docs/iOS_Firebase_Setup.md 完成 APNs/控制台配置想排查接口请求在 Debug 模式下LoggingHttpClient会输出每个 GraphQL 请求的名称、URL、耗时与状态码graphql_client.dart也可用 Flutter DevTools 的网络面板观察图片搜索/语音不可用核对第十节的系统权限是否已声明并确认设备已授予运行时权限语言切换后内容未更新切换语言会自动清理 GraphQL 缓存并刷新数据若仍异常可手动调用GraphQLClientProvider.clearCache()验证。更完整的安装指引见 Docs/installationGuide.md通用配置总览见 Docs/ConfigGuide.md服务端细节见 Docs/ServerConfig.md占位图替换方法见 Docs/PlaceholderSetup.md。结语从环境搭建、flutter run一键启动到 API 端点、主题令牌、Firebase 推送、多语言与权限的逐一配置opensource-ecommerce-mobile-app 提供了一条从 Bagisto 后端直达移动端的成熟路径。其配置面虽然分散在常量文件、原生清单与主题类中但核心收敛点清晰服务端看 api_constants.dart 与 graphql_client.dart界面定制看 app_theme.dart原生能力看 AndroidManifest / Info.plist。掌握本文的配置脉络后你便可以在数小时内将自有 Bagisto 商店封装为功能完备的移动电商 App。【免费下载链接】opensource-ecommerce-mobile-appThis open-source mobile ecommerce app seamlessly transforms your Bagisto store into a powerful mobile platform, providing real-time synchronization of products and categories.项目地址: https://gitcode.com/gh_mirrors/op/opensource-ecommerce-mobile-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考