Flutter应用内故事展示插件inappstory_plugin的使用

Flutter应用内故事展示插件inappstory_plugin的使用

安装

当前该插件还在开发中，并未发布。

在你的 pubspec.yaml 文件中添加依赖：

dependencies:
  ...
  inappstory_plugin: ^0.0.6
  ...

Android需求

确保更新你的 Android SDK 版本：

minSdkVersion = 23
compileSdkVersion = 34
targetSdkVersion = 34

初始化

使用你的 API 密钥初始化插件：

InappstoryPlugin().initWith('<your api key>', '<user id>', false);

使用

要使用该库，创建一个 YourStoryWidget 并实现 StoryWidget 接口：

class YourStoryWidget extends StatelessWidget implements StoryWidget {
  const YourStoryWidget(this.story, {super.key});
  ...
}

获取特定 feed 的故事组件：

InAppStoryPlugin().getStoriesWidgets(
  feed: '<your feed>',
  storyBuilder: <function returns Widget for Story>,
);

获取特定 feed 的故事组件并包含收藏项：

InAppStoryPlugin().getStoriesWidgets(
  feed: '<your feed>',
  storyBuilder: <function returns Widget for Story>,
  favoritesBuilder: <function returns Widget for in feed Favorites>,
);

完整示例

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final initialization = InappstoryPlugin().initWith('<your api key>', '<user id>', false);

  final flutterFeedStoriesWidgetsStream = InAppStoryPlugin().getStoriesWidgets(
    feed: 'flutter',
    storyBuilder: StoryWidgetSimpleDecorator.new,
    favoritesBuilder: GridFeedFavoritesWidget.new, // 可以为null
  );

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Column(
        children: [
          SizedBox(
            height: 150,
            child: StreamBuilder(
              stream: flutterFeedStoriesWidgetsStream,
              builder: (_, snapshot) {
                if (snapshot.hasError) return Text('${snapshot.error}');

                if (snapshot.hasData) {
                  return ListView.separated(
                    scrollDirection: Axis.horizontal,
                    itemBuilder: (_, index) => snapshot.requireData.elementAt(index),
                    separatorBuilder: (_, __) => const SizedBox(width: 12),
                    itemCount: snapshot.requireData.length,
                  );
                }

                return const LinearProgressIndicator();
              },
            ),
          ),
        ],
      ),
    );
  }
}

class StoryWidgetSimpleDecorator extends StatelessWidget implements StoryWidget {
  const StoryWidgetSimpleDecorator(this.story, {super.key});

  [@override](/user/override)
  final Story story;

  Image? get imageNullable {
    final imageFile = story.imageFile;

    if (imageFile == null) return null;

    return Image.file(imageFile);
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return StreamBuilder(
      stream: story.updates,
      builder: (_, __) {
        return ClipRRect(
          borderRadius: const BorderRadius.all(Radius.circular(10)),
          child: AspectRatio(
            aspectRatio: story.aspectRatio,
            child: GestureDetector(
              onTap: story.tap,
              child: Stack(
                children: [
                  Positioned.fill(
                    child: imageNullable ?? ColoredBox(color: story.backgroundColor),
                  ),
                  const Positioned.fill(
                    child: DecoratedBox(
                      decoration: BoxDecoration(
                        gradient: LinearGradient(
                          begin: Alignment.topCenter,
                          end: Alignment.bottomCenter,
                          colors: [
                            Colors.transparent,
                            Colors.black87,
                          ],
                        ),
                      ),
                    ),
                  ),
                  Align(
                    alignment: Alignment.bottomLeft,
                    child: Padding(
                      padding: const EdgeInsets.all(8.0),
                      child: Text(
                        story.title,
                        style: TextStyle(color: story.titleColor),
                      ),
                    ),
                  ),
                ],
              ),
            ),
          ),
        );
      },
    );
  }
}

获取收藏的故事

final favorites = InAppStoryPlugin().getFavoritesStoriesWidgets(
      feed: 'flutter',
      storyBuilder: StoryWidgetSimpleDecorator.new,
    ).asBroadcastStream();

外观管理器

故事阅读器外观

显示/隐藏按钮：

• 点赞/不喜欢
• 收藏
• 分享

AppearanceManagerHostApi().setHasLike(true);
AppearanceManagerHostApi().setHasFavorites(true);
AppearanceManagerHostApi().setHasShare(true);

故事阅读器关闭按钮位置

位置选项：

• topLeft
• topRight
• bottomLeft
• bottomRight

AppearanceManagerHostApi().setClosePosition(position)

故事阅读器计时器渐变

启用/禁用状态：

AppearanceManagerHostApi().setTimerGradientEnable(true)

获取状态：

final Future<bool> timerGradientEnabledFuture= AppearanceManagerHostApi().getTimerGradientEnable();

设置渐变颜色和位置：

const gradient = LinearGradient(colors: [Colors.purple, Colors.amber], stops: [0.1, 0.3]);

AppearanceManagerHostApi().setTimerGradient(
                        colors: gradient.colors.map((it) => it.value).toList(),
                        locations: gradient.stops ?? [],
                      );

故事阅读器背景

AppearanceManagerHostApi().setReaderBackgroundColor(Colors.green.value)

故事阅读器圆角半径

AppearanceManagerHostApi().setReaderCornerRadius(16); // int

单个故事API

通过 ID 显示单个故事：

IASSingleStoryHostApi().show(storyId: story.id, slide: 1);

如果用户还没有看过，则显示单个故事：

IASSingleStoryHostApi().showOnce(storyId: story.id);

监听回调结果：

class _WidgetState extends State<...> implements IShowStoryOnceCallbackFlutterApi {
  [@override](/user/override)
  void initState() {
    super.initState();
    IShowStoryOnceCallbackFlutterApi.setUp(this);
  }

  [@override](/user/override)
  void dispose() {
    IShowStoryOnceCallbackFlutterApi.setUp(null);
    super.dispose();
  }
  
  [@override](/user/override)
  void alreadyShown() => print('IShowStoryOnceCallback.alreadyShown()');

  [@override](/user/override)
  void onError() => print('IShowStoryOnceCallback.onError()');

  [@override](/user/override)
  void onShow() => print('IShowStoryOnceCallback.onShow()');
}

呼吁行动

添加/移除呼吁行动监听器：

1. 实现 CallToActionCallbackFlutterApi 接口。
2. 设置此监听器：

class _SimpleFeedExampleState extends State<SimpleFeedExampleWidget> implements CallToActionCallbackFlutterApi {
  [@override](/user/override)
  void initState() {
    super.initState();
    CallToActionCallbackFlutterApi.setUp(this); // 添加监听器
  }

  [@override](/user/override)
  void dispose() {
    CallToActionCallbackFlutterApi.setUp(null); // 移除监听器
    super.dispose();
  }

  final callsToAction = <String>[];

  [@override](/user/override)
  void callToAction(SlideDataDto? slideData, String? url, ClickActionDto? clickAction) {
    // 执行相关操作
  }
}