搜索插件、代码仓与 APP 分类

flutter_floating_bottom_bar 封面
插件详情v3.1.0

flutter_floating_bottom_bar

一个 Flutter 包,允许显示一个浮动小部件,可用于标签栏、底部导航栏等。该小部件还能响应滚动事件。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
1.8万
喜欢数
371
Pub 分数
160

安装插件

flutter pub add flutter_floating_bottom_bar

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个 Flutter 包,提供浮动底部栏小部件,非常适合用作标签栏或底部导航栏。它会动态响应滚动事件,根据用户的滚动行为自动隐藏或显示。专为跨平台的无缝集成而设计,支持 Android、iOS、Web、macOS、Windows 和 Linux。该包通过保持导航的可访问性而不遮挡内容,提升了用户体验。轻量且可自定义,适用于需要直观底部导航和响应式行为的应用程序。

适合场景

  • 可滚动列表中的底部导航
  • 移动应用中的浮动标签栏
  • Web 应用程序中的响应式导航
  • 跨平台应用中的动态UI元素
  • 内容密集型界面中的增强用户体验

主要特点

  • 滚动感知的隐藏/显示
  • 跨平台兼容性
  • 可自定义外观
  • 与现有小部件的轻松集成
  • 支持多个平台

适合对象

  • 移动应用开发者
  • Web应用程序设计师
  • 跨平台 Flutter 项目
  • 以用户界面/用户体验为重点的开发
  • 包含大量可滚动内容的应用程序

使用建议

  • 可能需要额外的样式来实现复杂布局
  • 对超长列表的性能影响
  • 高级动画的自定义功能有限
  • 不适合用于静态导航栏
  • 在嵌套滚动视图中需要谨慎处理

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

Floating Bottom Bar

A Flutter package that floats any widget above your content and reacts to scrolling. Use it as a tab bar, bottom navigation bar, search bar, command surface, or any custom child.

Platform Pub Package License: MIT Donate

Issues dock AI prompt dock Basic TabBar
Issues dock AI prompt dock Basic TabBar
Minimal API Nested scroll Badged nav
Minimal API Nested scroll Badged nav
Custom transition
Custom transition

Why this package

  • Host any widget as the floating bar: TabBar, BottomBarItems, a search composer, or a custom Row.
  • Scroll detection is notification-based. Most setups need no ScrollController plumbing.
  • BottomBarLayout.adaptive(maxWidth: ...) fills the host width while keeping a hard cap for tablets, desktop, and wide layouts.
  • BottomBarBodyPadding reserves the bar's full measured footprint, including configured offset and bottom safe-area, so body content stays clear even while the bar is hidden.
  • BottomBarMotion() defaults to Motor-backed Cupertino spring motion with velocity-preserving redirects when scroll direction changes mid-animation.
  • Custom transitions are supported, but they must stay paint-only and preserve the child's layout footprint.
  • The hidden action is accessibility-safe by default: it is non-interactive and excluded from semantics while the bar is visible, keeps at least a 48x48 hit target when active, uses direction-aware icon/tooltip text, and defaults its glyph color to ColorScheme.onPrimary.
  • Reduced-motion environments snap directly to the final shown/hidden state.
  • BottomBarController supports imperative show/hide plus scrollToStart()/scrollToEnd(), including correct NestedScrollView boundary targeting.
  • Motion from the motor package is re-exported intentionally for BottomBarMotion.motor(...).

Install

Requires Dart >=3.12.0 and Flutter >=3.44.0.

See the 3.0.0 release notes for the complete list of new layout, scrolling, accessibility, and reliability improvements.

flutter pub add flutter_floating_bottom_bar
import 'package:flutter_floating_bottom_bar/flutter_floating_bottom_bar.dart';

Claude Code skill

If you use Claude Code, this repo ships a skill for integration, migration, and debugging help around this package.

Install by copying .claude/skills/flutter-floating-bottom-bar/ into your Claude skills directory.

Basic usage

