Flutter插件vyuh_core介绍与使用方法

Flutter插件vyuh_core介绍与使用方法

Flutter插件vyuh_core简介

Vyuh 框架提供了一个核心库 vyuh_core，它提供了构建模块化、可扩展、CMS 驱动的 Flutter 应用程序所需的基本构建块和运行时功能。该包是 Vyuh 生态系统的基础，提供了一个强大的插件架构、模块化功能，并通过扩展机制提供了可选的 CMS 驱动的 UI。

Flutter插件vyuh_core特性

• 基于特征的架构 🏗️: 通过将应用程序拆分为独立的功能来构建模块化应用程序，每个功能都封装了自己的路由、UI 和业务逻辑。通过组合这些功能来构建整个应用程序。
• 插件架构 🔌: 可扩展的插件系统，支持导航、网络、遥测和内容管理等功能。
• 内容管理 📝: 可扩展的内容提供商系统，用于处理不同类型的内容。默认支持 Sanity.io CMS。可以通过 Provider 接口添加其他 CMS 集成的支持。
• 导航 🧭: 使用 Go Router 提供高级路由能力。
• 状态管理 💫: 集成了 MobX 进行响应式状态管理。你也可以使用自己的状态管理解决方案。
• 网络 🌐: 灵活的 HTTP 客户端，具有重试功能。
• 遥测 📊: 可配置的遥测系统，用于日志记录和错误跟踪。
• 分析 📊: 内置分析系统，用于跟踪用户交互和应用使用情况。
• 依赖注入 💉: 简单而强大的依赖注入系统，用于管理依赖项。
• 事件系统 📡: 发布/订阅事件系统，用于解耦通信。
• 存储 💾: 持久化存储功能，用于本地数据。
• 环境变量 🔧: 灵活的配置系统，用于管理特定环境的设置。
• 平台小部件 🎨: 可定制的小部件，用于常见的 UI 模式，如加载器和错误视图。

Flutter插件vyuh_core安装

在项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  vyuh_core: any

使用

基本应用设置

这是你的 Vyuh 应用程序的入口点。在这里你可以配置初始路由、注册功能并设置任何自定义插件。功能作为数组进行组装，便于添加或删除功能。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

void main() {
  vyuh.runApp(
    initialLocation: '/',
    plugins: _getPlugins(),
    features: () => [
      // 你的功能
      counter.feature,
      auth.feature(),
    ],
  );
}

功能定义

功能是应用程序的构建块。每个功能都是自包含的，有自己的路由、UI 组件和业务逻辑。功能可以独立开发和测试，然后组合在一起创建完整的应用程序。

import 'package:vyuh_core/vyuh_core.dart';

final feature = FeatureDescriptor(
  name: 'feature_name',
  title: '功能标题',
  description: '功能描述',
  icon: Icons.feature_icon,
  routes: () async {
    return [
      GoRoute(
        path: '/feature-path',
        builder: (context, state) {
          return const FeatureWidget();
        },
      ),
    ];
  },
);

插件配置

插件扩展了应用程序的核心功能。插件系统非常灵活，允许你配置各种方面，例如内容管理、环境变量和遥测。你还可以为特定需求创建自定义插件。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

PluginDescriptor _getPlugins() {
  // 启用 URL 反射以支持导航（可选）
  vyuh.DefaultNavigationPlugin.enableURLReflectsImperativeAPIs();
  vyuh.DefaultNavigationPlugin.usePathStrategy();

  return PluginDescriptor(
    // 配置内容插件
    content: vyuh.DefaultContentPlugin(
      provider: yourContentProvider,
    ),
    // 配置环境插件
    env: vyuh.DefaultEnvPlugin(),
    // 配置遥测
    telemetry: vyuh.TelemetryPlugin(
      providers: [vyuh.ConsoleLoggerTelemetryProvider()],
    ),
  );
}

自定义内容类型

内容类型代表可以由内容管理系统管理的特定类型的内容。你可以为应用程序创建自定义内容类型和布局。

import 'package:json_annotation/json_annotation.dart';
import 'package:vyuh_core/vyuh_core.dart';
import 'package:vyuh_extension_content/vyuh_extension_content.dart';

part 'my_card.g.dart';

@JsonSerializable()
final class MyCard extends ContentItem {
  static const schemaName = 'myCard';
  static final typeDescriptor = TypeDescriptor(
    schemaType: schemaName,
    title: '我的卡片',
    fromJson: MyCard.fromJson,
  );

  static final contentBuilder = ContentBuilder(
    content: typeDescriptor,
    defaultLayout: CustomCardLayout(),
    defaultLayoutDescriptor: CustomCardLayout.typeDescriptor,
  );

  final String title;
  final ImageReference? image;
  final String description;
  final List<Action> actions;

  MyCard({
    required super.id,
    required this.title,
    this.image,
    required this.description,
    this.actions = const [],
  }) : super(schemaType: schemaName);

  factory MyCard.fromJson(Map<String, dynamic> json) => _$MyCardFromJson(json);
}

自定义内容布局

布局用于配置内容项的视觉布局。你可以有一个默认布局，也可以为内容类型创建自定义布局。

