nopCommerce Dokumentace

Dokumentace mobilní aplikace

Úvod

Tým nopCommerce nabízí mobilní aplikaci pro iOS a Android. Přinese vašemu podnikání obrovskou hodnotu. Mobilní aplikace je zcela připravená k použití, takže můžete okamžitě začít prodávat své produkty a služby. Stejně jako platforma nopCommerce je i mobilní aplikace dodávána se zdrojovým kódem a nabízí neomezené možnosti přizpůsobení. Navíc se dokáže hladce přizpůsobit designu a funkcím vašeho internetového obchodu. K propojení aplikace s vaším obchodem nopCommerce, konfiguraci jejího obsahu a funkcí, publikaci v obchodech Google Play a App Store a ke správě jejího chodu nejsou potřeba žádné programátorské ani grafické dovednosti.

Zde jsou další významné funkce, které zajistí efektivní spuštění, přizpůsobení a údržbu mobilního e-commerce:

  • Postaveno na nejnovější verzi Flutter a Dart

  • Kompatibilní s Androidem a iOS

  • Využívá funkce Riverpod (správa stavu)

  • Snadno použitelné uživatelské rozhraní a krásný Material design 3

  • Autentizace založená na tokenech

  • Podpora internacionalizace

  • Podpora tmavého a světlého motivu

  • Ikony zdarma

Nastavení

Pomocí pluginu „nopCommerce mobile app“ lze kromě pluginu „Web API Frontend“ spravovat některá nastavení aplikace.

obrázek

K dispozici jsou následující funkce:

  1. Do mobilní aplikace lze přenést určitá nastavení. Je to tak záměrně, aby nebyl umožněn přístup k úplně všem nastavením aplikace. Pokud potřebujete další nastavení, musíte zajistit, aby je mobilní aplikace podporovala.
  2. Ovládání slideru na hlavní obrazovce. Můžete také určit, na které produkty budou uživatelé přesměrováni po kliknutí na jednotlivé obrázky slideru.

Visual Studio Code

Doporučeným vývojovým prostředím pro Flutter je Android Studio. Pohodlnou alternativou je editor VS Studio Code; níže jsou uvedena základní nastavení, která vám pomohou pohodlně pracovat s kódem, a také sada rozšíření nezbytných pro vývoj a ladění.

Nastavení editoru

{
    "[dart]": {
        "editor.codeActionsOnSave": {
            "source.fixAll": true
        },
        "editor.selectionHighlight": false,
        "editor.suggest.snippetsPreventQuickSuggestions": false,
        "editor.suggestSelection": "first",
        "editor.tabCompletion": "onlySnippets",
        "editor.wordBasedSuggestions": false,
    },
    "dart.warnWhenEditingFilesOutsideWorkspace": false,
    "dart.renameFilesWithClasses": "prompt",
    "editor.bracketPairColorization.enabled": true,
    "editor.inlineSuggest.enabled": true,
    "editor.formatOnSave": true,
    "explorer.compactFolders": false,
    "dart.debugExternalPackageLibraries": false,
    "dart.debugSdkLibraries": false,
    "editor.minimap.enabled": false
}

Rozšíření

Pro vývoj budete potřebovat nainstalovat následující rozšíření:

Název: Flutter
Id: Dart-Code.flutter
Popis: Podpora Flutteru a debugger pro Visual Studio Code.
Vydavatel: Dart Code
Odkaz na VS Marketplace: https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter

Název: Dart
Id: Dart-Code.dart-code
Popis: Podpora jazyka Dart a debugger pro Visual Studio Code.
Vydavatel: Dart Code
Odkaz na VS Marketplace: https://marketplace.visualstudio.com/items?itemName=Dart-Code.dart-code

Zahájení vývoje a přizpůsobení

Otevřete v editoru Visual Studio Code zdrojový kód z archivu, který obdržíte po zakoupení aplikace.

Ihned po otevření projektu v editoru kódu budete vyzváni ke stažení zahrnutých knihoven. Můžete to udělat i sami spuštěním následujícího příkazu v terminálu:

