Flutter功能扩展插件vyuh_feature_system的使用

Vyuh Feature System 🔧

vyuh_feature_system 是为Vyuh框架提供的系统特性包，提供了构建CMS驱动的Flutter应用所需的基本内容类型、动作、条件和服务。

特性 ✨

内容类型 📝

路由 🧭

• 页面路由：具有多种布局的全屏页面

  • 默认页面布局（带app bar和body）
  • 标签页布局（用于分段内容）
  • 单项布局（用于集中内容）
  • 动态路由条件布局

• 对话框路由：具有可自定义内容的模态对话框

  • 默认对话框布局
  • 自定义对话框布局

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 创建一个页面路由
system.Route(
  builder: (context) => MyPage(),
  type: system.RouteType.page,
);

// 创建一个对话框路由
system.Route(
  builder: (context) => MyDialog(),
  type: system.RouteType.dialog,
);

卡片 🎴

• 默认卡片：带有标题、内容和操作的标准卡片布局
• 列表项卡片：适用于列表视图的紧凑布局
• 按钮卡片：具有触发操作的交互式卡片
• 条件卡片：基于条件的动态布局

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 创建一个默认卡片
system.Card(
  title: '标题',
  content: '内容',
  actions: [
    system.Action(
      type: system.ActionType.navigate,
      payload: '/path/to/next/page',
    ),
  ],
);

组 📦

• 轮播：水平滚动的项目组

  • 支持自动播放
  • 导航控制
  • 自定义过渡效果

• 网格：响应式的网格布局

  • 可配置的列数
  • 响应断点
  • 自定义项目间距

• 列表：项目的垂直列表

  • 可配置的间距
  • 支持分隔符
  • 自定义项目布局

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 创建一个轮播组件
system.Carousel(
  items: [
    system.Item(
      child: Text('Item 1'),
    ),
    system.Item(
      child: Text('Item 2'),
    ),
  ],
);

其他项目 🔧

• 可移植文本：具有自定义标记的富文本内容

  • 操作调用标记
  • 具有自定义样式的链接标记
  • 自定义块样式

• 空内容占位符

• 未知内容占位符

• 基于条件的内容

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 创建一个包含丰富文本的卡片
system.Card(
  title: '标题',
  content: system.PortableText(
    content: [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "value": "这是丰富的文本内容。"},
        ],
      },
    ],
  ),
);

每个内容类型都可以通过实现 LayoutConfiguration<T> 并在功能描述符中注册布局来扩展。

动作 🎯

该系统特性包提供了一些内置的动作，用于导航、UI控制和系统操作：

导航动作 🧭

• NavigateAction：导航到新的路由，并可选地传递查询参数
• NavigateBackAction：返回到历史记录中的上一个路由
• NavigateReplaceAction：替换当前路由为一个新的路由
• OpenUrlAction：在浏览器或应用中打开外部URL

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 使用NavigateAction导航到新页面
system.NavigateAction(
  path: '/new_page',
).execute(context);

UI动作 🎨

• AlertAction：显示不同类型的消息（成功、错误、信息）的snackbar
• DrawerAction：显示或隐藏导航抽屉
• OpenInDialogAction：在模态对话框中显示内容
• ToggleThemeAction：切换亮暗主题

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 使用AlertAction显示消息
system.AlertAction(
  message: '这是一条消息',
  type: system.AlertType.success,
).execute(context);

系统动作 ⚙️

• DelayAction：在执行动作之间添加定时延迟
• RouteRefreshAction：刷新当前路由的内容
• RestartAction：重启整个应用程序

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 使用RestartAction重启应用
system.RestartAction().execute();

条件 🔄

• 布尔：简单的布尔条件
• 功能标志：基于条件切换功能
• 屏幕尺寸：基于屏幕尺寸的响应式布局
• 当前平台：特定于平台的内容
• 主题模式：基于主题的内容
• 用户认证：基于认证状态的内容

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 使用屏幕尺寸条件
if (system.BreakpointService().isMobile) {
  // 移动端布局
} else if (system.BreakpointService().isTablet) {
  // 平板布局
} else {
  // 桌面布局
}

内容修饰符

内容修饰符允许你在渲染之前对内容进行转换：

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 应用基于主题的修改
system.ThemeModifier(
  light: system.LightContent(),
  dark: system.DarkContent(),
);

API处理器

配置API内容处理：

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

final apiConfig = system.JsonPathApiConfiguration(
  baseUrl: 'https://api.example.com',
  paths: {
    'products': '\$.items[*]',
    'categories': '\$.categories[*]',
  },
);

服务 🛠️

断点服务

处理响应式布局：

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

final breakpointService = vyuh.di.get<system.BreakpointService>();

system.Observer(
  builder: (_) {
    if (breakpointService.isMobile) {
      return MobileLayout();
    }
    if (breakpointService.isTablet) {
      return TabletLayout();
    }
    return DesktopLayout();
  },
);

// 设置自定义断点
breakpointService.setBreakpoints(
  mobile: 480,
  tablet: 768,
  desktop: 1024,
);

主题服务

管理应用的主题和模式：

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

// 获取主题服务
final themeService = vyuh.di.get<system.ThemeService>();

// 切换主题
system.ToggleThemeAction().execute();

// 观察当前主题模式
system.Observer(
  builder: (_) {
    final mode = themeService.currentMode.value;
    return Text('当前主题: $mode');
  },
);

内容扩展

注册内容类型和生成器：

import 'package:vyuh_feature_system/vyuh_feature_system.dart' as system;

final feature = system.FeatureDescriptor(
  name: 'my_feature',
  extensions: [
    system.ContentExtensionDescriptor(
      contents: [
        // 你的内容描述符
      ],
      contentBuilders: [
        system.Route.contentBuilder,
        system.Card.contentBuilder,
        system.Group.contentBuilder,
      ],
      contentModifiers: [
        system.ThemeModifier.modifier,
      ],
    ),
  ],
);

系统路由

该系统特性包提供了内置路由：

错误路由

• 路径: /__system_error__
• 目的: 显示系统错误及其堆栈跟踪
• 使用: 框架自动用于错误处理

导航路由

• 路径: /__system_navigate__
• 目的: 处理外部导航（URLs，深度链接）
• 使用: 导航动作自动使用

这些路由在使用系统特性时会自动注册，为您的应用提供一致的错误处理和导航行为。

安装 📦

在您的 pubspec.yaml 文件中添加以下内容：

dependencies:
  vyuh_feature_system: any