Wix React Native Navigation 7.7.0 栈顶栏按钮开发指南

Wix React Native Navigation 7.7.0 栈顶栏按钮开发指南

react-native-navigation A complete native navigation solution for React Native 项目地址: https://gitcode.com/gh_mirrors/re/react-native-navigation

栈顶栏按钮概述

在 Wix React Native Navigation 中，栈顶栏（TopBar）是导航栈的重要组成部分。开发者可以在顶栏的左右两侧添加功能按钮，这些按钮可以包含图标或文本，为用户提供快捷操作入口。

基础按钮配置

按钮配置通过 options 对象实现，与其他样式选项一样，可以通过 Navigation.mergeOptions 方法动态更新：

topBar: {
  rightButtons: [
    {
      id: 'searchBtn',
      icon: require('./search.png'),
      color: '#333333'
    }
  ],
  leftButtons: [
    {
      id: 'backBtn',
      icon: require('./back.png')
    }
  ]
}

平台差异注意事项

Android 平台特殊要求

1. 图标按钮必须同时提供 title 属性，该文本会在以下情况显示：

   • 按钮被折叠到溢出菜单时
   • 长按按钮时作为提示文本

2. 左侧按钮限制：

   • 仅支持单个按钮
   • 不支持纯文本按钮

iOS 平台建议

推荐将次要操作放入溢出菜单：

1. 添加菜单图标按钮
2. 点击时打开 ActionSheet 显示相关操作

高级按钮功能

自定义 React 组件按钮

当需要实现复杂交互时，可以使用 React 组件作为按钮视图：

1. 首先注册组件：

Navigation.registerComponent('CustomButton', () => require('./CustomButton'));

2. 在配置中使用：

topBar: {
  rightButtons: [
    {
      component: {
        name: 'CustomButton',
        passProps: {
          initialCount: 0
        }
      }
    }
  ]
}

动态更新组件属性

1. 为按钮分配唯一 ID：

{
  id: 'counterBtn',
  component: {
    name: 'CustomButton',
    passProps: {
      count: 0
    }
  }
}

2. 更新属性：

Navigation.updateProps('counterBtn', {
  count: 5
});

按钮动态管理

设置新按钮

会覆盖现有按钮配置：

Navigation.mergeOptions(componentId, {
  topBar: {
    rightButtons: [
      {
        id: 'refreshBtn',
        text: '刷新'
      }
    ]
  }
});

移除所有按钮

Navigation.mergeOptions(componentId, {
  topBar: {
    rightButtons: []
  }
});

最佳实践建议

1. 重要操作放在右侧主按钮区，次要操作放入菜单
2. 为所有按钮设置唯一 ID，便于后续管理
3. 考虑不同平台的视觉和交互差异
4. 复杂交互优先考虑自定义组件方案
5. 按钮状态变化时及时更新 UI

通过合理使用栈顶栏按钮，可以显著提升应用导航体验，同时保持界面整洁有序。

react-native-navigation A complete native navigation solution for React Native 项目地址: https://gitcode.com/gh_mirrors/re/react-native-navigation