ShowCaseView

一个Flutter包，可让您逐步展示/突出显示您的Widget。

预览

The example app running in IOS

1.0.0版本迁移指南

下表中提到的组件的属性/字段已重命名。

之前 之后
autoPlayLockEnable enableAutoPlayLock
shapeBorder targetShapeBorder
showcaseBackgroundColor tooltipBackgroundColor
contentPadding tooltipPadding
overlayPadding targetPadding
radius targetBorderRadius
tipBorderRadius tooltipBorderRadius
disableAnimation disableMovingAnimation
animationDuration movingAnimationDuration

移除了Showcase.withWidget()未使用的参数，如下所示

  • title
  • titleAlignment
  • titleTextStyle
  • 描述
  • descriptionAlignment
  • descTextStyle
  • textColor
  • tooltipBackgroundColor
  • tooltipBorderRadius
  • tooltipPadding

安装

  1. 将依赖项添加到 pubspec.yaml

    在pub.dev上的“安装”选项卡中获取最新版本 pub.dev

dependencies:
    showcaseview: <latest-version>
  1. 导入包
import 'package:showcaseview/showcase_tutorial.dart';
  1. 添加一个 ShowCaseWidget 小部件。

ShowCaseWidget(
  builder: Builder(
    builder : (context)=> Somewidget()
  ),
),
  1. 添加一个 Showcase 小部件。

GlobalKey _one = GlobalKey();
GlobalKey _two = GlobalKey();
GlobalKey _three = GlobalKey();

...

Showcase(
  key: _one,
  title: 'Menu',
  description: 'Click here to see menu options',
  child: Icon(
    Icons.menu,
    color: Colors.black45,
  ),
),

Showcase.withWidget(
  key: _three,
  height: 80,
  width: 140,
  targetShapeBorder: CircleBorder(),
  container: Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: <Widget>[
      ...
    ],
  ),
  child: ...,
),
  1. 开始 ShowCase

someEvent(){
    ShowCaseWidget.of(context).startShowCase([_one, _two, _three]);
}

如果您想在UI构建完成后立即启动 ShowCaseView，请使用以下代码。

WidgetsBinding.instance.addPostFrameCallback((_) =>
  ShowCaseWidget.of(context).startShowCase([_one, _two, _three])
);

ShowCaseWidget.of(context)函数

函数名 描述
startShowCase(List widgetIds) 开始展示
next() 开始下一个展示
previous() 开始上一个展示
dismiss() 关闭所有展示

ShowCaseWidget属性

名称 类型 默认行为 描述
blurValue 双精度 0 在叠加层上提供模糊效果
autoPlay 布尔值 假 自动显示下一个展示
autoPlayDelay 持续时间 Duration(milliseconds: 2000) 启用自动播放时，展示的可见时间
enableAutoPlayLock 布尔值 假 启用自动播放时，阻止用户与叠加层交互。
enableAutoScroll 布尔值 假 允许自动滚动到下一个展示，以使给定目标可见。
scrollDuration 持续时间 Duration(milliseconds: 300) 自动滚动的持续时间
disableBarrierInteraction 布尔值 假 禁用屏障交互
disableScaleAnimation 布尔值 假 禁用所有展示的缩放过渡
disableMovingAnimation 布尔值 假 禁用所有展示的弹跳/移动过渡
onStart Function(int?, GlobalKey)? 在每次展示开始时触发。
onComplete Function(int?, GlobalKey)? 在每次展示完成时触发。
onFinish VoidCallback? 当所有展示都完成后触发
enableShowcase 布尔值 真 全局启用或禁用展示。

Showcase和Showcase.withWidget属性

