Flutter无障碍导航插件accessibility_navigation的使用

Flutter无障碍导航插件accessibility_navigation的使用

概览

无障碍导航 是一个增强您的应用程序导航功能的 Flutter 包。它通过聊天机器人界面允许用户搜索特定功能。它扩展了 go_router 包的功能，引入了 FeatureRoute，包括额外的属性如 name 和 description，并支持动态参数和多个 extra 数据条目，以更好地进行路由管理和无障碍访问。

特性

• 轻松集成：使用 go_router 轻松集成到现有 Flutter 应用程序。
• 聊天机器人界面：允许用户通过聊天机器人搜索应用程序功能。
• 扩展路由：使用 FeatureRoute 添加 name 和 description，并通过 includeChat 控制聊天界面的显示。
• 动态参数和附加数据：处理带有路径参数和多个 extra 数据条目的动态路由。
• 嵌套路由支持：支持嵌套路由和 StatefulShellRoute。
• GPT 模型选择：可选地选择 GPT 模型，默认为 gpt-4o-mini。
• 控制聊天可见性：在 FeatureRoute 中使用 includeChat 显示或隐藏特定页面上的聊天。
• 兼容性：与 GoRoute 兼容；您可以混合使用 GoRoute 和 FeatureRoute。

安装

将 accessibility_navigation 包添加到您的项目：

flutter pub add accessibility_navigation

使用

1. 设置路由器

在您的 main.dart 或其他设置路由器的地方，声明 FeatureRouter 如下：

FeatureRouter(
  goRouter: router,
  apiKey: 'your-gpt-api-key',
  gptModel: GPTModel.gpt4oMini, // 可选，默认为 gpt-4o-mini
);

选择 GPT 模型

您可以选择要使用的 GPT 模型，默认为 gpt-4o-mini。可用模型如下：

enum GPTModel {
  gpt4o('gpt-4o'),
  gpt4('gpt-4'),
  gpt4oMini('gpt-4o-mini');

  final String modelName;

  const GPTModel(this.modelName);
}

初始化 FeatureRouter 时设置 gptModel 参数：

FeatureRouter(
  goRouter: router,
  apiKey: 'your-gpt-api-key',
  gptModel: GPTModel.gpt4, // 选择所需的模型
);

2. 使用 FeatureRoute 定义路由

在您的 GoRouter 中，使用 FeatureRoute 替代 GoRoute 来定义路由。这允许您为每个路由添加额外的元数据如 name 和 description。

final GoRouter router = GoRouter(
  routes: [
    FeatureRoute(
      name: 'main',
      description: '主页，用户可以查看概览或访问各种功能。',
      path: '/',
      builder: (context, state) => const MainPage(),
    ),
    // 其他路由...
  ],
);

注意事项

• 使用 FeatureRoute 时，必须提供 name 和 description 参数。
• FeatureRoute 支持嵌套路由和 StatefulShellRoute。
• 控制聊天可见性：使用 includeChat 参数在特定页面上显示或隐藏聊天。默认值为 true。

FeatureRoute(
  name: 'settings',
  description: '用户设置页面',
  path: '/settings',
  includeChat: false, // 聊天不会出现在此页面上
  builder: (context, state) => const SettingsPage(),
),

3. 使用路径参数进行动态路由

FeatureRoute 使处理动态路由变得简单。您可以定义路径参数和多个 extra 数据条目来创建动态且灵活的路由。

定义参数

使用 parameters 属性来定义动态路径参数。

方法 1：使用 Map 定义参数值

使用 Map，键是路径参数，值是另一个 Map，其中包含可能的路径值及其显示名称。

FeatureRoute(
  path: '/invest/:companyID',
  name: 'investment_company',
  description: '投资公司详情',
  parameters: {
    'companyID': {
      '1': 'CompanyA',
      '2': 'CompanyB',
      '3': 'CompanyC',
    },
  },
  builder: (context, state) {
    final companyID = state.params['companyID']!;
    final companyName = getCompanyNameById(companyID);
    return InvestmentCompanyPage(
      companyID: companyID,
      companyName: companyName,
    );
  },
),

方法 2：使用 List 定义参数值