flutter pub get

Nyní je potřeba zadat endpoint pro připojení k serveru kvůli přístupu k API. Toto nastavení se nachází v souboru lib\constants\app_constants.dart:

class AppConstants {
  static const String storeUrl = 'https://yourstore.com';
}

Nyní je vše připraveno ke spuštění aplikace:

flutter run

Důležité

Ujistěte se, že je nastavení paymentSettings.BypassPaymentMethodSelectionIfOnlyOne vypnuté.

Další obecné doporučení k nastavení průběhu pokladny: nepovolujte nastavení, která vypínají nebo přeskakují kroky (například ordersettings.disablebillingaddresscheckoutstep). Taková nastavení nebudou mít v mobilní aplikaci žádný účinek.

Struktura projektu

Mobilní aplikace vyvinutá ve Flutteru zajišťuje funkce interakce s veřejnou částí obchodu pomocí Web API (Frontend). Všechny hlavní procesy interakce uživatele s aplikací jsou znázorněny na diagramu níže:

obrázek

Používá se přístup, podle kterého jsou funkce aplikace kořenovými složkami. Uvnitř takové složky pak popisujeme architektonické vrstvy příslušející této konkrétní funkci v podobě podsložek. Vše, co souvisí s funkcionalitou, která nás zajímá, se tak nachází v jedné složce, což výrazně usnadňuje pochopení kódu.

obrázek

Technologický stack

Použité frameworky a knihovny:

  • Flutter SDK 3.35.1
  • Dart SDK 3.9.0
  • flutter_riverpod: 2.6.1
  • go_router: 16.1.0
  • flutter_secure_storage: 9.2.4
  • dio: 5.9.0

Důležité

Pro správnou funkci aplikace se doporučuje používat verze balíčků uvedené v konfiguraci.

Architektura aplikace

Architektura aplikace je postavena podle obecně přijímaných standardů popsaných v dokumentaci Androidu. Protože projekt používá systém správy stavu Riverpod, byla architektura rozšířena a vypadá takto:

obrázek

Pro navigaci v aplikaci se používá knihovna go_router. Jde o deklarativní systém směrování postavený nad Flutter Router API.

Navigační mapa aplikace vypadá takto:

├─/splash (SplashScreen)
└─ (ShellRoute)
  ├─/home 
  ├─/catalog 
  │ ├─/catalog/category/:id (CategoryDetailsScreen)
  │ ├─/catalog/manufacturer/:id (ManufacturerDetailsScreen)
  │ ├─/catalog/vendor/:id (VendorDetailsScreen)
  │ ├─/catalog/productsByTag/:id (ProductsByTagScreen)
  │ ├─/catalog/productSearch/:q (ProductsSearchScreen)
  │ └─/catalog/product/:id (ProductDetailsScreen)
  │   ├─/catalog/product/:id/review (ProductReviewScreen)
  │   └─/catalog/product/:id/addReview 
  ├─/cart 
  │ └─/cart/checkout 
  └─/account 
    ├─/account/logincheckout 
    ├─/account/login 
    │ └─/account/login/forgotPassword (ForgotPasswordScreen)
    ├─/account/register 
    ├─/account/settings 
    ├─/account/contactUs 
    ├─/account/wishlist (WishlistScreen)
    ├─/account/accountInfo (AccountInfoScreen)
    ├─/account/accountAddresses (AccountAddressesScreen)
    │ └─/account/accountAddresses/createUpdateAddress/:id teAddressScreen)
    ├─/account/accountOrders (AccountOrdersScreen)
    │ └─/account/accountOrders/orderDetails/:id (OrderDetailsScreen)
    ├─/account/accountDownloadableProducts nloadableProductsScreen)
    ├─/account/accountBackInStock (AccountBackInStockScreen)
    ├─/account/accountRewardPoints (AccountRewardPointsScreen)
    ├─/account/accountChangePassword (AccountChangePassword)
    ├─/account/accountProductReviews (AccountProductReviewsScreen)
    ├─/account/accountGdprTools (AccountGdprToolsScreen)
    ├─/account/accountReturnRequests (AccountReturnRequestsScreen)
    └─/account/returnRequest/:id (ReturnRequestScreen)