BottomBar(
  layout: const BottomBarLayout.adaptive(maxWidth: 420),
  body: BottomBarBodyPadding(
    padding: const EdgeInsets.only(top: 24),
    child: ListView.builder(
      padding: const EdgeInsets.symmetric(horizontal: 16),
      itemCount: 50,
      itemBuilder: (_, index) => ListTile(title: Text('Item $index')),
    ),
  ),
  child: const Padding(
    padding: EdgeInsets.symmetric(horizontal: 16, vertical: 14),
    child: Row(
      mainAxisAlignment: MainAxisAlignment.spaceBetween,
      children: [
        Icon(Icons.home_rounded),
        Text('Floating bar'),
        Icon(Icons.search_rounded),
      ],
    ),
  ),
)

BottomBar needs two required arguments:

  • body: the subtree that emits ScrollNotifications.
  • child: the floating widget shown above that body.

The bar is stacked above the body, so use BottomBarBodyPadding when your body should reserve enough bottom space to stay clear of the bar.

Common recipes

Adaptive width + stable body padding

Use BottomBarLayout.adaptive(maxWidth: ...) to span narrow screens while stopping at a defined maximum on wide screens. Pair it with BottomBarBodyPadding when the body should reserve the full footprint.

BottomBar(
  layout: const BottomBarLayout.adaptive(maxWidth: 440),
  body: const BottomBarBodyPadding(
    child: CustomScrollView(
      slivers: [
        SliverAppBar(title: Text('Inbox')),
        SliverList.list(
          children: [
            ListTile(title: Text('Message 1')),
            ListTile(title: Text('Message 2')),
          ],
        ),
      ],
    ),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Compose')),
  ),
)

BottomBarScope.barHeight and BottomBarBodyPadding use the bar's measured layout footprint, not its animated transform. The reported value includes the bar height plus configured layout.offset and bottom safe-area when respectSafeArea is enabled.

Nested scroll views

BottomBarController.scrollToStart() always targets the minimum extent and scrollToEnd() always targets the maximum extent. In a NestedScrollView, the controller automatically chooses the correct coordinated boundary controller:

  • scrollToStart() drives the outer controller so pinned/expanded header slivers return to their true top state.
  • scrollToEnd() drives the inner controller so the body scrolls to the end and the header collapses naturally.

If your body emits unrelated notifications, use BottomBarScrollBehavior.predicate to filter them.

BottomBar(
  controller: controller,
  scrollBehavior: BottomBarScrollBehavior(
    predicate: (notification) => notification.depth == 0,
    showAtStart: true,
    showOnScrollEnd: true,
  ),
  body: NestedScrollView(
    headerSliverBuilder: (_, __) => const [
      SliverAppBar(
        pinned: true,
        expandedHeight: 180,
        flexibleSpace: FlexibleSpaceBar(title: Text('Nested scroll')),
      ),
    ],
    body: ListView.builder(
      itemCount: 100,
      itemBuilder: (_, index) => ListTile(title: Text('Row $index')),
    ),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Scroll-aware')),
  ),
)
Non-notification scroll sources (e.g. WebView)

BottomBar normally drives visibility from ScrollNotifications bubbled up from body. Some content — most notably an embedded WebView — scrolls internally without ever emitting one. For those cases, call BottomBarController.reportScroll from the WebView's own scroll callback:

controller.reportScroll(delta: newPixels - oldPixels);

This drives the same threshold/reverse/hideOnScroll visibility rules as body scrolling. It only affects visibility — scrollToStart()/scrollToEnd() still require a real ScrollPosition, which a WebView cannot provide.

Custom transitions

Custom transition builders must preserve the child's layout footprint. Use paint-only wrappers such as Opacity, Transform.translate, or Transform.scale.

Do not use layout-changing widgets such as SizeTransition or Align with a heightFactor; those break the stable footprint contract used by BottomBarScope.barHeight and BottomBarBodyPadding.