名称 类型 默认行为 描述 展示 ShowCaseWidget
key GlobalKey 每个展示的唯一全局键。 ✅ ✅
child Widget 您想展示的目标小部件 ✅ ✅
title String? 默认工具提示的标题 ✅
描述 String? 默认工具提示的描述 ✅
container Widget? 允许创建自定义工具提示小部件。 ✅
高度 double? 自定义工具提示小部件的高度 ✅
width double? 自定义工具提示小部件的宽度 ✅
titleTextStyle TextStyle? 标题的文本样式 ✅
descTextStyle TextStyle? 描述的文本样式 ✅
titleAlignment TextAlign TextAlign.start 标题的对齐方式 ✅
descriptionAlignment TextAlign TextAlign.start 描述的对齐方式 ✅
targetShapeBorder ShapeBorder 如果未提供targetBorderRadius参数，则它将形状边框应用于目标小部件 ✅ ✅
targetBorderRadius BorderRadius? 目标小部件的边框半径 ✅ ✅
tooltipBorderRadius BorderRadius? BorderRadius.circular(8.0) 工具提示的边框半径 ✅
blurValue double? ShowCaseWidget.blurValue 叠加层的模糊效果 ✅ ✅
tooltipPadding EdgeInsets EdgeInsets.symmetric(vertical: 8, horizontal: 8) 工具提示内容的内边距 ✅
targetPadding EdgeInsets EdgeInsets.zero 目标小部件的内边距 ✅ ✅
overlayOpacity 双精度 0.75 叠加层的不透明度 ✅ ✅
overlayColor 颜色 Colors.black45 叠加层的颜色 ✅ ✅
tooltipBackgroundColor 颜色 Colors.white 默认工具提示的背景色 ✅
textColor 颜色 Colors.black 工具提示文本的颜色 ✅
scrollLoadingWidget Widget 当启用autoScroll时，在叠加层上显示的加载小部件，直到活动展示在视口内可见。 ✅ ✅
movingAnimationDuration 持续时间 Duration(milliseconds: 2000) 此移动动画应持续的时间。 ✅ ✅
showArrow 布尔值 真 显示带箭头的工具提示 ✅
disableDefaultTargetGestures 布尔值 假 禁用目标小部件的默认手势 ✅ ✅
disposeOnTap bool? 假 点击目标/工具提示时关闭所有展示 ✅ ✅
disableMovingAnimation bool? ShowCaseWidget.disableMovingAnimation 禁用弹跳/移动过渡 ✅ ✅
disableScaleAnimation bool? ShowCaseWidget.disableScaleAnimation 禁用在展示开始和完成时的初始缩放过渡 ✅
scaleAnimationDuration 持续时间 Duration(milliseconds: 300) 缩放动画应持续的时间。 ✅
scaleAnimationCurve Curve Curves.easeIn 用于缩放动画的曲线。 ✅
scaleAnimationAlignment Alignment? 缩放发生的坐标原点，相对于框的大小。 ✅
onToolTipClick VoidCallback? 点击工具提示时触发。 ✅
onTargetClick VoidCallback? 点击目标小部件时触发 ✅ ✅
onTargetDoubleTap VoidCallback? 双击目标小部件时触发 ✅ ✅
onTargetLongPress VoidCallback? 长按目标小部件时触发 ✅ ✅
tooltipPosition TooltipPosition? 定义工具提示相对于目标小部件的垂直位置 ✅ ✅
titlePadding EdgeInsets? EdgeInsets.zero 标题的内边距 ✅
descriptionPadding EdgeInsets? EdgeInsets.zero 描述的内边距 ✅

如何使用

查看example目录中的示例应用程序或pub.dartlang.org上的“示例”选项卡以获取更完整的示例。

滚动到活动展示

自动滚动到活动展示的功能在按需渲染小部件的滚动视图中（例如ListView、GridView）将无法正常工作。

为了滚动到某个小部件，它需要附加到小部件树。因此，如果您使用的是按需渲染小部件的滚动视图，那么应用了展示的小部件可能未附加到小部件树。因此，Flutter将无法滚动到该小部件。

因此，如果您想创建一个包含较少子小部件的滚动视图，请优先使用SingleChildScrollView。

如果无法使用SingleChildScrollView，则可以将ScrollController分配给该滚动视图，并手动滚动到展示小部件渲染的位置。您可以在ShowCaseWidget的onStart方法中添加该代码。

例如，

// This controller will be assigned to respected sctollview.
final _controller = ScrollController();

ShowCaseWidget(
  onStart: (index, key) {
    if(index == 0) {
      WidgetsBinding.instance.addPostFrameCallback((_) {
       // If showcase widget is at offset 1000 in the listview.
       // If you don't know the exact position of the showcase widget,
       // You can provide nearest possible location.
       // 
       // In this case providing 990 instead of 1000 will work as well.
        _controller.jumpTo(1000);
      });
    }
  },
);

GitHub

查看 Github