패키지, 저장소 및 앱 카테고리 검색

패키지 상세v3.0.0

voyager

Flutter용 위젯 라우터 및 기본 종속성 주입 라이브러리입니다. YAML에서 네비게이션 경로를 정의하고 사용자 지정 플러그인으로 강화하세요.

AndroidiOSLinuxmacOSWebWindows
30일 다운로드
104
좋아요
28
Pub 점수
130

패키지 설치

flutter pub add voyager

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

Voyager는 위젯 라우팅과 기본적인 종속성 주입을 결합한 Flutter 패키지로, 개발자가 YAML 형식으로 네비게이션 경로를 정의할 수 있게 해줍니다. 동적 라우트 구성과 사용자 정의 플러그인을 통한 확장성을 지원하여 네비게이션 로직을 단순화하고 반복 코드를 줄입니다. YAML을 활용함으로써 라우트는 선언적이며 유지보수 가능해지고, 내장된 종속성 주입은 화면 간 서비스 관리를 원활하게 지원합니다. 복잡한 네비게이션 요구 사항을 가진 앱에 적합하며, Voyager는 개발을 간소화하고 코드 구조를 향상시킵니다.

사용 사례

  • YAML을 사용한 선언적 탐색
  • 복잡한 앱 라우팅
  • 동적 라우트 구성
  • 플러그인 기반의 탐색 확장
  • 간소화된 종속성 주입
  • 크로스 플랫폼 탐색

주요 기능

  • YAML 기반 경로 정의
  • 사용자 정의 플러그인 지원
  • 내장된 종속성 주입
  • 크로스 플랫폼 호환성
  • 최소한의 뼈대 코드
  • 확장 가능한 탐색 시스템

적합한 대상

  • 대규모 플러터 애플리케이션
  • 유지보수 가능한 라우팅을 우선시하는 팀
  • 선언적 구성 사용 개발자
  • 동적 탐색이 필요한 앱
  • 재사용 가능한 탐색 컴포넌트를 갖춘 프로젝트

고려 사항

  • 경로 설정을 위해서는 YAML 지식이 필요합니다
  • 기본 종속성 주입에 제한됨
  • 플러그인 통합의 학습 곡선
  • 간단한 단일 화면 앱에는 적합하지 않음
  • 외부 YAML 파싱에 의존
  • 검증을 위해 추가 도구가 필요할 수 있습니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

banner

pub package Codemagic build status codecov Kotlinlang slack

Navigate and prosper 🖖

Voyager is a Widget router for Flutter with a dynamic navigation map and Provider based DI elements.

Features

  • Support for Navigator 1.0/2.0 APIs
  • YAML/JSON based Navigation Map
    • support for query parameters (?param=value)
    • path subsections (/user/:id)
    • parameters interpolation in subsections (Selected %{id})
    • serializable (can be delivered using e.g. Firebase remote config)
    • fast code generator for paths & plugins
    • schema validation (draft v7)
  • Highly customizable plugin architecture.
  • VoyagerWidget to embed your path mapping in any place

Getting started

Check the example app on github or see it in the browser.

Add Voyager Dependency

To use this plugin, add voyager as a dependency in your pubspec.yaml file.

You should ensure that you add the router as a dependency in your flutter project.

dependencies:
 voyager: ^latest_release

Then in the code, make sure you import voyager package:

import 'package:voyager/voyager.dart';
Define Navigation Map

In an example below there are two paths defined - /home and /other/:title. These paths route to HomeWidget and OtherWidget respectively. A map can carry extra information along the way - e.g. title will later be accessible in the routed widget.

---
'/home' :
  widget: HomeWidget
  title: "This is Home"
'/other/:thing' :
  widget: OtherWidget
  title: "This is %{thing}"

The second path has :thing section parameter. This can be used to interpolate value of title dynamically at runtime, using %{key} notation.

Load paths using method of your choosing:

final List<VoyagerPath> paths = loadPathsFromYamlSync(yaml_string);
Define Plugins