使用 List，路径参数映射到可能值的列表。

FeatureRoute(
  path: '/:action',
  name: 'investment_action',
  description: '买卖投资',
  parameters: {
    'action': ['buy', 'sell'],
  },
  builder: (context, state) {
    final action = state.params['action']!;
    // ...您的代码...
  },
),

4. 使用 extras 传递附加数据

FeatureRoute 支持使用 extras 属性传递附加数据。这允许您为路由定义多个 extra 数据条目，类似于处理参数的方式。

定义多个 extras

使用 extras 属性，这是一个 Map，每个键对应一个唯一的 extra 数据条目。

FeatureRoute(
  path: 'transactions',
  name: 'transactions',
  description: '交易页面',
  builder: (context, state) {
    final info = state.extra?['info'];
    return TransactionsPage(info: info);
  },
  extras: {
    'Transaction A': {'info': '附加数据 1'},
    'Transaction B': {'info': '附加数据 2'},
    // 更多条目...
  },
),

如何工作

• 路由生成：RouteDataProvider 将为每种参数和 extra 组合生成路由。
• 调整后的路由名称：路由名称和描述将包括 extra 键以确保唯一性。
• 导航：导航到这些路由时，相应的 extra 数据将通过 state.extra 传递。

示例：使用参数和 extras

FeatureRoute(
  path: 'investments/:companyID',
  name: 'investment',
  description: '投资页面',
  parameters: {
    'companyID': {
      '1': 'CompanyA',
      '2': 'CompanyB',
    },
  },
  extras: {
    'Transaction A': {'info': '附加数据 1'},
    'Transaction B': {'info': '附加数据 2'},
  },
  builder: (context, state) {
    final companyID = state.params['companyID']!;
    final companyName = getCompanyNameById(companyID);
    final info = state.extra?['info'];
    return InvestmentPage(
      companyID: companyID,
      companyName: companyName,
      info: info,
    );
  },
),

生成的路由名称：

• investment_CompanyA_Transaction A
• investment_CompanyA_Transaction B
• investment_CompanyB_Transaction A
• investment_CompanyB_Transaction B

5. 在构建器中访问 extra 数据

在路由的 builder 函数中，您可以通过 state.extra 访问 extra 数据。

builder: (context, state) {
  final info = (state.extra as Map<String, dynamic>?)?['info'];
  return SomePage(info: info);
},

7. 混合使用 FeatureRoute 和 GoRoute

由于 FeatureRoute 扩展了 GoRoute，您仍然可以使用 GoRoute 声明路由。但是请注意，由 Feature Navigator 提供的聊天机器人功能无法访问使用 GoRoute 定义的路由。为了充分利用聊天机器人功能，建议使用 FeatureRoute。

routes: [
  FeatureRoute(
    // ... FeatureRoute 定义...
  ),
  GoRoute(
    path: '/help',
    builder: (context, state) => const HelpPage(),
  ),
],

重要提示

• 聊天机器人无障碍访问：Feature Navigator 中的聊天机器人只能访问使用 FeatureRoute 定义的路由。使用 GoRoute 定义的路由将无法通过聊天机器人界面访问。
• 唯一路由名称：使用参数和 extra 时，路由名称会自动调整以包含参数值和 extra 键，以确保唯一性。
• 兼容性：由于 FeatureRoute 扩展了 GoRoute，您可以在应用程序中同时使用两者而没有任何问题。
• 控制聊天可见性：在 FeatureRoute 中使用 includeChat: false 隐藏特定页面上的聊天。

开发者

[@yunseoLee0343](/user/yunseoLee0343)	[@hin6150](/user/hin6150)

贡献

欢迎贡献！如果您想改进 Feature Navigator 包或修复错误，请提交拉取请求。我们建议在提交更改前创建一个议题或讨论您的想法。

如何贡献

1. ** Fork 仓库 **：克隆此仓库。
2. ** 创建分支 **：为您的功能或错误修复创建新分支。

   git checkout -b feature/new-feature
   

3. ** 提交更改 **：提交您的更改，并附上描述性的消息。

   git commit -m "添加新功能"
   

4. ** 推送到分支 **：将更改推送到分支。

   git push origin feature/new-feature