shimmer

套件介紹

根據套件公開資料產生的選型評估，僅供參考。

Shimmer 是一個 Flutter 套件，可簡化向 UI 元件新增閃爍載入效果的過程，創造出流暢、動畫化的佔位符外觀。它非常適合模擬清單、卡片或影像中的內容載入狀態，在資料取得期間提升使用者體驗。此套件支援所有主要平台，包括 Android、iOS、Web、macOS、Windows 和 Linux，確保在各裝置上行為一致。透過最少的設定，開發者可快速實作視覺上吸引人的載入指示器，無需撰寫複雜的動畫。

適用情境

列表中的載入佔位符
動畫卡片佔位符
圖像加載骨架
改進資料獲取過程中的使用者體驗
動態內容預覽

主要特色

簡單 API 結合
跨平台支援
可自定的閃爍顏色
流暢的動畫效果
輕量且高效

適合對象

尋求視覺精緻的UI設計師
開發動態內容螢幕的開發者
頻繁加載資料的應用
原型設計互動介面
提升感知性能

使用建議

不適用於靜態內容
需要在小部件樹中正確放置
如果過度使用，可能會影響效能
超出基本樣式的自訂功能有限
最佳搭配透明背景使用

原始 README

以下為關聯原始碼儲存庫的 README 原文快照，最新內容請造訪原始碼儲存庫。

A lightweight Flutter widget that paints a moving highlight over placeholder UI. Typical uses are skeleton screens while data loads, and a sliding highlight on a call to action.

Install

dependencies:
  shimmer: ^4.0.0
  material_ui: ^1.0.1

shimmer 4.0 uses Flutter's standalone material_ui package (Flutter 3.44+). Apps that still import package:flutter/material.dart can wrap those subtrees in MaterialUiCompatibilityBridge.

import 'package:material_ui/material_ui.dart';
import 'package:shimmer/shimmer.dart';

Usage

Skeleton placeholder

Shimmer.fromColors is the usual constructor. Build the child from solid shapes (Container, Row, Column). The gradient replaces those colors; transparent pixels stay transparent.

Shimmer.fromColors(
  baseColor: Colors.grey.shade300,
  highlightColor: Colors.grey.shade100,
  child: Column(
    children: [
      Container(height: 200, color: Colors.white),
      const SizedBox(height: 16),
      Container(height: 12, color: Colors.white),
      const SizedBox(height: 8),
      Container(height: 12, width: 200, color: Colors.white),
    ],
  ),
);

Dark theme:

Shimmer.fromColors(
  baseColor: Colors.grey.shade800,
  highlightColor: Colors.grey.shade600,
  child: placeholder,
);

Custom gradient

Use the default constructor when you need a RadialGradient, SweepGradient, or a LinearGradient that follows Theme.

Shimmer(
  gradient: LinearGradient(
    colors: [
      Theme.of(context).colorScheme.surfaceContainerHighest,
      Theme.of(context).colorScheme.surface,
      Theme.of(context).colorScheme.surfaceContainerHighest,
    ],
    stops: const [0.35, 0.5, 0.65],
  ),
  child: placeholder,
);

Direction, speed, and loops

Shimmer.fromColors(
  direction: ShimmerDirection.rtl,
  period: const Duration(milliseconds: 1200),
  loop: 0, // 0 = forever
  enabled: isLoading,
  baseColor: Colors.grey.shade300,
  highlightColor: Colors.grey.shade100,
  child: placeholder,
);

Parameter	Default	Role
`child`	required	Opaque area the highlight is blended onto
`gradient`	required*	Highlight colors (`fromColors` builds this for you)
`direction`	`ltr`	`ltr`, `rtl`, `ttb`, `btt`
`period`	`1500ms`	Duration of one pass
`loop`	`0`	Passes before stopping; `0` repeats forever
`enabled`	`true`	`false` pauses the animation

*Required on Shimmer(...). Shimmer.fromColors takes baseColor and highlightColor instead.

Performance

Wrap a list of placeholders in one Shimmer, not one Shimmer per row.
Keep child simple and static. Fancy widgets (images, text with decoration, elevation) often look wrong because the shader replaces their colors.
Toggle enabled to false when loading finishes so the ticker stops.

Example

The example/ app shows a loading list and a “slide to unlock” highlight. From the repository root:

cd example && flutter run

How it works

Shimmer drives an AnimationController and paints a ShaderMaskLayer over the child (BlendMode.srcIn). The highlight rectangle is three times the child size so the band can travel fully across the widget.

Project internals, tests, and further optimization notes live in docs/overview.md and docs/optimization.md.