You need to tell router what kind of plugins you plan to use. Those depend on what you have written in the navigation file. In our example we need to provide mappings for widget and title.

final plugins = [
  WidgetPluginBuilder() /// provide widget builders for expressions used in YAML
    .add("HomeWidget", (context) => HomeWidget())
    .add("OtherWidget", (context) => OtherWidget())
    .build(),
  TitlePlugin() /// custom plugin
];
Instantiate Router

Pass paths and plugins as constructor parameters to obtain VoyagerRouter.

final router = VoyagerRouter.from(paths, plugins);
Choose Your API

Voyager offers different kind of APIs. Here's a quick overview what these are good for.

Voyager Widget

This is the most atomic use case. Simply embed your widget anywhere you want:

VoyagerWidget(path: "/home", router: router);

If Provider<VoyagerRouter> is available in the widget tree, you can omit the router parameter.

Navigator 1.0

Simple, imperative navigation model. Following snippet illustrates intergration with MaterialApp and opening initialPath:

final initalPath = "/my/fancy/super/path"

Provider<VoyagerRouter>.value(
  value: router,
  child: MaterialApp(
    home: VoyagerWidget(path: initalPath),
    onGenerateRoute: router.generator()
  )
)

Navigation stack is handled via system, e.g. following will push a new page:

Navigator.of(context).pushNamed("/path/to/go");

Sidenote: You can try using MaterialApp.initalRoute but please read this first if you find MaterialApp.initalRoute is not working for you... that's because it's probably working as intended ¯\_(ツ)_/¯

Navigator 2.0

Navigator 2.0 gives you a full control over the navigation stack. This comes with a price of fairly complex API. Voyager builds on top of this API and introduces VoyagerStack to hopefully make declarative navigation easier.

VoyagerStackApp(
  router: router,
  stack: VoyagerStack[
    VoyagerPage("/my/fancy/super/path"),
  ],
  createApp: (context, parser, delegate) => MaterialApp.router(
    routeInformationParser: parser,
    routerDelegate: delegate,
    theme: themeData(),
  ),
);

With Navigator 2.0, you own the navigation stack.

If you wish to navigate to the other path, you'll need to update the stack the declarative way, e.g.:

  // ...
  stack: VoyagerStack[
    VoyagerPage("/my/fancy/super/path"),
    VoyagerPage("/path/to/go"),
  ],
  // ...

Under the hood, VoyagerStack uses .asPages(VoyagerRouter) method that resolves the given stack to a List<Page<dynamic>> instance which then is used with Navigator. It's possible to use Navigator and VoyagerStack directly without VoyagerStackApp wrapper. Additionally VoyagerInformationParser and VoyagerDelegate are easily instantiable in case you need to use them directly.

Predefined Plugins

Voyager comes with a few predefined plugins that are ready to setup and use:

Widget Plugin

This is a mandatory plugin that enables widget resolution. It converts a string value from navigation map e.g. "HomeWidget" into a usable Flutter widget:

WidgetPlugin({
  "HomeWidget": (context) => HomeWidget()
});

You can enable code generation to avoid writing these mappings manually. Check the example app.

Page Plugin (a.k.a. transitions)

This plugin works only when using Voyager in Navigation 2.0 API. It enables specifying custom Page<dynamic> appearance to be used for the given path, e.g.:

PagePlugin({
  "slideFromTop": slideFromTop
});

Check slide_from_top_page.dart for a custom page implementation details

Code generation to avoid writing these mappings manually. Check the example app.

Redirect Plugin

Allows registering aliases for already defined paths:

---
'/home' :
  widget: HomeWidget
  title: "This is Home"
'/start' :
  redirect: '/home'
Writing Custom Plugins

You can define as many router plugins as you want. Here's how you could handle the title node from the example navigation yaml.

class TitlePlugin extends RouterPlugin {
  TitlePlugin() : super("title"); // YAML node to intercept

  @override
  void outputFor(RouterContext context, dynamic config, Voyager voyager) {
    // config can be anything that is passed from YAML
    voyager["title"] = config.toString(); // output of this plugin
  }
}