BottomBar(
  motion: BottomBarMotion(
    transitionBuilder: (context, animation, child) {
      final value = animation.value.clamp(0.0, 1.0);
      return Opacity(
        opacity: value,
        child: Transform.scale(
          scale: 0.92 + (0.08 * value),
          child: child,
        ),
      );
    },
  ),
  body: ListView.builder(
    itemCount: 100,
    itemBuilder: (_, index) => ListTile(title: Text('Row $index')),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Paint-only transition')),
  ),
)

Spring progress can overshoot. Clamp animation.value before using it for opacity or scale.

BottomBarItems and BottomBarItem

BottomBarItems is a row helper. BottomBarItem is an opinionated item widget with built-in accessibility and RTL-aware badge placement.

  • The badge uses PositionedDirectional, so it follows the top-end corner in both LTR and RTL layouts.
  • The item exposes button semantics, selection state, and enabled state.
  • The tappable surface keeps at least a 48x48 target.
  • Accessible naming is deterministic: semanticLabel wins, otherwise tooltip, otherwise descendant semantics.
  • When semanticLabel or tooltip provides the explicit accessible name, descendant semantics are excluded to avoid duplicate announcements.
  • In bounded rows wide enough for each item's 48x48 minimum target, BottomBarItems wraps every child in Expanded, so items share the row's width equally. Narrow bounded rows use a horizontal scroll view to preserve the minimum targets; unbounded rows keep their raw children.
  • A BottomBarItem's Text label (with non-null data) is truncated to a single line with an ellipsis. Text.rich and other label widgets are left untouched.
  • BottomBarItems.labelBehavior (BottomBarLabelBehavior.alwaysShow by default) controls when descendant labels render: alwaysShow, onlySelected, or alwaysHide. An item used outside a BottomBarItems row always shows its label.

Migration from v1.x

v1.x v2.x Migration
body: (context, controller) => Widget body: Widget Drop the builder. The bar listens to ScrollNotifications from descendant scrollables.
barColor removed Use BottomBarThemeData.barDecoration or theme:.
width, offset, borderRadius, barAlignment, fit, clip, respectSafeArea BottomBarLayout Move these into layout: BottomBarLayout(...). barAlignment became alignment.
duration, curve, start, end BottomBarMotion BottomBarMotion() now defaults to Cupertino spring motion. start/end became slideStart/slideEnd.
hideOnScroll, reverse, scrollOpposite, scrollDeltaThreshold BottomBarScrollBehavior Move these into scrollBehavior: BottomBarScrollBehavior(...). scrollDeltaThreshold became deltaThreshold.
iconWidth, iconHeight, iconDecoration, barDecoration BottomBarThemeData Move these to the theme or the theme: override.
BottomBarScrollControllerProvider BottomBarScope The old controller provider was replaced by BottomBarScope, which exposes barHeight and isVisible.

No backward-compatibility shim ships with v2.

API quick reference

BottomBar
Parameter Type Default Notes
child Widget required Floating content shown above the body.
body Widget required Descendant scrollables here drive hide/show via notifications.
controller BottomBarController? null Imperative show/hide/scroll API.
layout BottomBarLayout? null Falls back to theme layout, then const BottomBarLayout().
motion BottomBarMotion? null Falls back to theme motion, then const BottomBarMotion().
scrollBehavior BottomBarScrollBehavior? null Falls back to theme scroll behavior, then const BottomBarScrollBehavior().
theme BottomBarThemeData? null Per-instance theme overrides.
icon BackToTopIconBuilder? null Custom hidden action visual.
showIcon bool true Enables or removes the built-in hidden action.
iconSemanticLabel String? null Defaults to the direction-aware tooltip text.
iconTooltip String? null Defaults to Scroll to top or Scroll to bottom.

The hidden action is only interactive while the bar is hidden. While the bar is visible it is ignored for hit testing and removed from the semantics tree.