Generování klienta Web API

Nainstalujte OpenAPI Generator (vyžaduje Node.js)

Chcete-li aktualizovat verzi OpenAPI Generatoru, použijte následující příkaz a ze zobrazeného seznamu vyberte nejnovější stabilní verzi.

openapi-generator-cli version-manager list

Vytvořte soubor openapitools.json. Použijte generátor dart-dio.

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.14.0",
    "generators": {
        "frontend": {
            "input-spec": "swagger.json",
            "generator-name": "dart-dio",
            "output": "frontend_api",
            "additionalProperties": {
                "pubName": "frontend_api"
            }
        }
    }
  }
}

Poznámka

Chcete-li aktualizovat verzi generátoru, spusťte následující příkaz:

openapi-generator-cli version-manager list

Je nutné, aby se schéma OpenAPI swagger.json nacházelo v adresáři s nainstalovaným generátorem.

  1. Pro vygenerování klienta zavolejte následující příkaz:

    openapi-generator-cli generate
    
  2. Standardní openapi-generator vygeneruje pouze základní kód, který používá knihovny spoléhající na vlastní generování kódu v Dartu. Proto je po dokončení základního generování nutné spustit generátor Dartu:

    cd frontend_api
    flutter pub get  
    dart run build_runner build -d
    

    Výsledkem je hotový balíček, který se bude nacházet tam, kde jste určili v konfiguračním souboru nebo v příkazu konzole. Zbývá ho zahrnout do pubspec.yaml:

    frontend_api: # <- nopCommerce generated api library
        path: lib/frontend_api
    

Lokalizace

Chcete-li lokalizovat rozhraní samotné aplikace, je třeba umístit soubor s lokalizacemi do složky \lib\localization. Je důležité, aby název souboru měl následující formát:

intl_.arb

Jako základ můžete vzít soubor intl_en.arb, který je již součástí sady, a přeložit jeho zdroje do cílového jazyka.

Spusťte v terminálu následující příkaz pro vygenerování potřebných zdrojových souborů pro lokalizaci.

flutter gen-l10n

Správnost vygenerování všech potřebných zdrojů si můžete ověřit v cestě lib\localization\generated\i18n.

obrázek

Upozornění

Neprovádějte v tomto souboru žádné změny, protože tato část kódu je generována automaticky. Všechny změny lokalizace by měly být prováděny výhradně v souboru intl_.arb umístěném v cestě \lib\localization.

Nyní bude při přepnutí jazyka v nastavení aplikace lokalizováno i rozhraní aplikace.

Důležité

Kód jazyka, který bude součástí názvu lokalizačního souboru, se musí shodovat s kódem přidaným na vašem serveru. V opačném případě bude rozhraní lokalizováno výchozími lokalizacemi (tj. en).

Návrh uživatelského rozhraní

Abychom zachovali jednotný a konzistentní vzhled napříč zařízeními, využili jsme potenciál design tokenů, které poskytuje Material 3. Tyto tokeny umožňují ukládat styly, písma a hodnoty animací, takže můžeme používat stejné hodnoty stylů v návrhových souborech i v kódu.

Používání tokenů přináší několik výhod:

  • Konzistence: Tokeny zajišťují konzistentní design napříč obrazovkami a komponentami.
  • Motivy: Snadné přepínání mezi světlým/tmavým/dynamickým motivem výměnou ColorScheme nebo ThemeData.
  • Udržovatelnost: Vzhled celé aplikace změníte z jednoho místa (není nutné hledat a nahrazovat kódy barev).
  • Spolupráce designu a vývoje: Tokeny slouží jako most mezi Figmou a Flutterem.

Integrace tokenů z návrhových nástrojů

