驚天秘密！如何在 Flutter 項目中實現操作引導
不要冒然評價我，你只知道我的名字，卻不知道我的故事，你只是聽聞我做了什麼，卻不知我經歷過什麼。
俗話說得好，產品有三寶，彈窗浮層加引導。
上圖截圖自我司 App 曉黑板中的口算模塊，相信每個 App 開發在工作中都碰到這種場景，為了避免用戶對新功能產生困惑，會對一些功能加一些引導操作。在原生開發中，例如 Android 開發中，我們可以使用 NewbieGuide 等開源庫來實現。但是很遺憾的是，在 Dart packages 中找了一圈，一無所獲。
但是我們還是很快就解決了問題，既然解決不了問題，我們就要學會讓這個問題不存在，這時候開發一寶就顯得尤其有用了。
本文完，大家下期再見👋
~
~
~
開個玩笑。真的猛男，敢於直面慘淡的人生，也敢於正視淋漓的鮮血，這區區需求怎麼能打倒我們。接下來我們開始琢磨一下這個引導操作要怎麼實現，相信各位小夥伴接到這個需求第一個想到的就是，這玩意兒不就是在整個頁面上面蓋一個蒙層，然後把中間再摳一塊出來。最後再加一些文字和一個下一步按鈕就行了嘛。你要是把這個需求想得這麼簡單，那你可就真是大對特對了。所以我們就按前面說的三步來實現這個東西。當然，你如果不想接着往下看的話，可以直接點擊這裡使用我們開發完成的引導組件庫來快速在你的 Flutter 項目中接入引導功能。
蓋個蒙層
那麼如何在 Flutter 頁面上蓋一個浮層呢？翻了一下 Flutter 的 API 文檔，找到了兩個法寶，分別是 Overlay 和 OverlayEntry。兩者的使用方法如下。
class _MyWidgetState extends State<MyWidget> {
OverlayEntry overlayEntry;
@override
Widget build(BuildContext context) {
return Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
RaisedButton(
onPressed: () {
/// 1. 創建一個 overlayEntry 實例，builder 方法返回一個 Widget
/// 該 Widget 會被渲染到頁面頂層
overlayEntry = OverlayEntry(
builder: (context) => Container(
color: Colors.white.withOpacity(.4),
child: Center(
child: RaisedButton(
onPressed: () {
/// 3. 執行 remove 方法銷毀 overlayEntry 實例
overlayEntry.remove();
},
child: Text('點我關閉 OverlayEntry'),
),
),
),
);
/// 2. 使用 OverlayState.insert 方法來顯示 overlayEntry
Overlay.of(context).insert(overlayEntry);
},
child: Text('點我康康 Overlay 的用法'),
),
],
),
);
}
}
如果你不嫌煩的話，還可以點擊這裡親自試一試效果。
中間摳一塊兒
上面解決了浮層問題，下面我們就來看一下如何讓蒙層中間某一塊區域亮起來的問題，這個問題很簡單，為什麼會亮，因為有光，怎麼有光。我想到了上帝，因為上帝說要有光，於是就有了光。
成為上帝 I（找到組件所在位置）
接下來就是如何成為上帝的第一步，我們要找到需要高亮的那個組件的大小和位置，經過我縝密的調查，發現在 Flutter 中可以通過 GlobalKey 來獲取一個元素的大小和位置，核心代碼如下：
/// 1. 聲明一個 globalKey
final globalKey = GlobalKey();
RaisedButton(
/// 2. 將 globalKey 綁定到組件上
key: globalKey,
onPressed: () {
///
},
child: Text(
'點我康康控制台輸出',
),
);
/// 3. 通過下面的代碼來獲取組件的尺寸和位置
RenderBox renderBox = globalKey.currentContext.findRenderObject();
Size size = renderBox.size;
Offset offset = renderBox.localToGlobal(Offset.zero);
print(size);
print(offset);
其中 Size 中有 width 和 height 屬性，分別表示高亮組件的寬高屬性，Offset 中有 dx 和 dy 屬性，分別表示組件左上角距離屏幕左側和頂部的距離。相信做 Web 開發的同學對這個都很熟悉了。
如果你不嫌煩的話，還可以點擊這裡親自試一試效果。
成為上帝 II（高亮組件所在區域）
我們已經在代碼層面定位到這個組件的位置了，接下來就是對該區域進行精準打擊，讓這塊區域不被浮層的顏色所覆蓋，請看成為上帝的第二步。
先看結果，可以看到中間的組件沒有被遮罩層遮住，但是有眼睛的同學可能會發現，為啥上下還會各有一段也沒被遮住，那是因為 RaisedButton 上下自帶一個 margin，所以代碼獲取 RaisedButton 的實際佔位比看起來要大，有興趣的同學可以去研究一下怎麼去掉這個 margin。又有同學會說了，為啥這個截圖是移動端的截圖，不是 Web 瀏覽器上的截圖。這個問題問得好，請看下面核心代碼。
OverlayEntry(
builder: (context) => Stack(
children: [
/// 我們使用了 ColorFiltered 來實現這個功能
ColorFiltered(
colorFilter: ColorFilter.mode(
/// 遮罩層顏色
Colors.red.withOpacity(.4),
BlendMode.srcOut,
),
child: Stack(
children: [
Container(
decoration: BoxDecoration(
/// 任何顏色均可
color: Colors.white,
backgroundBlendMode: BlendMode.dstOut,
),
),
Positioned(
/// 和需要高亮組件的大小和位置均一致
child: Container(
/// 任何顏色均可
color: Colors.white,
width: size.width,
height: size.height,
),
left: offset.dx,
top: offset.dy,
),
],
),
),
],
),
);
上面可以看到，我們使用了 Stack 和 Positioned 來實現將組件放到我們想要的位置，然後實現高亮的核心組件是 ColorFiltered，ColorFiltered 可太好了，我可太喜歡這個組件了，它能做的事情也很有趣，後面我們還再出一篇文章去單獨地介紹它。敬請期待叭~
然後說一說為啥我們的截圖是移動端，不再是 Web 端，因為 ColorFiltered 這哥們太強大，以至於 Flutter 團隊在 Flutter Web 上還沒有完全實現它。你可以在 Flutter 倉庫裏面的隨便找到不少關於 ColorFiltered 在 Web 上表現異常的 Issue。
當然如果你不嫌煩的話，而且也願意在 Web 上試一下沒有效果的效果，我也很貼心的為你準備了在線鏈接。
成為上帝 III（加上下一步按鈕和文字）
終於到了最後一步，加上下一步按鈕和文字，這就不用說了，創建 overlayEntry 的時候你願意在 builder 方法裏面返回啥都行。
那麼我還漏掉了什麼沒說呢？認真思考的同學可能想到，我要怎麼更新 overlayEntry 呢，引導頁一般有多個呀，我不能每次都 remove 掉當前的，然後再 insert 一個新的吧，那樣頁面肯定會有閃爍。其實如果認真看了OverlayEntry文檔的話肯定不會錯過這個 markNeedsBuild 方法。這裡就不再舉個例子了，我太懶了。總之就是如果 builder 的內容有變化，你對 overlayEntry 執行一次 overlayEntry.markNeedsBuild() 就可以了，Flutter 就會重新渲染一次 builder 返回的內容。以此來做到無閃爍切換引導頁。
相信完成了上面三步，我們即使沒有成為上帝，也能做到有光，讓指定區域高亮起來了。一句話總結：
我們使用了 Overlay 和 ColorFiltered 即完成了引導頁的製作
我看完了
耐心看完了的小夥伴肯定都覺得作者誠不欺我，確實很簡單，這兩個組件我都用過。但是：
So，我們貼心地開發了一個小的庫，並借鑒了 Web 端的知名引導庫 Intro.js 的名字，給它取名為 flutter_intro。
少廢話，先看東西。
上圖即為使用 flutter_intro 的默認主題可以快速實現的引導效果。那麼我要怎麼使用呢？首先在項目依賴文件 pubspec.yaml 中引入 flutter_intro。點擊這裡查看最新版本。
引入 Intro 並實例化一個對象
import 'package:flutter_intro/flutter_intro.dart';
/// 1. 引入 Intro，實例化一個對象，傳入必傳的 stepCount 參數
/// 和 widgetBuilder 參數，其中 widgetBuilder 可以使用庫內置的
/// 方法，這樣就只需傳入需要顯示的文本即可。
/// 當然如果你不嫌煩的話，也可以自己實現 widgetBuilder 方法
Intro intro = Intro(
/// 總共的引導頁數量，必傳
stepCount: 4,
/// 高亮區域與 widget 的內邊距
padding: EdgeInsets.all(8),
/// 高亮區域的圓角半徑
borderRadius: BorderRadius.all(Radius.circular(4)),
/// 使用庫默認提供的 useDefaultTheme 可以快速構建引導頁
/// 需要自定義引導頁樣式和內容，需要自己實現 widgetBuilder 方法
widgetBuilder: StepWidgetBuilder.useDefaultTheme(
/// 提示文本
texts: [
'你好呀，我是 Flutter Intro。',
'我可以幫你在 Flutter 項目中快讀實現 Step By Step 引導。',
'我的用法也十分簡單，你可以通過 example 和 api 文檔快速掌握和使用。',
'為了快速實現引導，我也默認提供了一套樣式，開箱即用，祝大家使用愉快，再見！',
],
/// 按鈕文字
btnLabel: '我知道了',
/// 是否在按鈕後顯示當前步驟
showStepLabel: true,
),
);
下圖為 flutter_intro 支持的一些參數配置所對應的位置介紹：
給需要加引導的的 Widget 綁定 globalKey
好熟悉的操作，和上面介紹的一模一樣。
當然，這裡為了方便大家使用，庫的內部為大家創建好了 globalKey，使用的時候只需要通過 intro.keys[下標] 獲取就行了。
Placeholder(
/// 2. 第一個引導頁即綁定 keys 中的第一項，以此內推
key: intro.keys[0]
)
真是太方便了！
全軍出擊
好了，我們已經做好全部的準備了。輸入以下指令，點擊運行。
intro.start(context);
沒了，是不是很簡單。
你這個太丑了
如果你嫌我的默認主題丑，想要自己實現 widgetBuilder 方法，我也可以接受。
final Widget Function(StepWidgetParams params) widgetBuilder;
該方法會在引導頁出現時由 flutter_intro 內部調用，並會將當前頁面上的一些數據通過參數的形式 StepWidgetParams 傳進來，最終渲染在屏幕上的為此方法返回的組件。
class StepWidgetParams {
/// 返回前一個引導頁方法，如果沒有，則為 null
final VoidCallback onPrev;
/// 進入下一個引導頁方法，如果沒有，則為 null
final VoidCallback onNext;
/// 結束所有引導頁方法
final VoidCallback onFinish;
/// 當前執行到第幾個引導頁，從 0 開始
final int currentStepIndex;
/// 引導頁的總數
final int stepCount;
/// 屏幕的寬高
final Size screenSize;
/// 高亮組件的的寬高
final Size size;
/// 高亮組件左上角坐標
final Offset offset;
}
StepWidgetParams 提供了生成引導頁所需要的所有參數，默認提供的主題也是基於此參數生成引導頁。
尾聲
天下沒有不散的筵席，但是如果你請客，我可以多陪你吃一會兒。
這篇文章主要介紹了如何在 Flutter 中實現操作引導，並且我們基於此封裝了一個我們眼裡東半球最好用的 flutter_intro。
對 Electron 感興趣？請關注我們的開源項目 Electron Playground，帶你極速上手 Electron。
我們每周五會精選一些有意思的文章和消息和大家分享，來掘金關注我們的 曉前端周刊。
我們是好未來 · 曉黑板前端技術團隊。
我們會經常與大家分享最新最酷的行業技術知識。
歡迎來 知乎、掘金、Segmentfault、CSDN、簡書、開源中國、博客園 關注我們。