BottomBarLayout
Field Type Default Notes
width double 300 Requested bar width before viewport/max-width clamping.
maxWidth double? null Optional explicit width cap after host constraints.
offset double 10 Outer padding applied around the bar or hidden action.
borderRadius BorderRadius BorderRadius.circular(28) Matches the default Material 3 bar decoration; pass BorderRadius.zero for a square bar.
iconOffset Offset Offset.zero Extra translation applied only to the hidden action.
alignment Alignment Alignment.bottomCenter Shared alignment for the bar and hidden action.
fit StackFit StackFit.loose Host stack fit.
clip Clip Clip.hardEdge Host stack clip behavior.
respectSafeArea bool true Wraps the bar and hidden action in SafeArea.
avoidKeyboard bool true Pads the bar and hidden action by MediaQuery.viewInsets.bottom so they sit above the keyboard. No-op when insets are 0 (typical inside a Scaffold body).

Use BottomBarLayout.adaptive(maxWidth: ...) to fill available width up to a hard cap. When deriving layouts, copyWith(clearMaxWidth: true) explicitly removes an existing cap.

BottomBarMotion
Field Type Default Notes
mode BottomBarMotionMode cupertino BottomBarMotion() defaults to Cupertino spring mode.
duration Duration 500ms in default Cupertino mode Used for curved motion and scroll-to-boundary animation timing.
curve Curve Curves.easeOutCubic Used by curved motion and controller boundary scrolling.
cupertinoPreset BottomBarCupertinoMotion snappy Default Cupertino preset.
transition BottomBarTransition slide Built-in transition when transitionBuilder is null.
transitionBuilder Widget Function(BuildContext, Animation<double>, Widget)? null Overrides the enum. Must preserve layout footprint and stay paint-only.
slideStart Offset Offset(0, 2) Hidden offset for slide and slideAndFade.
slideEnd Offset Offset.zero Visible offset for slide and slideAndFade.

Reduced-motion environments snap to the target shown/hidden state instead of animating.

BottomBarScrollBehavior
Field Type Default Notes
hideOnScroll bool true Disables scroll-driven hiding when false.
reverse bool false Inverts the scroll direction that hides vs shows the bar.
scrollOpposite bool false Changes only the built-in hidden action direction, tooltip, and glyph. It does not change scrollToStart() or scrollToEnd().
deltaThreshold double 8 Minimum absolute delta required before visibility can flip.
showAtStart bool false Forces the bar visible when a scrollable reaches its minimum extent.
showOnScrollEnd bool false Forces the bar visible when scrolling settles.
keepVisibleOnFocus bool true Skip scroll-hide while the floating child has focus. BottomBarController.hide() still hides it.
predicate bool Function(ScrollNotification)? null Skip notifications entirely when it returns false.
BottomBarController
Member Notes
isVisible Tracks the currently attached bar's visibility.
isAttached Whether the controller is attached to a live bar.
show() / hide() / toggle() Imperative visibility controls.
scrollToStart() Always scrolls the last active scrollable to its minimum extent.
scrollToEnd() Always scrolls the last active scrollable to its maximum extent.
reportScroll(delta: ...) Drives visibility from a source that doesn't emit ScrollNotifications (e.g. WebView). Visibility only; doesn't affect scrollToStart/scrollToEnd.

A controller can own only one live bar at a time. Double-attach fails in both debug and release, and visibility updates are accepted only from the owning bar binding.

BottomBarScope

BottomBarScope exposes two listenables inside BottomBar.body:

  • barHeight: the live measured bar footprint, including offset and bottom safe-area when enabled.
  • isVisible: the current shown/hidden target state.

Use BottomBarBodyPadding when you want the common "reserve the bottom footprint for me" behavior without wiring your own ValueListenableBuilder.

Examples and demos

  • API recipes: EXAMPLES.md
  • Runnable demo app: example/
  • Demo entry point: example/lib/main.dart

Contributing

See CONTRIBUTING.md for setup, quality checks, and release dry-run steps.

Bugs or requests

Open an issue at https://github.com/codenameakshay/flutter-floating-bottom-bar/issues.

所属分类

依赖

依赖清单 2 项

源码仓库

使用此插件的项目