Material Theme Builder (MTB) je nástroj pro designéry a vývojáře k vytváření barevných a typografických tokenů Material Design 3 (M3) a jejich exportu jako kódu (Flutter, Compose, Android XML, design tokeny atd.). Pomáhá vytvořit koordinované světlé/tmavé ColorScheme z výchozí/značkové barvy, zobrazit náhled komponent a exportovat artefakty připravené k implementaci.

Vygenerování barevného schématu

  1. Otevřete Material Theme Builder.

  2. Vyberte výchozí / primární barvu

    • Zadejte hexadecimální hodnotu, použijte výběr barvy nebo kapátko. Výchozí (primární) barva je jediný výchozí bod, ze kterého se generují tónové palety.

      obrázek

    • Můžete také povolit vstup dynamické barvy (tapeta/obrázek) nebo importovat obrázek pro extrakci barev — MTB z tohoto zdroje odvodí tónové palety.

      obrázek

  3. Zvolte nebo upravte sekundární / terciární / chybovou / neutrální barvu

    MTB zobrazuje pole pro běžné role (sekundární, terciární, chybová, neutrální atd.). Můžete přijmout automaticky vygenerované hodnoty nebo přepsat barvy konkrétních rolí (ručním zadáním hexadecimálních hodnot). Builder udržuje vztahy mezi rolemi v souladu s pravidly M3.

    obrázek

    Zde je potřeba vybrat základní barvy pro celé schéma. Můžete je zadat ručně, například pokud už máte definované barvy své značky. Na panelu Dynamic můžete nahrát obrázek a extrahovat z něj barvy. Pro generování harmonických barev se doporučuje použít službu https://coolors.co/.

    Klikněte na Start the generator:

    obrázek

    Přebytečné bloky můžete odstranit, dokud nezůstanou jen 3, a poté stisknutím mezerníku vygenerovat varianty.

  4. Přepínejte mezi světlým a tmavým náhledem

    Přepínáním Light/Dark okamžitě uvidíte obě schémata;

    obrázek

    MTB generuje párová světlá/tmavá ColorScheme, takže kontrast a vizuální hierarchie zůstávají zachovány v obou režimech jasu.

    obrázek

  5. Náhled komponent a ploch

    Builder nabízí živé náhledy (app bary, tlačítka, čipy, karty, položky seznamu, navigační lišty, dialogy). Pomocí nich ověřte, jak se vaše paleta chová na plochách, v textu, ikonách a interaktivních ovládacích prvcích.

    obrázek

  6. Použijte sladění / harmonizaci barev

    Pokud máte barvy značky, které kolidují s vygenerovanými tónovými paletami, MTB nabízí režimy sladění nebo harmonizace barev, které palety posunou tak, aby ladily s odstíny značky, a přitom stále dodržovaly tónová pravidla M3. To se hodí, když začínáte s více barvami značky.

    obrázek

  7. Typografie

    Vyberte základní rodinu písma. MTB dokáže k barevným tokenům vytvořit i tokeny pro typografii (řezy, velikosti, výšky řádků).

    obrázek

  8. Export

    Zvolte formát exportu – Flutter (Dart) – a poté exportujte/stáhněte ZIP s artefakty kódu a soubory tokenů. Pro Flutter builder obvykle vygeneruje soubor theme.dart, který můžete vložit do svého projektu.

    obrázek

Přehled souboru theme.dart

Jakmile vytvoříte barevnou paletu v Material Theme Builder a vyexportujete ji, získáte soubor theme.dart. Tento soubor je výchozím bodem pro stylování vaší aplikace. Jeho hlavním obsahem jsou obvykle dva objekty ColorScheme:

  • lightScheme: Definuje sadu barev pro světlý motiv aplikace (např. barvy pozadí, textu a zvýraznění ve světlém režimu).

  • darkScheme: Definuje stejné barvy pro tmavý motiv.

Tato schémata jsou generována na základě zvolené výchozí barvy a zajišťují harmonickou a konzistentní kombinaci barev v celé aplikaci v souladu s principy Material Design 3.

Integrace theme.dart do projektu

Aby struktura projektu zůstala přehledná, doporučuje se ukládat soubory související s motivem do samostatného adresáře.

