Onboarding包及其组件

我们在上一章回中介绍了"Onboarding简介"相关的内容，本章回中将介绍Onboarding包的用法.闲话休提，让我们一起Talk Flutter吧。

1. 知识回顾

我们在上一章回中简单地介绍了Onboarding包，主要介绍了包中Onboarding和OnboardingStep两个组件的属性和用法，并且分享了一些使用时的注意事项。本章回
中将综合使用这两个组件实现首次使用App时的引导功能。

2. 使用方法

• 创建FocusNode类型的List,List的大小是OnboardingStep的数量；
• 创建Onboarding组件，并且把某个页面的Scaffold组件赋值给它的child属性；
• 创建多个OnboardingStep组件，并且把它们赋值给Onboarding组件的steps属性；
• 在Scaffold组件表示的页面中添加OnboardingStep组件，添加到某个功能组件上就可以；
• 在Scaffold组件表示的页面中启动Onboarding功能，通常是在initState方法中启动；
• 在Onboarding组件的onChanged中关闭最后一个OnboardingStep组件；
  上面介绍的方法中需要使用GlobalKey<OnboardingState>类型的对象，通过该对象来显示和关闭OnboardingStep组件，我们将在后面的示例代码中演示。

3. 示例代码

class _ExOnboardingOverlayState extends State<ExOnboardingOverlay> {
  final GlobalKey<OnboardingState> onboardingKey = GlobalKey<OnboardingState>();
  final GlobalKey<ScaffoldState> scaffoldKey = GlobalKey<ScaffoldState>();

  ///这个FocusNode相当于OnboardingStep的key，它把页面中的功能和OnboardingStep关联起来
  var focusNodeList = List<FocusNode>.generate(5,
          (index) => FocusNode(debugLabel: "FocusNode $index",),
      growable: false,
    );

