Bagisto Flutter 移动电商应用完整配置指南API 接入、主题定制、启动屏与推送通知【免费下载链接】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本文是 opensource-ecommerce-mobile-app基于 Bagisto 的开源 Flutter 移动电商应用的官方配置指南。它面向需要将该 App 对接到自己 Bagisto 店铺的开发者系统讲解 GraphQL API 接入、品牌主题定制、应用名称、启动屏与图标替换、Firebase 推送通知以及双端权限配置的完整流程。读完本文你将能够仅通过修改少量集中配置文件就把这套移动端店铺无缝接入你的 Bagisto 后端并打上自己的品牌标识。目录API 配置连接你的 Bagisto 店铺主题配置品牌色与明暗主题应用名称配置启动屏配置App 图标配置推送通知服务配置Firebase权限配置配置文件汇总表相关资源API 配置连接你的 Bagisto 店铺配置文件lib/core/constants/api_constants.dart应用与 Bagisto 后端的所有通信都经由 GraphQL 完成而连接信息集中定义在api_constants.dart这一个文件中。仓库当前版本实际包含五个常量除了配置文档列出的三个之外还有两个与渠道Channel相关的常量/// 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;常量默认值作用bagistoEndpointhttps://your-bagisto-domain.com/graphqlBagisto GraphQL 端点所有查询与变更Query/Mutation都发往此 URLstorefrontKeyyour_storefront_key_hereBagisto Storefront API 密钥由 Bagisto 管理后台生成用于标识合法客户端channelCodedefault渠道代码会作为X-CHANNEL请求头发送给后端channelId1默认渠道 ID应用启动引导Bootstrap阶段按此 ID 拉取渠道的货币与语言配置companyNameYour Company Name公司名称用于应用内展示文档注明默认值为 Webkul Software (Registered in India)配置步骤打开 lib/core/constants/api_constants.dart将bagistoEndpoint替换为你的 Bagisto GraphQL 端点 URL形如https://your-store.com/graphql将storefrontKey替换为从 Bagisto 管理后台获取的 Storefront API 密钥按需更新companyName如果你的店铺使用非默认渠道同步修改channelCode与channelId。这些常量在源码中如何被消费从源码调用链可以清晰看到每个常量的实际用途端点与密钥在 lib/core/graphql/graphql_client.dart 的GraphQLClientProvider中bagistoEndpoint被传入HttpLink而storefrontKey被写入每个请求的默认头X-STOREFRONT-KEY。也就是说这两个值任何一处配错所有 GraphQL 请求都会失败。渠道标识channelCode在 lib/core/graphql/graphql_client.dart 中被写入X-CHANNEL请求头channelId则被 lib/core/channel/channel_bootstrap_service.dart 用作StoreConfigQueries.getChannelById查询的变量应用启动时据此拉取该渠道支持的货币与语言列表并写入SharedPreferences作为默认偏好。认证头当用户登录后客户端还会额外附加Authorization: Bearer token头见buildClient(token:)与authenticatedClient。提示从源码结构看仓库还提供了带日志的LoggingHttpClient在 debug 模式下打印每次请求的 API 名称、URL、耗时与状态码方便你在接入阶段排查 API 配置问题。主题配置品牌色与明暗主题配置文件lib/core/theme/app_theme.dart整个 App 的视觉系统由三类 Dart 类承载AppColors设计令牌、AppTextStyles字体样式与AppTheme明暗主题定义。修改主色AppColors类在 AppColors 类中集中定义所有颜色注释标明这些设计令牌提取自 Figma 设计稿Light 模式 node-id92-1679Dark 模式 node-id92-1730class AppColors { // Primary Colors static const Color primary500 Color(0xFFFF6900); // Main primary color (Orange) static const Color primary600 Color(0xFFF54900); // Darker variant for pressed states // 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/primary600品牌主色默认橙色 0xFFFF6900及按压态加深色同时是ColorScheme的 primary/secondaryneutral50~neutral900从浅到深的 10 级中性灰阶用于背景、边框、正文与标题successGreen/success50/success500/success700成功状态如价格、成功提示的深浅变体process600/process700信息/进行中状态蓝色系white/black静态基础色修改品牌色时只需调整primary500与primary600两个值所有按钮、选中态、价格强调、底部导航选中项都会随之改变。主题模式Light / DarkAppTheme 类提供两套完整的ThemeDataLight ThemescaffoldBackgroundColor为白色onSurface为neutral900深色文字底部导航背景为neutral50Dark ThemescaffoldBackgroundColor为neutral900近黑色onSurface为neutral200浅色文字底部导航背景为neutral800。两套主题的共同点均启用Material 3useMaterial3: true字体族统一为RobotoAppBarTheme无阴影elevation 0且surfaceTintColor透明CardTheme使用 12px 圆角、无阴影的卡片样式。主题模式的切换由 lib/core/theme/theme_cubit.dart 管理lib/main.dart 中通过theme: AppTheme.lightTheme、darkTheme: AppTheme.darkTheme与themeMode完成装配。另外AppTextStyles 类定义了 text1~text6、价格文本、划线原价、折扣价等十余种文字样式全部跟随明暗模式自动取色。若需对颜色做更细粒度的定制参见 Docs/ColorSetUp.md详细配色定制指南。应用名称配置Android配置文件android/app/src/main/AndroidManifest.xml修改application标签上的android:label属性即可更换桌面显示的应用名application android:labelYour App Name android:name${applicationName} android:iconmipmap/ic_launcher当前仓库中的默认值为Mobikul Bagisto Laravel App见 android/app/src/main/AndroidManifest.xml。iOS配置文件ios/Runner/Info.plist找到CFBundleDisplayName键并替换其字符串值keyCFBundleDisplayName/key stringYour App Name/string当前仓库中的默认值同样为Mobikul Bagisto Laravel App见 ios/Runner/Info.plist。启动屏配置文件assets/images/splash.png将现有的splash.png替换为你自己的启动图即可。当前仓库自带的默认图是一张 720×1460 的占位图纯白背景中央为黑色大号 mobikul 与 For Bagisto 品牌文字顶部提示这是演示商店通过本应用提交的任何请求都不会被处理底部标注开发方 Webkul Software。Android 平台配置文件android/app/src/main/res/drawable-v21/launch_background.xml该文件使用layer-list定义启动背景当前默认仅设置背景色。可以取消注释并插入自定义位图让启动图居中显示?xml version1.0 encodingutf-8? layer-list xmlns:androidhttp://schemas.android.com/apk/res/android item android:drawable?android:colorBackground / !-- 在此插入你自己的启动图片资源 -- !-- item bitmap android:gravitycenter android:srcmipmap/launch_image / /item -- /layer-listiOS 平台相关文件ios/Runner/Assets.xcassets/LaunchImage.imageset/ios/Runner/Assets.xcassets/splash.imageset/替换以下三个倍率文件以适配不同分辨率的设备LaunchImage.png1xLaunchImage2x.png2xLaunchImage3x.png3x同时更新splash.imageset以配合 Flutter 侧启动流程。iOS 的Info.plist中UILaunchStoryboardName指向LaunchScreen因此替换 LaunchImage 三件套即可覆盖系统启动阶段。App 图标配置Android图标位于 android/app/src/main/res/mipmap-xxxhdpi/以及其他各密度mipmap-*目录。推荐使用 Android Studio 的 Image Asset 工具自动生成全套密度图标用 Android Studio 打开android目录右键app→New→Image Asset设置你的自定义图标图片Studio 会自动输出到各 mipmap 目录。AndroidManifest.xml中通过android:iconmipmap/ic_launcher引用这套图标。iOS文件ios/Runner/Assets.xcassets/AppIcon.appiconset/替换其中的图标图片即可。建议使用 Xcode 的 AppIcon 模板以保证各尺寸含 1024×1024 App Store 尺寸规范正确。推送通知服务配置Firebase推送通知基于 Firebase Cloud MessagingFCM实现。仓库中的 Firebase 配置文件目前全部是占位dummy值必须替换为你自己的 Firebase 项目配置后推送才能工作。Android文件android/app/google-services.json用你的 Firebase 项目配置文件替换该文件登录 Firebase 控制台 → 项目设置 → 常规点击添加应用→ Android注册包名后下载google-services.json替换 android/app/google-services.json 中的占位内容。iOS文件ios/Runner/GoogleService-Info.plist替换流程与 Android 类似Firebase 控制台 → 项目设置 → 常规点击添加应用→ iOS下载GoogleService-Info.plist替换 ios/Runner/GoogleService-Info.plist 中的占位内容。注意上述两份文件当前包含占位值必须替换为真实配置推送通知功能才能生效。占位配置的自动检测机制仓库并非无脑初始化 Firebase而是内置了占位值检测。在 lib/core/notifications/firebase_service.dart 中FirebaseService._hasPlaceholderConfig会比对projectId、messagingSenderId、storageBucket三个字段与占位配置是否一致static bool _hasPlaceholderConfig(FirebaseOptions options) { return options.projectId FirebasePlaceholderConfig.projectId || options.messagingSenderId FirebasePlaceholderConfig.senderId || options.storageBucket FirebasePlaceholderConfig.storageBucket; }一旦检测到占位值FirebaseService.initialize()会返回false并跳过 Firebase 初始化——App 仍可正常使用只是没有推送通知。这也解释了为什么替换google-services.json/GoogleService-Info.plist后需要同时保证 lib/core/notifications/firebase_options.dart 中的FirebasePlaceholderConfig对应的平台选项被正确生成/替换。通知的初始化链路从 lib/main.dart 的main()可以看到完整启动顺序FirebaseService.initialize()初始化 Firebase占位配置时跳过若启用注册FirebaseMessaging.onBackgroundMessage后台消息处理器初始化 Hive 缓存与SharedPreferences执行ChannelBootstrapService.bootstrap()拉取渠道语言与货币若启用初始化FCMService含前台/后台/点击通知回调与 iOS APNS 支持并获取设备 Token。消息的data负载支持category跳转分类商品页、product支持productUrlKey或productId两种方式跳转商品详情、order/order_status跳转订单详情等类型的深链跳转具体字段可参考 lib/main.dart 中的_navigateFromNotification实现。更完整的 Firebase 配置细节可参见 Docs/Android_Firebase_Setup.md 与 Docs/iOS_Firebase_Setup.md。权限配置应用为支持完整功能尤其是图像搜索、语音搜索与语音识别需要声明以下权限。请注意同时需要在运行时向用户动态申请授权仓库使用permission_handler插件相关逻辑位于 lib/features/search/presentation/pages/image_search_screen.dart 与 lib/features/search/data/services/permission_service.dart。Android 权限配置文件android/app/src/main/AndroidManifest.xml!-- Camera permissions for image search -- 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/ !-- Microphone permission for speech recognition -- uses-permission android:nameandroid.permission.RECORD_AUDIO/ !-- Internet permission -- uses-permission android:nameandroid.permission.INTERNET/其中android.hardware.camera的requiredfalse表示设备没有摄像头时应用仍可安装运行仅相关功能不可用。存储类权限WRITE/READ_EXTERNAL_STORAGE、READ_MEDIA_IMAGES与图库选择功能对应RECORD_AUDIO则服务于语音搜索。iOS 权限配置文件ios/Runner/Info.plistiOS 要求为每个敏感权限提供使用描述字符串缺失时系统会直接拒绝授权!-- Camera for image search -- keyNSCameraUsageDescription/key stringThis app needs camera access to capture photos for image-based product search./string !-- Microphone for voice search -- keyNSMicrophoneUsageDescription/key stringThis app needs microphone access for voice search functionality./string !-- Photo Library -- 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 !-- Speech Recognition -- keyNSSpeechRecognitionUsageDescription/key stringThis app uses speech recognition for voice search./string这些描述文案已在仓库的 ios/Runner/Info.plist 中配置妥当如需调整措辞例如面向不同地区用户直接修改对应string值即可。配置文件汇总表以下为应用配置所涉及的全部关键文件替换对应文件即可完成相应定制配置项文件路径API 端点与密钥lib/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/启动屏图片assets/images/splash.pngAndroid 启动背景android/app/src/main/res/drawable-v21/launch_background.xmliOS 启动图ios/Runner/Assets.xcassets/LaunchImage.imageset/ 与 ios/Runner/Assets.xcassets/splash.imageset/Android 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.dart依赖声明pubspec.yaml相关资源Docs/ConfigGuide.md —— 备选详细配置指南含语言本地化与 GraphQL 配置章节Docs/ColorSetUp.md —— 颜色定制详细指南Docs/ServerConfig.md —— 服务端配置Docs/installationGuide.md —— 应用安装说明Docs/PlaceholderSetup.md —— 占位图配置Docs/LanguageConfiguration.md —— 新增语言的完整步骤Docs/Android_Firebase_Setup.md 与 Docs/iOS_Firebase_Setup.md —— 双端 Firebase 接入指南通过上述配置文件的替换与调整即可将本开源项目快速对接到你自己的 Bagisto 店铺并完成品牌化定制。建议按照API → 主题 → 名称/图标/启动屏 → 推送 → 权限的顺序依次验证每完成一步重启应用确认生效再进入下一步。【免费下载链接】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），仅供参考