Nahraďte vygenerované objekty ColorScheme z theme.dart v souboru lib/themes/material_theme.dart.

S růstem vašeho design systému můžete potřebovat zavést vlastní tokeny (např. specifické barvy značky, sémantické stavy). Použijte rozšíření (extensions). Tento kód ukazuje, které tokeny rozšíření se v mobilní aplikaci používají.

ThemeData theme(ColorScheme colorScheme) => ThemeData(
        useMaterial3: true,
        brightness: colorScheme.brightness,
        colorScheme: colorScheme,
        textTheme: textTheme.apply(
          bodyColor: colorScheme.onSurface,
          displayColor: colorScheme.onSurface,
        ),
        scaffoldBackgroundColor: colorScheme.surface,
        canvasColor: colorScheme.surface,
        // defailt extensions - BEGIN
        extensions: [
          CustomColors(
            subTextColor: colorScheme.onSurfaceVariant,
            ratingStarColor: colorScheme.secondary,
            pictureIndicatorColor: colorScheme.surfaceContainerHighest,
            pictureIndicatorCurrentColor: colorScheme.primary,
            inStockColor: colorScheme.tertiary,
            outOfStockColor: colorScheme.error,
          ),
        ],
        // defailt extensions - END
      );

Poznámka

Můžete použít celý obsah souboru theme.dart, ale nezapomeňte zahrnout výchozí rozšíření, která jsou k dispozici v souboru custom_color_scheme.dart.

To je vše — restartujte aplikaci a užijte si nové barevné schéma.

Publikování v obchodě Google Play

Proces vydání vaší aplikace ve Flutteru v obchodě Google Play zahrnuje přípravu, sestavení a poté nahrání aplikace do Google Play Console.

Klíčové kroky:

  1. Registrace vývojářského účtu Google Play: Budete se muset zaregistrovat k vývojářskému účtu.
  2. Příprava aplikace k vydání: Zahrnuje konfiguraci názvu aplikace, ikony a čísla verze v souboru pubspec.yaml a nastavení potřebných oprávnění.
  3. Podepsání aplikace: Musíte vygenerovat upload keystore a podepsat jím aplikaci, abyste ověřili svou identitu.
  4. Sestavení verze pro vydání: Pomocí příkazu flutter build appbundle vytvořte Android App Bundle (.aab) vaší aplikace.
  5. Publikování v Google Play Console: Vytvořte v Play Console nový záznam aplikace, vyplňte všechny požadované údaje záznamu v obchodě (název, popis, snímky obrazovky, zásady ochrany osobních údajů) a nahrajte soubor .aab ke kontrole.

Oficiální dokumentace: Build and release an Android app

Publikování v Apple App Store

Nasazení do Apple App Store vyžaduje registraci v programu Apple Developer Program a použití Xcode ke správě závěrečných kroků procesu.

Klíčové kroky:

  1. Registrace do Apple Developer Program: Jde o placené roční předplatné, které vám umožní publikovat v App Store.
  2. Konfigurace projektu v Xcode: Otevřete v Xcode složku ios vašeho projektu a nastavte Bundle ID, číslo verze a nastavení podepisování kódu.
  3. Vytvoření záznamu v App Store Connect: Přihlaste se do App Store Connect a vytvořte nový záznam aplikace. Zde zadáte všechna metadata aplikace, jako je její název, popis, snímky obrazovky, klíčová slova a informace o ochraně soukromí.
  4. Sestavení a archivace aplikace: Pomocí Xcode vytvořte archiv sestavení (.ipa) vaší aplikace.
  5. Nahrání do App Store Connect: Nahrajte archivované sestavení pomocí Xcode nebo nástroje Transporter.
  6. Odeslání ke kontrole: Jakmile je sestavení zpracováno a všechna metadata jsou kompletní, můžete aplikaci odeslat společnosti Apple ke kontrole.

Oficiální dokumentace: Build and release an iOS app

Přispěvatelé: DmitriyKulagin
Upravit na GitHubu