MarqueeR 是一個可自訂的 Flutter 小部件,支援平滑的多方向捲動文字,並具備使用者互動與程式控制功能。適合在有限空間中顯示長篇文字內容,提供彈性的動畫選項與跨平台的響應行為。此小部件設計直覺且高度可設定,讓開發者能調整捲動速度、方向與互動處理方式。它能在 Android、iOS、Web、macOS、Windows 與 Linux 上順暢運作,非常適合需要動態文字顯示的跨平台應用。
適用情境
顯示長標題或通知
創建動畫橫幅
實現滾動字幕
透過動態文字元素增強使用者介面
建構可存取的文字輪播
主要特色
多方向滾動(左、右、上、下)
對滾動狀態的程式化控制
使用者互動支援(點擊、拖曳)
可自訂的捲動速度與延遲
跨裝置的響應式設計
平滑的動畫過渡
適合對象
開發跨平台應用的開發者
需要動態文字效果的UI設計師
需要可存取滾動內容的應用程式
文字顯示空間有限的專案
互動式儀表板和自助服務終端
使用建議
可能影響非常長文字的效能
需要仔細調整捲動速度以確保可讀性
僅限文字內容(不含圖片或小工具)
不適合靜態或非滾動文字
最適合短到中等長度的字串
原始 README
以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。
The Marqueer package is a versatile Flutter widget designed to create smooth and customizable marquee effects. Whether you're building a news ticker, scrolling advertisements, or any animated content display, Marqueer offers flexibility, performance, and user interaction controls.
With support for infinite scrolling, dynamic item generation, and highly customizable animation behavior, Marqueer ensures an engaging and fluid user experience.
Package Features
Directional Scrolling: Scroll content in any direction—right-to-left, left-to-right, top-to-bottom, or bottom-to-top.
Infinite or Finite Scrolling: Display unlimited content or stop after a specific item count.
Customizable Speed: Control scroll speed with a pps (pixels per second) parameter.
Interactive Control: Pause and resume scrolling based on user interactions.
Dynamic Content: Use the builder constructor for generating items dynamically.
Responsive: Automatically adapts to screen size changes and other layout updates.
Stable Animation: Animation continues smoothly even when parent widget rebuilds via setState. Only restarts when pps, direction, or infinity parameters change.
Updated Infinity Behavior
infinity: When true, the widget creates an endless loop by either:
Duplicating the content after the original list ends and continuing seamlessly.
Reversing the animation direction when the list ends.
By adjusting the infinity parameter, you can control how the marquee behaves at its boundaries, ensuring a smooth experience regardless of content length.
Constructor Parameters
Core Parameters
direction: Defines the scroll direction. Options include:
rtl (Right-to-Left)
ltr (Left-to-Right)
ttb (Top-to-Bottom)
btt (Bottom-to-Top)
pps: Pixels per second, controlling the speed of the scroll animation. For instance, pps: 15.0 means 15 pixels are scrolled every second.
infinity: A bool determining how the scroll behaves after reaching the end of the list. When enabled, it either duplicates the content or reverses the animation.
autoStart: A bool controlling whether the marquee starts automatically when the widget is built.
Interactivity
interaction: If true, pauses the animation on user touch.
restartAfterInteraction: Automatically restarts scrolling after user interaction if enabled.
restartAfterInteractionDuration: Specifies the delay before restarting, e.g., Duration(seconds: 3).
Content Customization
separatorBuilder: Adds a separator widget between items in the marquee.
padding: Adds padding around the scrolling content.
Callbacks
onStarted: Triggered when the animation starts.
onStopped: Triggered when the animation stops.
onInteraction: Called when a user interacts with the marquee.
onChangeItemInViewPort: Invoked when a new item enters the viewport.
Advanced Control
controller: An optional MarqueerController to programmatically control the marquee (e.g., start, stop, change direction, or animate to position).
edgeDuration: Adds a delay when the marquee reaches the edges, useful in finite scrolling scenarios.
clipBehavior: Controls how the content is clipped. Default is Clip.hardEdge.
intrinsicCrossAxisSize: Auto-sizes the cross axis based on child widget. No need for SizedBox wrapper. Default is false.
Controller Methods
start(): Starts the marquee animation
stop(): Stops the marquee animation
forward(): Starts forward animation (left to right or bottom to top)
backward(): Starts backward animation (right to left or top to bottom)
animateTo(position, duration, curve): Animates to a specific scroll position
interactionEnabled(enabled): Enables or disables user interaction
recalculateIntrinsicSize(): Recalculates intrinsic size when child content changes
isAnimating: Returns the animation status (requires single attached widget)
scrollablePointerIgnoring
The scrollablePointerIgnoring parameter is a boolean that resolves gesture-related issues caused by Flutter's default IgnorePointer behavior within Scrollable widgets. When set to true, it ensures that the IgnorePointer behavior in nested scrollable elements is bypassed, allowing gestures to propagate correctly.
Why Use This?
Flutter's Scrollable widget applies an IgnorePointer by default to prevent unintended interactions during animations. However, this can interfere with custom gestures or user interactions in certain scenarios. Enabling scrollablePointerIgnoring ensures smooth and predictable gesture handling.
Default Behavior
false: The default IgnorePointer behavior remains active.
true: Disables the default IgnorePointer behavior, allowing gestures to work as expected.
final controller = MarqueerController();
/// controller.start()/// controller.stop()/// controller.forward()/// controller.backward()/// controller.animateTo(position, duration: duration, curve: curve)/// controller.interactionEnabled(false)SizedBox(
height: 30,
child: Marqueer(
pps: 100,
/// optional
controller: controller,
/// optional
direction: .rtl,
/// optional
restartAfterInteractionDuration: constDuration(seconds: 6),
/// optional
restartAfterInteraction: false,
/// optional
onChangeItemInViewPort: (index) {
print('item index: $index');
},
onInteraction: () {
print('on interaction callback');
},
onStarted: () {
print('on started callback');
},
onStopped: () {
print('on stopped callback');
},
child: constText(
'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer pretium massa mollis lorem blandit imperdiet. Nulla mattis vitae mauris vel condimentum. Nam posuere, augue vitae lobortis consequat, odio ante condimentum est, at maximus augue purus id metus. Curabitur condimentum aliquet ante at aliquet. Quisque vel massa congue, bibendum leo sodales, malesuada ante. Maecenas sed tortor quis ipsum dictum sollicitudin.',
),
),
);