  @override
  void initState() {
    super.initState();

    Future.delayed(const Duration(seconds: 1,),() {
        onboardingKey.currentState?.showWithSteps(0, [0,1,2]);
    });

  }
  @override
  Widget build(BuildContext context) {
    return Onboarding(
      key: onboardingKey,
      autoSizeTexts: true,
      ///这个会在body外层显示一个红色方框，不能打开，使用默认的false就可以
      debugBoundaries: false,
      ///这里只处理最后一个索引时关闭模糊显示，从一个step到下一个step中跳转是控件
      ///自己在处理，不需要添加任何事件
      onChanged: (index) {
        if(index == 2) {
          onboardingKey.currentState?.hide();
        }
      },
      steps: [
        OnboardingStep(focusNode: focusNodeList[0],
          titleText: "FocusNode 1 title",
          bodyText: "FocusNode 1 body",
          hasArrow: true,
          hasLabelBox: true,
          arrowPosition: ArrowPosition.autoVertical,
          fullscreen: true,
        ),
        OnboardingStep(focusNode: focusNodeList[1],
          ///stepBuilder中没有内容时显示title和body，有内容则优先显示stepBuilder中的内容
          ///这两个内容可以看作是对模糊层上高亮内容的解释，写任意一个就行
          titleText: "FocusNode 2 title",
          bodyText: "FocusNode 2 body",
          ///这两个颜色默认都是白色
          titleTextColor: Colors.blue,
          bodyTextColor: Colors.yellow,
          ///配置body外层的边框和内边距
          labelBoxPadding: const EdgeInsets.all(8,),
          ///需要添加默认的边框相当于是透明的，什么也没有
            ///如果设置了stepBuilder这个边框也会显示在它的外层
          labelBoxDecoration: BoxDecoration(
            color: Colors.orange,
            shape: BoxShape.rectangle,
            borderRadius: BorderRadius.circular(16),
          ),

          ///模糊层的颜色
          overlayColor: Colors.purpleAccent,
          ///只有fullscreen属性设置为false后才有效果,而且是从左上角开始呈现放射形状
          // overlayShape: const RoundedRectangleBorder(
          //   borderRadius: BorderRadius.all(Radius.circular(30.0),),
          // ),
          // overlayShape:const CircleBorder(),
          ///模糊层上高亮显色内容的形状，默认是矩形
          // shape: CircleBorder(
          // ),
          ///模糊层上高亮显色内容的内边距
          // margin: EdgeInsets.only(left: 90,),
          ///只有labelBoxDecoration赋值后才有效果
          hasArrow: true,
          hasLabelBox: true,
          ///body外层窗口的箭头位置
          arrowPosition: ArrowPosition.topCenter,
          ///设置成translucent后点击模糊区域无法跳转到下一个step,这个属性的值有多种，功能不同，
            ///主要用来控制在哪里响应点击事件，功能值可以查看官方文档
          overlayBehavior: HitTestBehavior.translucent,
          fullscreen: true,
          onTapCallback: (TapArea area, VoidCallback next, VoidCallback close){
          ///它的值分三种：hole:就是模糊层上高亮部分，overlay:就是模糊层, label：就是文本部分
          debugPrint("onTapCallback: area:$area");

          },
          ///如果觉得只两个title和body两个文本比较简单，可以实现此属性，它主要用来实现自定义的内容
          ///不过该内容仍然会包含在body的边框中，可以通过labelBoxDecoration修饰边框的颜色，圆角等风格
          stepBuilder: (context,renderInfo) {
          ///建议通过容器类组件控制大小，不然会铺满整个屏幕
          return Container(
            color: Colors.lightGreenAccent,
            height: 320,
            width: 300,
            child: Column(
              children: [
                ///这两个文本就是titleText和bodyText中的内容,不过字体比较大
                Text(renderInfo.titleText),
                Text(renderInfo.bodyText),
                ElevatedButton(
                  onPressed: () {
                    debugPrint("next: :${renderInfo.nextStep.toString()}");
                    renderInfo.nextStep();
                  },
                  child: const Text("Next"),
                ),
                ElevatedButton(
                  onPressed: () => renderInfo.close(),
                  child: const Text("Stop"),
                ),
              ],
            ),
          );
          }
        ),
        OnboardingStep(focusNode: focusNodeList[2],
          titleText: "FocusNode 3 title",
          bodyText: "FocusNode 3 body",
          hasArrow: true,
          hasLabelBox: true,
          arrowPosition: ArrowPosition.autoVertical,
          fullscreen: true,
        ),

      ],
      child: Scaffold(
        key: scaffoldKey,
        appBar: AppBar(
          title: const Text("Example of onboardingOverlay"),
          actions: [
            Focus(
              focusNode: focusNodeList[0],
                child: const Text("show focus"),
            ),
          ],
        ),
        body: Column(
          children: [
            const Text("body of scaffold "),
            IconButton(onPressed: (){
              onboardingKey.currentState?.show();
            }, icon: const Icon(Icons.delete),focusNode: focusNodeList[1],),
            Focus(
              focusNode: focusNodeList[2],
              child: const Text("show focus"),
            ),
          ],
        ),
      ),
    );
  }
}

上面的示例代码完全按照实现方法中的步骤编写，而且内容比较完整。编译并且运行上面的代码，可以看到位于AppBar中的功能介绍，点击模糊层后可以切换到下一个功
能介绍，直到最后一个功能介绍时停止功能介绍页面，恢复到正常页面。示例代码中一共三个功能介绍(OnboardingStep)，大家可以自己动手多添加几个功能介绍，至、
于功能介绍在页面中的位置取决于需求，这个没有特殊要求，大家放到自己想要的位置就可以。
示例代码中的第二个OnboardingStep没有使用默认的功能提示窗口，而是自己定义了一个窗口组件，它主要使用组件的stepBuilder和overlayBehavior属性,代
码中只是一个示例，大家可以参考该示例的代码，然后把它修改成自己定制的组件。

4. 内容总结

最后，我们对本章回的内容做一个全面的总结：

• OnboardingStep主要用来实现功能提示，它自带一个带箭头指示的窗口，可以满足大部分的需求；如果有特殊的需求可以通过它的stepBuilder属性自定义组件；
• Onboarding通过steps属性存放所有的OnboardingStep组件,并且通过OnboardingState类型的Globalkey显示和隐藏OnboardingStep组件；
• Onboarding组件提供了overlayColor箸属性来控制模糊层的颜色和透明度；
• Onboarding组件相当于在整个Scaffold页面外层包裹了一层模糊层，因此通过把某个页面的Scaffold组件赋值它的child属性；

看官们，与"onBoarding包用法"相关的内容就介绍到这里，欢迎大家在评论区交流与讨论!