Sidenote: Above plugin is redundant. Voyager repackages the primitive types from configuration by default. Use plugins to resolve primitive types to custom types , e.g. take a look at IconPlugin from the example app.

Dependency Injection

If you use VoyagerWidget to e.g. resolve to OtherWidget, you can obtain Voyager anywhere from BuildContext using extension getter:

final voyager = context.voyager;

Voyager is a key/value map, a composite output of the plugins setup for the given path.

Now going back to our mystery OtherWidget class from the example navigation map, that widget's implementation could look something like this:

class OtherWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final voyager = context.voyager; // injecting voyager from build context
    final title = voyager["title"];

    return Scaffold(
      appBar: AppBar(
        title: Text(title), // et voilà
      ),
      body: Center(
        child: Text("Other Page"),
      )
    );
  }
}
Code generation

Using code generation enables you to use some of the following features:

  • Strong typed paths
    • "/other/:thing" becomes pathOther("thing")
  • WidgetPlugin generation
    • skip manual mapping, simply add generatedVoyagerWidgetPlugin() to list of plugins
  • PathPlugin generation
    • skip manual mapping, simply add generatedVoyagerPathPlugin() to list of plugins
  • Schema validation & strong typed Voyager fields

Important: Code generation relies heavily on the type value. It should be unique per path definition, also the values should_be_snake_case. Since 3.0 type is automatically generated based on the path - it still can be overridden manually.

Voyager supports generating dart code based on the navigation map yaml (or json) file. Simply run the following command and wait for the script to set it up for you.

flutter packages pub run voyager:codegen --run-once

This should create a voyager-codegen.yaml file in the root of your project:

- name: Voyager # base name for generated classes
  source: assets/navigation.yaml
  target: lib/navigation.voyager.dart
  widgetPlugin: true
  pagePlugin: true

Then you need to create lib/navigation.dart that will look something like this:

import 'package:voyager/voyager.dart';

part 'navigation.voyager.dart';

Now if you run again:

flutter packages pub run voyager:codegen --run-once

This should regenerate contents of lib/navigation.voyager.dart. If compiler complains about unresolved symbols, make sure you add necessary imports to lib/navigation.dart

Dart Code Formatting: If you want to have Flutter's default code formatting for the generated code, make sure you have dart-sdk in you PATH. Dart SDK is included with the flutter sdk, so you can e.g.:

export PATH="$PATH:/path/to/flutter/bin/cache/dart-sdk/bin"

File Watching: If you omit --run-once flag, the code generator will keep watching files and generating code in a loop.

You might want to add .jarCache/ to your .gitignore to avoid checking in binary jars to your repo.

Schema Validation

Add your validation in voyager-codegen.yaml, for instance to cover IconPlugin you could do this:

- name: Voyager
  source: lib/main.dart
  target: lib/navigation.voyager.dart
  schema:
    icon:
      pluginStub: true # add if you want to generate a plugin stub
      output: Icon # associated Dart class produced by the plugin
      input: # write schema for your the icon node (JSON Schema draft-07 layout)
        type: string
        pattern: "^[a-fA-F0-9]{4}$"

Now whenever you run voyager:codegen you'll get an extra message stating all is fine:

✅ Schema validated properly

...or an error specific to your router navigation map, e.g.:

🚨 /fab@icon: #/icon: string [e88fd] does not match pattern ^[a-fA-F0-9]{4}$

Furthermore you gain strong typed reference to the plugin output in extended Voyager instance:

assert(voyager.icon is Icon);

Finally, pluginStub: true gets you an abstract plugin class, so that you can avoid typing voyager["node_name"] manually. Just focus on parsing the node's config input and converting it into an expected output:

class IconPlugin extends IconPluginStub {
  @override
  Icon buildObject(RouterContext context, dynamic config) {
    /// write your code here
  }
}

카테고리

의존성

의존성 목록 4 개

소스 저장소

이 패키지를 사용하는 프로젝트

아직 데이터가 없습니다.