@JsonSerializable()
final class CustomCardLayout extends LayoutConfiguration<MyCard> {
  static const schemaName = '${MyCard.schemaName}.layout.custom';
  static final typeDescriptor = TypeDescriptor(
    schemaType: schemaName,
    title: '自定义布局',
    fromJson: CustomCardLayout.fromJson,
  );

  CustomCardLayout() : super(schemaType: schemaName);

  @override
  Widget build(BuildContext context, MyCard content) {
    return Card(
      child: Column(
        children: [
          Text(content.title),
          ContentImage(ref: content.image),
        ],
      ),
    );
  }
}

分析

使用分析插件跟踪事件和用户交互：

// 获取分析插件
final analytics = vyuh.di.get<AnalyticsPlugin>();

// 跟踪简单事件
analytics.reportEvent('page_view');

// 跟踪带参数的事件
analytics.reportEvent(
  'button_click',
  params: {
    'button_id': 'submit',
    'screen': 'checkout',
  },
);

// 配置多个提供者
final analyticsPlugin = AnalyticsPlugin(
  providers: [
    GoogleAnalyticsProvider(),
    MixpanelProvider(),
    CustomAnalyticsProvider(),
  ],
);

导航

Vyuh 提供了一个基于 GoRouter 的简单而强大的导航系统。路由器全局可访问，通过 vyuh.router 可以从应用程序的任何位置轻松导航到不同的路由。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// 导航到一个路由
vyuh.router.push('/your-route');

// 使用命名路由导航
vyuh.router.pushNamed(
  'route-name',
  pathParameters: {'id': '123'},
  queryParameters: {'filter': 'active'},
);

// 到达一个路由（替换当前路由）
vyuh.router.go('/your-route');

// 返回上一个页面
vyuh.router.pop();

使用 MobX 进行状态管理

Vyuh 内置了对 MobX 的支持，提供了开箱即用的响应式状态管理。MobX 的简单而强大的方法使得管理应用程序状态变得轻而易举。

import 'package:mobx/mobx.dart';
import 'package:flutter/material.dart';
import 'package:flutter_mobx/flutter_mobx.dart';

// 创建可观察值
final counter = 0.obs();

// 在 widget 中使用 Observer
Column(
  children: [
    Observer(
      builder: (_) => Text('${counter.value}'),
    ),
    IconButton(
      icon: Icon(Icons.add),
      onPressed: () => runInAction(() => counter.value++),
    ),
  ],
);

依赖注入

一个简单的但功能强大的依赖注入系统，用于管理应用程序的依赖项。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// 注册依赖项
vyuh.di.register<MyService>(() => MyServiceImpl());

// 获取实例
final service = vyuh.di.get<MyService>();

事件系统

使用事件系统在应用程序的不同部分之间进行解耦通信。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// 订阅事件
vyuh.events.on<UserLoggedIn>((event) {
  // 处理事件
});

// 发布事件
vyuh.events.emit(UserLoggedIn(userId: '123'));

存储

使用存储插件持久化本地数据。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// 存储数据
await vyuh.storage.set('key', 'value');

// 获取数据
final value = await vyuh.storage.get('key');

环境变量

使用环境插件管理特定于环境的配置。

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// 访问环境变量
final apiKey = vyuh.env.get('API_KEY');
final isDev = vyuh.env.get('IS_DEV', defaultValue: false);

平台小部件

自定义应用程序的根小部件和其他平台特定的 UI 组件。defaultPlatformWidgetBuilder 提供了默认实现，你可以使用 copyWith 进行自定义：

import 'package:vyuh_core/vyuh_core.dart' as vyuh;
import 'package:flutter_mobx/flutter_mobx.dart';

vyuh.runApp(
  platformWidgetBuilder:
      vyuh.defaultPlatformWidgetBuilder.copyWith(
        // 自定义根应用小部件
        appBuilder: (platform) {
          return Observer(
            builder: (_) {
              return MaterialApp.router(
                title: '你的应用',
                theme: YourTheme.light,
                darkTheme: YourTheme.dark,
                debugShowCheckedModeBanner: false,
                routerConfig: platform.router.instance,
              );
            },
          );
        },
        // 自定义应用加载器，在初始应用加载期间显示
        appLoader: (context) {
          return const Center(
            child: CircularProgressIndicator(),
          );
        },
        // 自定义内容加载器，在加载内容时显示
        contentLoader: (context) {
          return const Center(
            child: CircularProgressIndicator(),
          );
        },
        // 自定义路由加载器，在路由过渡期间显示
        routeLoader: (context, color) {
          return DefaultRouteLoader(
            progressColor: color,
          );
        },
        // 自定义路由错误视图，当路由加载失败时显示
        routeErrorView: (context, error) {
          return Center(
            child: Text('路由错误: $error'),
          );
        },
        // 自定义一般错误视图，当发生一般错误时显示
        errorView: (context, error) {
          return Center(
            child: Text('错误: $error'),
          );
        },
        // 自定义图像占位符
        imagePlaceholder: (context) {
          return const Center(
            child: Icon(Icons.image),
          );
        },
      ),
  // ... 其他配置
);