DEV Community: Ge Ji

KotlinLesson 2: Kotlin Basic Syntax: Mastering Variables, Data Types, and Operators

Ge Ji — Wed, 20 Aug 2025 14:58:12 +0000

In the previous lesson, we set up our Kotlin learning environment and completed our first program. This lesson will delve into the core of Kotlin's basic syntax—variables, data types, and operators. These form the foundation of any programming language, and mastering them will enable you to write functional code, laying the groundwork for learning concepts like functions and classes in subsequent lessons.

I. Variables and Constants: "Data Containers" in Programs

Variables and constants are basic units for storing data. Kotlin makes a strict distinction between "mutability" and "immutability," which is an important difference from other languages like Python.

1. var (Mutable Variables) and val (Immutable Constants)

In Kotlin, variables are declared using var and val, with the key difference being whether they can be reassigned:

var (short for variable): Declares a mutable variable that can be reassigned after initialization;
val (short for value): Declares an immutable constant that cannot be reassigned after initialization (similar to final in Java).

// Mutable variable: can be reassigned
var age = 20
age = 21  // Valid, var allows modification

// Immutable constant: cannot be modified after initialization
val name = "Kotlin"
// name = "Java"  // Compilation error! val does not allow reassignment

Best Practice: Prefer val and use var only when modification is truly necessary. This reduces "unexpected changes" in code, making programs more stable and maintainable (especially in multi-threaded scenarios).

2. Two Ways to Declare Variables: Explicit Typing vs. Type Inference

Kotlin is a statically typed language but supports "type inference," eliminating the need to explicitly specify variable types every time:

Explicit typing: Format is var/val variableName: Type = value, clearly telling the compiler the variable's type;
Type inference: Format is var/val variableName = value, where the compiler automatically infers the variable type from the assigned value.

// Explicit type specification
var score: Int = 95
val pi: Double = 3.14159

// Type inference (recommended)
var height = 175  // Compiler automatically infers Int type
val isStudent = true  // Automatically infers Boolean type

Note: Type inference only works when a value is assigned during declaration. If declaring without an initial value (delayed initialization), you must explicitly specify the type:

var address: String  // Delayed initialization, type must be explicitly specified
address = "Chaoyang District, Beijing"  // Assignment later

3. Variable Scope: The "Effective Range" of Variables

A variable's scope refers to the range of code where it can be accessed. In Kotlin, there are mainly local variables and global variables:

(1) Local Variables

Variables defined inside functions or code blocks (like if or for blocks) that are only valid within their containing block:

fun printMessage() {
    // Local variable inside function, only accessible in printMessage()
    val message = "Hello, Local Variable"
    println(message)
}

fun main() {
    printMessage()
    // println(message)  // Compilation error! message is a local variable of printMessage()
}

(2) Global Variables

Variables defined at the top level of a file (not belonging to any function or class) that can be accessed throughout the file or class:

// Global variable at file level, accessible throughout the file
val globalVersion = "1.0.0"

fun checkVersion() {
    println("Current version: $globalVersion")  // Can directly access global variable
}

fun main() {
    checkVersion()  // Output: Current version: 1.0.0
}

Note: Global variables occupy memory continuously and should be used sparingly. Prefer local variables and follow the "minimum scope principle."

II. Basic Data Types: Kotlin's "Data Building Blocks"

Kotlin provides a rich set of basic data types for storing different kinds of data. Unlike Java, Kotlin's basic data types are not "primitive types" (like int) but "object types," while still maintaining efficient performance (optimized to primitive types during compilation).

1. Numeric Types: "Toolkit" for Storing Numbers

Kotlin offers 6 numeric types, ordered by precision and range from smallest to largest:

Type	Bits	Range	Example Usage
Byte	8	-128 ~ 127	Storing small integers (saves space)
Short	16	-32768 ~ 32767	Medium-range integers
Int	32	-2^31 ~ 2^31-1（约 -21 亿～21 亿）	Regular integers (default preference)
Long	64	-2^63 ~ 2^63-1（约 -900 亿亿～900 亿亿）	Large integers
Float	32	Single-precision floating point (~±3.4e38, 7 significant digits)	Decimals with low precision requirements
Double	64	Double-precision floating point (~±1.8e308, 15 significant digits)	High-precision decimals (default preference)

Usage Notes:

When declaring Long types, append L suffix: val bigNum: Long = 10000000000L;
When declaring Float types, append F suffix: val pi: Float = 3.14F;
Integers default to Int type, decimals default to Double type.

val b: Byte = 127
val s: Short = 32000
val i = 1000  // Defaults to Int
val l = 10000000000L  // Long type must have L suffix
val f = 3.14F  // Float type must have F suffix
val d = 3.14159  // Defaults to Double

2. Character Type Char: "Container" for Single Characters

Char is used to store single characters, enclosed in single quotes '. There are specific rules to note regarding its interaction with numbers:

Kotlin allows Char types to be added to numbers when the Char is on the left side (the compiler automatically converts Char to its corresponding ASCII code for calculation), but does not allow numbers to be added to Char when the number is on the left side. This is a special rule in Kotlin syntax.

val c1: Char = 'A'  // English character
val c2: Char = '中'  // Chinese character (supports Unicode)
val c3: Char = '\u0041'  // Unicode representation (corresponds to 'A')

// Special syntax rule: Char can be added to numbers when on the left
val y1 = 'A' + 1  // Valid, result is 'B' (ASCII code for 'A' is 65, +1 = 66, which is 'B')

// Numbers cannot be added to Char when on the left
// val y2 = 1 + 'A'  // Compilation error! Kotlin does not allow numbers on left to add with Char directly

To convert a Char to its corresponding ASCII code, explicitly call the toInt() method, which allows correct calculation regardless of order:

val charCode = 'A'.toInt()  // Convert to ASCII code 65
val sum = 1 + charCode  // Valid, result is 66
println(sum.toChar())  // Output: 'B'

3. Boolean Type: "Switch" for Logical Judgments

Boolean represents logical values with only two possible values: true (true) and false (false), mainly used for conditional judgments (like if statements).

val isReady = true
val hasError = false

// Example of logical judgment
if (isReady) {
    println("Ready")
} else {
    println("Not ready")
}

III. String Type Detailed Explanation: "Powerful Tool" for Text Processing

Strings (String) are used to store text and are one of the most commonly used data types in programming. Kotlin offers flexible support for strings with various convenient operations.

1. String Creation: Single-line and Multi-line

Kotlin supports two ways to create strings:

Single-line strings: Enclosed in double quotes "", content is within one line;
Multi-line strings: Enclosed in triple quotes """, can contain line breaks directly and preserve formatting (no need for \n escape characters).

// Single-line string
val singleLine = "This is a single-line string"

// Multi-line string (preserves line breaks and indentation)
val multiLine = """
    First line
    Second line
    Third line
""".trimIndent()  // trimIndent() removes extra leading indentation from each line

println(multiLine)
// Output:
// First line
// Second line
// Third line

Note: Multi-line strings preserve leading indentation by default. The trimIndent() method automatically removes this extra indentation for cleaner output.

2. String Concatenation: Two Ways to Connect Text

There are two common methods for concatenating strings:

+ operator: Directly use + to connect strings and other data types;
String templates: Use $ to reference variables or expressions, which is more concise and efficient.

val name = "Kotlin"
val version = 1.9

// + operator concatenation (more cumbersome)
val info1 = "Programming language: " + name + ", Version: " + version
println(info1)  // Output: Programming language: Kotlin, Version: 1.9

// String template (recommended)
val info2 = "Programming language: $name, Version: $version"
println(info2)  // Output: Same as above

// Using expressions in templates (needs ${})
val a = 10
val b = 20
val sumStr = "Sum of two numbers: ${a + b}"  // Result of expression a + b will be inserted
println(sumStr)  // Output: Sum of two numbers: 30

Advantage: String templates are more efficient than + concatenation (avoiding creation of excessive temporary strings) and make code more readable.

3. Common String Methods: "Toolkit" for Text Processing

Kotlin's String class provides numerous methods. Here are the most commonly used ones:

Method Name	Description	Example
`length`	Gets string length (number of characters)	`"hello".length → 5`
`substring(start, end)`	Extracts substring (from start to end-1)	`"Kotlin".substring(1, 4) → "otl"`
`equals(other)`	Checks if content equals (structural equality)	`"a".equals("A") → false`
`compareTo(other)`	Compares strings (lexicographical order)	`"apple".compareTo("banana") → negative`
`startsWith(prefix)`	Checks if starts with specified prefix	`"Kotlin".startsWith("Ko") → true`
`endsWith(suffix)`	Checks if ends with specified suffix	`"Kotlin".endsWith("lin") → true`
`trim()`	Removes leading and trailing whitespace	`" hello ".trim() → "hello"`
`split(delimiter)`	Splits string into list by delimiter	`"a,b,c".split(",") → ["a", "b", "c"]`

val str = "  Kotlin Programming  "

println(str.length)  // Output: 20 (including leading and trailing spaces)
println(str.trim())  // Output: "Kotlin Programming" (spaces removed)
println(str.startsWith("Ko"))  // Output: false (original string has leading space)
println(str.trim().startsWith("Ko"))  // Output: true (after trimming)
println(str.substring(2, 8))  // Output: "Kotlin" (extracts characters from index 2 to 7)

IV. Operators and Expressions: "Rules" for Data Operations

Operators perform operations on data, and when combined with variables and constants, form expressions (code fragments with return values). Most of Kotlin's operators are similar to Java's, with some subtle differences.

1. Arithmetic Operators: Handling Numeric Calculations

Operator	Function	Example
`+`	Addition	`5 + 3 → 8`
`-`	Subtraction	`5 - 3 → 2`
`*`	Multiplication	`5 * 3 → 15`
`/`	Division	`5 / 2 → 2`（integer division）
`%`	Modulus (remainder)	`5 % 2 → 1`
`++`	Increment	`var a=1; a++ → 2`
`--`	Decrement	`var b=3; b-- → 2`

Notes:

Integer division (/) automatically discards the decimal part (e.g., 5 / 2 = 2 rather than 2.5);
Difference between prefix and postfix increment/decrement (++/--):
- a++: Uses a's value first, then increments;
- ++a: Increments first, then uses a's value.

val num1 = 10
val num2 = 3

println(num1 + num2)  // 13
println(num1 - num2)  // 7
println(num1 * num2)  // 30
println(num1 / num2)  // 3 (integer division, decimal discarded)
println(num1.toDouble() / num2)  // 3.333... (division after converting to Double)
println(num1 % num2)  // 1 (10 divided by 3 leaves remainder 1)

var count = 5
println(count++)  // Outputs 5 (uses then increments)
println(count)    // Outputs 6

var score = 80
println(++score)  // Outputs 81 (increments then uses)
println(score)    // Outputs 81

2. Assignment Operators: Assigning Values to Variables

The basic assignment operator is =, with additional compound assignment operators (combining arithmetic operations and assignment):

Operator	Equivalent Expression	Example
`=`	Direct assignment	`a = 5`
`+=`	`a = a + b`	`a += 3 → a = a + 3`
`-=`	`a = a - b`	`a -= 2 → a = a - 2`
`*=`	`a = a * b`	`a = 4 → a = a 4`
`/=`	`a = a / b`	`a /= 2 → a = a / 2`
`%=`	`a = a % b`	`a %= 3 → a = a % 3`

var x = 10

x += 5   // Equivalent to x = x + 5 → x = 15
x *= 2   // Equivalent to x = x * 2 → x = 30
x -= 8   // Equivalent to x = x - 8 → x = 22
println(x)  // Output: 22

3. Comparison Operators: Judging Data Relationships

Comparison operators determine relationships between two data items, returning Boolean values (true or false).

Operator	Description	Example
`==`	Checks content equality (structural)	`"abc" == "abc" → true`
`!=`	Checks content inequality	`5 != 3 → true`
`>`	Greater than	`10 > 5 → true`
`<`	Less than	`10 < 5 → false`
`>=`	Greater than or equal to	`5 >= 5 → true`
`<=`	Less than or equal to	`3 <= 2 → false`
`===`	Checks reference equality	(See explanation below)

Key Difference: == vs ===

==: Checks "structural equality" (whether content is the same), equivalent to Java's equals() method;
===: Checks "reference equality" (whether they point to the same object in memory), equivalent to Java's == operator.

val str1 = "Hello"
val str2 = "Hello"
val str3 = String("Hello".toCharArray())  // Creates new string object with same content

println(str1 == str2)   // true (same content)
println(str1 == str3)   // true (same content)
println(str1 === str2)  // true (Kotlin string constant pool optimization, same reference)
println(str1 === str3)  // false (str3 is new object, different reference)

4. Logical Operators: Combining Conditional Judgments

Logical operators connect multiple boolean expressions for complex logical judgments:

Operator	Description	Example
`&&`	Logical AND (short-circuit)	`true && false → false`
\|\|	Logical OR (short-circuit)	`true`\|\|`false → true`
`!`	Logical NOT	`!true → false`

Short-circuit Characteristics:

&&: If the left expression is false, the right expression will not execute (since overall result is already false);
||: If the left expression is true, the right expression will not execute (since overall result is already true).

val hasMoney = true
val hasTime = false

// Logical AND: returns true only if both conditions are true
val canBuy = hasMoney && hasTime
println(canBuy)  // false (hasTime is false)

// Logical OR: returns true if at least one condition is true
val canRelax = hasMoney || hasTime
println(canRelax)  // true (hasMoney is true)

// Logical NOT: negation
val isPoor = !hasMoney
println(isPoor)  // false

// Short-circuit example
var count = 0
val result = false && (count++ > 0)  // Left is false, right doesn't execute
println(count)  // 0 (count not incremented)

V. Type Conversion: "Bridge" Between Different Data Types

Kotlin does not support "implicit type conversion" (like Java's automatic conversion from int to long). You must explicitly call conversion methods. Each basic type provides methods to convert to other types (e.g., toInt(), toDouble()).

val numInt: Int = 100
// val numLong: Long = numInt  // Compilation error! Kotlin doesn't allow implicit conversion

val numLong: Long = numInt.toLong()  // Correct: explicitly convert to Long
val numFloat: Float = numInt.toFloat()  // Convert to Float
val numStr: String = numInt.toString()  // Convert to string

// String to number (ensure string contains valid number)
val str = "123"
val strToInt = str.toInt()  // Convert to Int
val strToDouble = str.toDouble()  // Convert to Double

Note: Converting a string to a number will throw a NumberFormatException if the content isn't a valid number (e.g., "abc"). We'll cover handling such exceptions in later lessons.

VI. Practical Exercise: "Mini Project" to Reinforce Basics

To help you consolidate what you've learned, let's write a simple "personal information card" program that integrates variables, data types, and operators:

fun main() {
    // 1. Define personal information variables
    val name = "Zhang San"
    var age = 25
    val height: Double = 1.75
    val isStudent = true

    // 2. Calculate age next year (using arithmetic operators)
    val nextYearAge = age + 1

    // 3. Combine personal information into string (using string templates)
    val info = """
        Personal Information Card
        Name: $name
        Current Age: $age
        Age Next Year: $nextYearAge
        Height: ${height}m
        Is Student: ${if (isStudent) "Yes" else "No"}  // Using expression in template
    """.trimIndent()

    // 4. Output result
    println(info)
}

After running the program, the output will be:

Personal Information Card
Name: Zhang San
Current Age: 25
Age Next Year: 26
Height: 1.75m
Is Student: Yes

Try modifying variable values or adding more information (like weight or hobbies) to observe output changes and deepen your understanding of the concepts.

KotlinLesson 1: Kotlin Introduction Preparation: Setting Up the Learning Environment and Foundational Knowledge

Ge Ji — Tue, 19 Aug 2025 03:21:08 +0000

Welcome to your first Kotlin lesson! This course will take you from "why learn Kotlin" to "how to learn it", helping you build a complete learning framework. You'll understand Kotlin's core value while gaining hands-on experience in setting up your environment and developing your first program, laying a solid foundation for further study.

I. Why Learn Kotlin? — First, Understand the "Purpose of Learning It"

Before writing any code, we first need to clarify: What exactly is Kotlin? Where is it used in the industry? What advantages does it have compared to familiar languages like Java and Python? This will help you establish learning goals and avoid following trends blindly.

1. Programming Language Positioning: A Modern Language Focused on "Conciseness, Safety, and Multi-platform Support"

Kotlin is a statically typed programming language introduced by JetBrains (the company behind popular tools like IntelliJ IDEA and PyCharm) in 2011. In 2017, it was officially designated by Google as the preferred language for Android development, and in 2019, it became a "first-class citizen" in the Java ecosystem (fully compatible with Java). Its core positioning is: significantly simplifying code writing while ensuring performance and security, with support for multi-platform development.

2. Industry Application Scenarios: Beyond Android, Its Uses Are More Extensive Than You Think

Many people think Kotlin is only for Android development, but its application scenarios have long expanded across multiple domains:

Android Development: This is Kotlin's core scenario. Currently, over 70% of new apps on Google Play are developed using Kotlin, including Google's own Gmail and Maps;
Backend Development: Supports mainstream frameworks like Spring Boot and Ktor, serving as a replacement for Java in developing high-performance server programs with significantly less code (e.g., a simple interface requires 30-50% less code in Kotlin than Java);
Cross-platform Development: Through Kotlin Multiplatform Mobile (KMM), it enables simultaneous Android and iOS app development with over 70% shared business logic code, reducing redundant development;
Other Scenarios: It can also be used for desktop applications (with Compose Desktop), data science (collaborating with Python), and other fields, with a rapidly expanding ecosystem.

3. Comparison with Java/Python: Kotlin's "Differentiated Advantages"

(1) vs. Java: Solving "Historical Burdens" with Greater Conciseness and Safety

Java is a classic enterprise-level language but was born in 1995 with many "historical burdens" that Kotlin was specifically designed to address:

More Concise Code: For example, defining a data class (for storing user information, order details, etc.) requires writing getter/setter methods, toString, equals, etc. in Java (at least 50 lines of code), while Kotlin needs just one line: data class User(val name: String, val age: Int);
Null Safety: "NullPointerException" is the most common cause of crashes in Java, but Kotlin enforces a distinction between "nullable types" and "non-null types", catching errors at compile time (e.g., String is always non-null, while String? allows null values), fundamentally reducing null pointer issues;
Support for Modern Syntax: Built-in Lambda expressions, coroutines (simplifying asynchronous programming), extension functions (adding methods to existing classes without inheritance), etc., while Java only added Lambda support in Java 8 with more cumbersome syntax;
100% Java Compatibility: Can directly call Java libraries, use Java frameworks, and even mix Kotlin and Java code in the same project, resulting in extremely low migration costs (e.g., legacy Java projects can be gradually refactored with Kotlin).

(2) vs. Python: Balancing "Flexibility" with "Performance and Safety"

Python is a beginner-friendly dynamically typed language, but Kotlin has two key advantages in enterprise-level development:

Static Typing + Compile-time Checks: Python uses dynamic typing (variable types are determined at runtime), which can cause runtime crashes due to "type errors" (e.g., passing a string to a function expecting a number). Kotlin, being statically typed, checks for type errors at compile time, making large projects easier to maintain;
Superior Performance: Kotlin compiles to bytecode running on the JVM (Java Virtual Machine), executing 5-10 times faster than Python (especially in loops and computationally intensive scenarios), making it more suitable for developing high-performance applications;
More Mature Enterprise Ecosystem: While Python excels in data science and script development, its enterprise-level ecosystem for backend and mobile development (e.g., distributed frameworks, security frameworks) is less mature than Kotlin's Java-based ecosystem;
Of course, Kotlin can complement Python's strengths (like ease of entry and rich data science libraries) through "collaboration": for example, using Kotlin to write backend services that call Python machine learning models.

II. Setting Up the Kotlin Learning Environment: 3 Steps from "Zero" to "Writing Code"

JiGe recommend learning Kotlin directly through Kotlin Playground. Kotlin Playground (https://play.kotlinlang.org/) is an official online platform from JetBrains for editing and running Kotlin code. It offers simple functionality and a smooth experience. Simply click "Run" to experiment with code snippets. Of course, you'll need to first understand how to set up a Kotlin environment.

Learning Kotlin doesn't require a complex environment. The core tools are JDK (Java Development Kit, required for Kotlin execution) and IntelliJ IDEA (development tool, officially recommended by JetBrains, with a free Community Edition). Below are detailed installation steps by operating system to ensure every student can get set up.

1. Step 1: Install and Configure JDK (Essential! Kotlin Depends on JVM)

Kotlin code ultimately compiles to JVM bytecode, so you must first install the JDK. We recommend installing JDK 11 (a long-term support version that's stable and compatible with all mainstream frameworks).

(1) Installing JDK on Windows

Download JDK: Visit the Oracle JDK Download Page (or use domestic mirrors like Huawei Cloud or Alibaba Cloud), select "Windows x64 Installer" (.exe file). Note that you'll need to register a free Oracle account;
Install JDK: Double-click the installer and click "Next" throughout, noting the installation path (e.g., C:\Program Files\Java\jdk-11);
Configure environment variables: Right-click "This PC" → "Properties" → "Advanced system settings" → "Environment Variables"; In "System Variables", click "New", enter JAVA_HOME as the variable name and your JDK installation path as the variable value (e.g., C:\Program Files\Java\jdk-11); Find Path in "System Variables", click "Edit" → "New", enter %JAVA_HOME%\bin, then "New" again and enter %JAVA_HOME%\jre\bin (if JDK 11 lacks a jre folder, open Command Prompt and run bin\jlink.exe --module-path jmods --add-modules java.desktop --output jre to generate it);
Verify installation: Open "Command Prompt" (Win+R, type cmd), enter java -version. If it displays "java version "11.xxx"", installation is successful.

(2) Installing JDK on macOS

Download JDK: Visit the Oracle website and select "macOS x64 DMG Installer";
Install JDK: Double-click the DMG file and either drag it to the "Applications" folder or follow the prompts to complete installation;
Configure environment variables (if needed): Open "Terminal" (Launchpad → Other → Terminal); Enter sudo nano /etc/profile (enter your password), then add at the end of the file:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

Press Ctrl+O to save, Ctrl+X to exit, then enter source /etc/profile to apply changes;

Verify: In Terminal, enter java -version. If it displays JDK 11 version, installation is successful.

(3) Installing JDK on Linux

For Ubuntu:

Download JDK: From the official website, select "Linux x64 Compressed Archive" (.tar.gz file);
Extract to specified directory: Open Terminal and enter sudo tar -zxvf jdk-11xxx.tar.gz -C /usr/local/ (replace xxx with the specific version number);
Configure environment variables: Enter sudo nano /etc/profile and add at the end:

export JAVA_HOME=/usr/local/jdk-11xxx
export PATH=$JAVA_HOME/bin:$PATH

After saving and exiting, enter source /etc/profile;

Verify: In Terminal, enter java -version. If it displays the version, installation is successful.

2. Step 2: Download and Initialize IntelliJ IDEA (Free Community Edition)

IntelliJ IDEA (referred to as IDEA) is the most convenient tool for Kotlin development, supporting code completion, syntax checking, debugging, and more. The Community Edition is completely free and sufficient for learning purposes.

(1) Download IDEA

Visit the JetBrains website and select the "Community Edition" for your operating system (.exe for Windows, .dmg for macOS, .tar.gz for Linux).

(2) Install IDEA

Windows: Double-click the installer, check "Create desktop shortcut" and "Associate .java/.kt files", then click "Next" throughout;
macOS: Double-click the .dmg file and drag IDEA to the "Applications" folder;
Linux: Extract the .tar.gz file to the /opt/ directory, navigate to the bin folder, and double-click idea.sh to launch.

(3) Initialize IDEA (First Launch)

On first launch, you'll be prompted to "Import settings". Select "Do not import settings" (recommended for beginners) and click "OK";
Choose a theme (Light/Dark, based on preference) and click "Next: Featured plugins";
Check if the "Kotlin" plugin is selected (included by default in IDEA Community Edition, no additional installation needed). If not, select it manually, click "Install", then "Next";
Click "Start using IntelliJ IDEA" to complete initialization.

3. Step 3: Write Your First Kotlin Program "Hello World"

This step will guide you through the complete process of "creating a new project → writing code → running the program" — it's very straightforward!

(1) Create a New Kotlin Project

Open IDEA and click "New Project";
Select "Kotlin" from the left list and "Kotlin/JVM" on the right (JVM-based Kotlin project, ideal for beginners);
Fill in project information: "Name": Project name, e.g., "KotlinFirstDemo"; "Location": Project save path, e.g., "D:\KotlinProjects"; "JDK": Select the JDK 11 we installed earlier (if not displayed, click "Add JDK" and manually select the path);
Click "Create" and wait for IDEA to initialize the project (may take a few seconds the first time as it downloads necessary dependencies).

(2) Create a Kotlin Source File

After project initialization, the project directory will appear on the left. Locate the src/main/kotlin folder (the default directory for Kotlin source code);
Right-click the kotlin folder and select "New" → "Kotlin Class/File";
In the popup window, enter "HelloWorld" for "Name" (note that Kotlin filenames should typically start with a capital letter, matching the class name), select "File" for "Kind" (suitable for simple code), and press "Enter".

(3) Write the "Hello World" Code

In the newly created HelloWorld.kt file, enter the following code:

// First Kotlin program: Print Hello World
fun main() {
    println("Hello, Kotlin!")
}

Code explanation:

fun main(): Kotlin's entry function (similar to Java's main method), where program execution begins;
println("Hello, Kotlin!"): Print statement that outputs the string in parentheses to the console;
// First Kotlin program...: Single-line comment, which we'll discuss in detail later.

(4) Run the Program

There are two simple ways to run it:

Click the run button: On the left side of the code editor, you'll see a green "play button" (▶️). Click it and select "Run 'HelloWorldKt'";
Right-click to run: Right-click the HelloWorld.kt file and select "Run 'HelloWorldKt'".

After successful execution, the "Run" panel at the bottom will display the output: Hello, Kotlin!. Congratulations! You've successfully run your first Kotlin program.

III. Analyzing the Kotlin Project Structure: Understanding "Every File in the Directory"

New IDEA users might find the project directory unfamiliar, but Kotlin project structures are well-organized. Understanding them will help you manage code more efficiently. Let's break down the core directories and files using our newly created "KotlinFirstDemo" project.

1. Core Directory Structure (Focus on These 3 Folders)

KotlinFirstDemo/          # Project root directory
├─ .idea/                 # IDEA project configuration folder (auto-generated, no manual changes needed)
├─ gradle/                # Gradle build tool configuration (auto-generated, manages dependencies)
├─ src/                   # Core directory for source code and resource files
│  ├─ main/               # Main program directory (where you'll write business code)
│  │  ├─ kotlin/          # Kotlin source code directory (place .kt files here)
│  │  └─ resources/       # Resource file directory (e.g., images, configuration files)
│  └─ test/               # Test program directory (for test code, not needed for beginners)
│     └─ kotlin/          # Kotlin directory for test code
├─ build.gradle.kts       # Gradle build script (configures project dependencies, Kotlin version, etc.)
└─ settings.gradle.kts    # Gradle project settings (e.g., project name, module management)

Pay special attention to: src/main/kotlin (for writing code) and src/main/resources (for resources). Beginners don't need to modify other directories and files — keep them as default.

2. Source File Format: .kt Suffix is Key

Kotlin source files have the unified suffix .kt (e.g., HelloWorld.kt, User.kt), which distinguishes them from Java files (.java) and Python files (.py).

A .kt file can contain multiple classes, functions, or variables (e.g., adding a User class to HelloWorld.kt), but it's advisable to follow the "single responsibility principle": one file should correspond to one core class or function (e.g., User.kt contains only the User class, Order.kt contains only the Order class) for easier maintenance.

3. Common IDEA Operations: "Tips" to Improve Development Efficiency

As a beginner, mastering these common operations will make coding smoother:

(1) Creating New Files/Classes

Besides the earlier method of "right-click → New → Kotlin Class/File", you can use shortcuts:

Windows/Linux: Alt + Insert (hold Alt and press Insert);
macOS: Cmd + N (hold Command and press N). In the popup menu, you can choose "File" (ordinary file), "Class", "Data Class", etc., as needed.

(2) Running Code

In addition to clicking the "play button", use shortcuts:

Run current file: Shift + F10 (Windows/Linux) / Ctrl + R (macOS);
Run specific program: If your project has multiple entry functions, click the "run configuration" in the top-right corner of IDEA (e.g., "HelloWorldKt"), select the program to run, then click the play button.

(3) Debugging Techniques (Core for Troubleshooting Code Errors)

When code results don't match expectations, use "debugging" to step through execution:

Add breakpoints: Click next to the line number (left side of the code line) to create a red dot (breakpoint), e.g., on the println line;
Start debugging: Click the "debug button" (green bug icon 🐞) or use the shortcut Shift + F9 (Windows/Linux) / Ctrl + D (macOS);
Debug controls: After debugging starts, the "Debug" panel appears at the bottom. Common control buttons (left to right):
- "Step Over" (F8): Execute next step (without entering function internals);
- "Step Into" (F7): Enter current function (e.g., for custom functions, click to see execution);
- "Resume Program" (F9): Continue execution to next breakpoint;
- "Stop" (red square): Terminate debugging.

During debugging, hover your mouse over variables to see their values, helping you quickly identify errors (e.g., whether variable values match expectations).

(4) Code Completion (Essential for Beginners to Reduce Typos)

IDEA's code completion is powerful. Instead of typing complete words, press Ctrl + Space (Windows/Linux) or Cmd + Space (macOS) for suggestions, then press Enter to complete. For example, typing pri suggests print, println, etc.

IV. First Look at Kotlin Syntax Style: These "Details" Determine Code Quality

Syntax style is a programming language's "writing conventions". Good style makes code more readable and maintainable. Kotlin has clear syntax specifications — mastering these details will help you write "professional-grade" code from the start.

1. Code Comments: Helping Others Understand Your Code

Comments explain code without affecting execution, yet are crucial for "people" (including your future self). Kotlin supports three comment types:

(1) Single-line Comments (//)

Most commonly used for explaining single lines of code or short text, formatted as // comment content:

// Define a function to calculate sum of two numbers
fun add(a: Int, b: Int): Int {
    return a + b // Return calculation result
}

(2) Multi-line Comments (/* ... */)

Used for comments spanning multiple lines, formatted as /* comment content */ and can span lines:

/* 
   This is a multi-line comment example
   The function below checks if a number is even
   Parameter: num - integer to check
   Return value: true (even) / false (odd)
*/
fun isEven(num: Int): Boolean {
    return num % 2 == 0
}

⚠️ Note: Kotlin's multi-line comments support nesting (unlike Java):

/* 
   Outer comment
   /* This is a nested inner comment */
   Continuing outer comment
*/

(3) Documentation Comments (/** ... */)

Used for generating API documentation (similar to Java's Javadoc), typically for commenting classes, functions, properties, etc., with support for tags (e.g., @param for parameters, @return for return values):

/**
 * Calculate product of two integers
 * @param x first multiplier
 * @param y second multiplier
 * @return product of the two numbers
 */
fun multiply(x: Int, y: Int): Int {
    return x * y
}

In IDEA, hovering over places where this function is used will automatically display the documentation comment, which is very convenient.

2. Semicolons at Statement End: Optional, Omitting is Recommended

Unlike Java, which requires ; at the end of each statement, Kotlin makes semicolons optional. Omitting them is recommended for cleaner code:

// Recommended style (no semicolons)
println("Hello")
val age = 20

// Allowed but not recommended (with semicolons)
println("World");
val name = "Kotlin";

Semicolons are only needed when multiple statements are written on the same line:

// Multiple statements on one line require semicolons
println("Hello"); println("Kotlin")

3. Code Indentation: Use Spaces Instead of Tabs

Indentation shows code hierarchy (e.g., function bodies and loop bodies need indentation). Kotlin recommends 4 spaces for indentation (IDEA automatically converts Tabs to 4 spaces by default):


// Correct indentation example
fun printNumbers() {
    // Function body indented by 4 spaces
    for (i in 1..5) {
        // Loop body indented by another 4 spaces (total 8)
        println(i)
    }
}

// Incorrect example (no indentation, poor readability)
fun printLetters() {
for (c in 'a'..'c') {
println(c)
}
}

IDEA automatically handles indentation (adding correct indentation after pressing Enter), so you can focus on writing code.

4. Naming Conventions: "Unspoken Rules" for Meaningful Names

While Kotlin doesn't enforce naming requirements, the industry follows common conventions that make code more understandable:

Variables/functions/properties: Use "camelCase" (lowercase first letter, uppercase first letter of subsequent words), e.g., userName, calculateTotal();
Classes/interfaces: Use "PascalCase" (uppercase first letter, uppercase first letter of subsequent words), e.g., User, OrderService;
Constants: Use all uppercase with underscores separating words, e.g., MAX_SIZE, DEFAULT_TIMEOUT;
Package names: All lowercase without underscores, typically using reversed domain names (e.g., for company domain com.example, package name could be com.example.myapp).

Examples:

// Class name (PascalCase)
class Student {
    // Property (camelCase)
    val studentName: String = "Tom"

    // Function (camelCase)
    fun getAge(): Int {
        return 18
    }
}

// Constant (all uppercase)
const val MAX_SCORE = 100

Flutter Lesson 18: Device Feature Integration in Flutter

Ge Ji — Fri, 15 Aug 2025 15:15:41 +0000

In mobile app development, integrating native device features (such as cameras, photo galleries, and location services) is crucial for enhancing user experience. Flutter provides a rich ecosystem of third-party plugins that make implementing these features straightforward. In this lesson, we'll explore the core concepts of device feature integration, including permission management, camera/gallery access, location retrieval, and demonstrate practical implementation through a comprehensive example.

1. Permission Management: The permission_handler Plugin

Before accessing device features, you must obtain user authorization. The permission_handler plugin is the most commonly used permission management tool in Flutter, supporting nearly all permission types across Android and iOS platforms.

1.1 Installation and Configuration

Step 1: Add Dependency
Add the plugin to your pubspec.yaml:

dependencies:
  permission_handler: ^12.0.1  # Use the latest version

Run flutter pub get to install.

Step 2: Platform Permission Configuration
Permissions must be declared in native configuration files; otherwise, feature access will fail.

Android Configuration Edit android/app/src/main/AndroidManifest.xml and add required permissions:

<!-- Camera permission -->
<uses-permission android:name="android.permission.CAMERA"/>
<!-- Storage permissions -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- Location permissions -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

iOS Configuration Edit ios/Runner/Info.plist and add permission descriptions (users will see these):

<!-- Camera permission description -->
<key>NSCameraUsageDescription</key>
<string>Camera access is needed to take photos</string>
<!-- Photo library permission description -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is needed to select images</string>
<!-- Location permission description -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access is needed to get your current location</string>

1.2 Core Permission Methods

permission_handler provides a simple API for checking and requesting permissions:

import 'package:permission_handler/permission_handler.dart';

// Check permission status
Future<bool> checkPermission(Permission permission) async {
  PermissionStatus status = await permission.status;
  return status.isGranted; // Returns true if permission is granted
}

// Request permission
Future<bool> requestPermission(Permission permission) async {
  PermissionStatus status = await permission.request();
  return status.isGranted;
}

// Open app settings (when user denies permission with "Don't ask again")
Future<void> openAppSet() async {
  await openAppSettings();
}

1.3 Common Permission Constants

The Permission class contains all supported permissions. Common ones include:

Permission.camera: Camera access
Permission.photos / Permission.storage: Photo library/storage access
Permission.locationWhenInUse: Location access while app is in use
Permission.locationAlways: Always allow location access

2. Accessing Camera/Gallery: The image_picker Plugin

image_picker is the officially recommended media selection plugin for Flutter, supporting photo/video capture from camera or selection from gallery.

2.1 Installation and Configuration

Step 1: Add Dependency

dependencies:
  image_picker: ^1.1.2  # Use the latest version

Run flutter pub get to install.

Step 2: Additional Platform Configuration (for specific scenarios)

iOS Video Selection: For video selection, add NSCameraUsageDescription to Info.plist (same as camera permission)
Android 10+ Storage: To save images to public directories, add to AndroidManifest.xml:

<application ...>
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <!-- For Android 10+ -->
  <application ... android:requestLegacyExternalStorage="true">
</application>

2.2 Core Feature Implementation

(1) Taking Photos with Camera

import 'package:image_picker/image_picker.dart';

// Get image from camera
Future<XFile?> takePhoto() async {
  final ImagePicker picker = ImagePicker();
  // Launch camera, returns XFile (contains image path and info)
  final XFile? photo = await picker.pickImage(
    source: ImageSource.camera, // Source is camera
    imageQuality: 80, // Image quality (0-100)
    maxWidth: 1080, // Maximum width
  );
  return photo;
}

(2) Selecting Images from Gallery

// Select image from gallery
Future<XFile?> pickImageFromGallery() async {
  final ImagePicker picker = ImagePicker();
  final XFile? image = await picker.pickImage(
    source: ImageSource.gallery, // Source is gallery
    imageQuality: 80,
  );
  return image;
}

(3) Displaying Selected Images
After obtaining an XFile, display the image using Image.file:

XFile? selectedImage; // Stores selected image

// Update image after taking photo
void _onTakePhoto() async {
  XFile? photo = await takePhoto();
  if (photo != null) {
    setState(() {
      selectedImage = photo;
    });
  }
}

// Display image in UI
Widget buildImagePreview() {
  if (selectedImage == null) {
    return Text("No image selected");
  }
  return Image.file(
    File(selectedImage!.path),
    width: 300,
    height: 300,
    fit: BoxFit.cover,
  );
}

3. Location Services: The geolocator Plugin

geolocator provides cross-platform location services, supporting retrieval of coordinates, altitude, speed, and location change monitoring.

3.1 Installation and Configuration

Step 1: Add Dependency

dependencies:
  geolocator: ^14.0.2  # Use the latest version

Run flutter pub get to install.

Step 2: Platform Permission Configuration

Location services require additional permissions (already partially added in the permission_handler section):

Android: In addition to ACCESS_FINE_LOCATION (precise location) and ACCESS_COARSE_LOCATION (approximate location), for background location:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

iOS:
For background location, add to Info.plist:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Continuous location access is needed for background tracking</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

3.2 Core Feature Implementation

(1) Getting Current Location

import 'package:geolocator/geolocator.dart';

// Get current coordinates
Future<Position?> getCurrentLocation() async {
  // Check if location services are enabled
  bool isLocationEnabled = await Geolocator.isLocationServiceEnabled();
  if (!isLocationEnabled) {
    // Prompt user to enable location services
    return null;
  }

  // Check location permissions
  LocationPermission permission = await Geolocator.checkPermission();
  if (permission == LocationPermission.denied) {
    // Request permission
    permission = await Geolocator.requestPermission();
    if (permission != LocationPermission.whileInUse && 
        permission != LocationPermission.always) {
      // Permission denied
      return null;
    }
  }

  // Get current location (timeout after 10 seconds)
  try {
    Position position = await Geolocator.getCurrentPosition(
      desiredAccuracy: LocationAccuracy.high, // High accuracy
      timeLimit: Duration(seconds: 10),
    );
    return position; // Contains latitude and longitude
  } catch (e) {
    print("Failed to get location: $e");
    return null;
  }
}

(2) Listening for Location Changes

// Listen for location changes (updates every 10 meters or 30 seconds)
StreamSubscription<Position>? positionStream;

void startListeningLocation() {
  positionStream = Geolocator.getPositionStream(
    locationSettings: LocationSettings(
      accuracy: LocationAccuracy.high,
      distanceFilter: 10, // Update only when moving more than 10 meters
      intervalDuration: Duration(seconds: 30), // Update at least every 30 seconds
    ),
  ).listen((Position position) {
    print("Current location: ${position.latitude}, ${position.longitude}");
  });
}

// Stop listening
void stopListeningLocation() {
  if (positionStream != null) {
    positionStream!.cancel();
    positionStream = null;
  }
}

4. Comprehensive Example: Photo Upload with Location

Let's implement a complete page with these features:

Check and request camera and location permissions
Take photos or select from gallery
Get current location coordinates
Simulate image upload (show upload status)

Complete Code Implementation

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:image_picker/image_picker.dart';
import 'package:geolocator/geolocator.dart';

class DeviceDemoPage extends StatefulWidget {
  const DeviceDemoPage({super.key});

  @override
  State<DeviceDemoPage> createState() => _DeviceDemoPageState();
}

class _DeviceDemoPageState extends State<DeviceDemoPage> {
  XFile? _selectedImage; // Selected image
  Position? _currentPosition; // Current location
  bool _isUploading = false; // Upload in progress

  // Check and request permission
  Future<bool> _checkAndRequestPermission(Permission permission) async {
    bool isGranted = await checkPermission(permission);
    if (!isGranted) {
      isGranted = await requestPermission(permission);
    }
    return isGranted;
  }

  // Take photo with camera
  void _takePhoto() async {
    bool hasCameraPermission = await _checkAndRequestPermission(Permission.camera);
    if (!hasCameraPermission) {
      _showSnackBar("Please grant camera permission");
      return;
    }

    XFile? photo = await ImagePicker().pickImage(
      source: ImageSource.camera,
      imageQuality: 80,
    );
    if (photo != null) {
      setState(() => _selectedImage = photo);
    }
  }

  // Select from gallery
  void _pickFromGallery() async {
    bool hasStoragePermission = await _checkAndRequestPermission(Permission.photos);
    if (!hasStoragePermission) {
      _showSnackBar("Please grant gallery permission");
      return;
    }

    XFile? image = await ImagePicker().pickImage(
      source: ImageSource.gallery,
      imageQuality: 80,
    );
    if (image != null) {
      setState(() => _selectedImage = image);
    }
  }

  // Get current location
  void _getCurrentLocation() async {
    bool hasLocationPermission = await _checkAndRequestPermission(Permission.locationWhenInUse);
    if (!hasLocationPermission) {
      _showSnackBar("Please grant location permission");
      return;
    }

    Position? position = await getCurrentLocation();
    if (position != null) {
      setState(() => _currentPosition = position);
      _showSnackBar("Location information obtained");
    } else {
      _showSnackBar("Failed to get location. Please check location services.");
    }
  }

  // Simulate image upload
  void _uploadImage() async {
    if (_selectedImage == null) {
      _showSnackBar("Please select an image first");
      return;
    }

    setState(() => _isUploading = true);
    // Simulate network request (complete after 2 seconds)
    await Future.delayed(Duration(seconds: 2));
    setState(() => _isUploading = false);
    _showSnackBar("Image uploaded successfully");
  }

  // Show notification
  void _showSnackBar(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("Device Features Demo")),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            // Image preview
            _selectedImage == null
                ? const Text("No image selected", style: TextStyle(fontSize: 16))
                : Image.file(
                    File(_selectedImage!.path),
                    width: 300,
                    height: 300,
                    fit: BoxFit.cover,
                  ),
            const SizedBox(height: 20),

            // Action buttons
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                ElevatedButton.icon(
                  onPressed: _takePhoto,
                  icon: const Icon(Icons.camera_alt),
                  label: const Text("Take Photo"),
                ),
                const SizedBox(width: 16),
                ElevatedButton.icon(
                  onPressed: _pickFromGallery,
                  icon: const Icon(Icons.photo_library),
                  label: const Text("Gallery"),
                ),
              ],
            ),
            const SizedBox(height: 16),

            // Location information
            ElevatedButton.icon(
              onPressed: _getCurrentLocation,
              icon: const Icon(Icons.location_on),
              label: const Text("Get Current Location"),
            ),
            if (_currentPosition != null)
              Padding(
                padding: const EdgeInsets.all(16),
                child: Text(
                  "Current Location:\nLatitude: ${_currentPosition!.latitude}\nLongitude: ${_currentPosition!.longitude}",
                  textAlign: TextAlign.center,
                  style: const TextStyle(fontSize: 16),
                ),
              ),
            const SizedBox(height: 16),

            // Upload button
            _isUploading
                ? const CircularProgressIndicator()
                : ElevatedButton.icon(
                    onPressed: _uploadImage,
                    icon: const Icon(Icons.upload),
                    label: const Text("Upload Image"),
                  ),
          ],
        ),
      ),
    );
  }
}

// Utility methods for permission checking and requesting (can be extracted to a utility class)
Future<bool> checkPermission(Permission permission) async {
  return (await permission.status).isGranted;
}

Future<bool> requestPermission(Permission permission) async {
  return (await permission.request()).isGranted;
}

// Location utility methods (can be extracted to a utility class)
Future<Position?> getCurrentLocation() async {
  // Check if location services are enabled
  if (!await Geolocator.isLocationServiceEnabled()) {
    return null;
  }

  // Check permissions
  LocationPermission permission = await Geolocator.checkPermission();
  if (permission == LocationPermission.denied) {
    permission = await Geolocator.requestPermission();
    if (permission != LocationPermission.whileInUse &&
        permission != LocationPermission.always) {
      return null;
    }
  }

  // Get location
  try {
    return await Geolocator.getCurrentPosition(
      desiredAccuracy: LocationAccuracy.high,
      timeLimit: const Duration(seconds: 10),
    );
  } catch (e) {
    return null;
  }
}

Code Explanation

Permission Management: Uses encapsulated checkPermission and requestPermission methods to handle permission logic uniformly, ensuring authorization before accessing device features.
Image Handling: Implements camera capture and gallery selection using image_picker, with Image.file for displaying selected images.
Location Features: Retrieves coordinates using geolocator, including location service checks and permission handling for reliable location functionality.
User Experience: Adds loading states (progress indicator during upload) and notification messages (SnackBar) to enhance interaction friendliness.

5. Extended Knowledge: Other Useful Device Feature Plugins

Beyond the features covered in this lesson, these plugins are commonly used for device integration:

url_launcher: Launch system browser, make phone calls, send emails, etc.
share_plus: Share text and images to other applications.
flutter_local_notifications: Local notification functionality.
connectivity_plus: Network connection status monitoring.
package_info_plus: Retrieve app version, name, and other information.

Flutter Lesson 17: Project Practice: Comprehensive Application Development (Part 2)

Ge Ji — Thu, 14 Aug 2025 07:39:30 +0000

In the previous lesson, we completed the basic page structure of the to-do list app. In this lesson, we will build on that foundation to implement data persistence, state management, interaction optimization, and dark mode adaptation, equipping the app with more comprehensive functionality and a better user experience.

I. Integrating Network Requests and Local Storage

1. Implementing Network Requests (using Dio)

First, add dependencies to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.9.0
  flutter_riverpod: ^2.6.1
  hive: ^2.2.3
  hive_flutter: ^1.1.0
  intl: ^0.20.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner: ^2.6.0

Create a network request utility class utils/network_utils.dart:

import 'package:dio/dio.dart';
import '../models/task_model.dart';

class NetworkUtils {
  static final Dio _dio = Dio(BaseOptions(
    baseUrl: 'https://api.example.com/tasks',
    connectTimeout: const Duration(seconds: 5),
    receiveTimeout: const Duration(seconds: 3),
  ));

  // Fetch all tasks
  static Future<List<Task>> fetchTasks() async {
    try {
      final response = await _dio.get('/');
      List<dynamic> data = response.data;
      return data.map((json) => Task.fromJson(json)).toList();
    } catch (e) {
      throw Exception('Failed to fetch tasks: $e');
    }
  }

  // Add a new task
  static Future<Task> addTask(Task task) async {
    try {
      final response = await _dio.post('/', data: task.toJson());
      return Task.fromJson(response.data);
    } catch (e) {
      throw Exception('Failed to add task: $e');
    }
  }

  // Update a task
  static Future<Task> updateTask(Task task) async {
    try {
      final response = await _dio.put('/${task.id}', data: task.toJson());
      return Task.fromJson(response.data);
    } catch (e) {
      throw Exception('Failed to update task: $e');
    }
  }

  // Delete a task
  static Future<void> deleteTask(String id) async {
    try {
      await _dio.delete('/$id');
    } catch (e) {
      throw Exception('Failed to delete task: $e');
    }
  }

  // Unified error message handling
  static String getErrorMsg(dynamic e) {
    if (e is DioException) {
      if (e.type == DioExceptionType.connectionTimeout) {
        return 'Network connection timed out. Please check your network.';
      } else if (e.type == DioExceptionType.receiveTimeout) {
        return 'Data reception timed out.';
      } else if (e.type == DioExceptionType.badResponse) {
        return 'Server error: ${e.response?.statusCode}';
      } else if (e.type == DioExceptionType.connectionError) {
        return 'Unable to connect to server. Please check your network.';
      }
    }
    return 'Operation failed. Please try again later.';
  }
}

Modify the Task model with manual JSON serialization (models/task_model.dart):

class Task {
  final String id;
  String title;
  String content;
  DateTime createTime;
  DateTime? deadline;
  bool isCompleted;

  Task({
    required this.id,
    required this.title,
    this.content = '',
    DateTime? createTime,
    this.deadline,
    this.isCompleted = false,
  }) : createTime = createTime ?? DateTime.now();

  // Manual JSON serialization
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'title': title,
      'content': content,
      'createTime': createTime.millisecondsSinceEpoch,
      'deadline': deadline?.millisecondsSinceEpoch,
      'isCompleted': isCompleted,
    };
  }

  // Manual deserialization from JSON
  factory Task.fromJson(Map<String, dynamic> json) {
    return Task(
      id: json['id'],
      title: json['title'],
      content: json['content'] ?? '',
      createTime: DateTime.fromMillisecondsSinceEpoch(json['createTime']),
      deadline: json['deadline'] != null 
          ? DateTime.fromMillisecondsSinceEpoch(json['deadline'])
          : null,
      isCompleted: json['isCompleted'] ?? false,
    );
  }
}

2. Implementing Local Storage (Hive)

Create a Hive adapter (models/task_adapter.dart):

import 'package:hive/hive.dart';
import 'task_model.dart';

class TaskAdapter extends TypeAdapter<Task> {
  @override
  final typeId = 0;

  @override
  Task read(BinaryReader reader) {
    final id = reader.readString();
    final title = reader.readString();
    final content = reader.readString();
    final createTime = DateTime.fromMillisecondsSinceEpoch(reader.readInt());
    final hasDeadline = reader.readBool();
    DateTime? deadline;
    if (hasDeadline) {
      deadline = DateTime.fromMillisecondsSinceEpoch(reader.readInt());
    }
    final isCompleted = reader.readBool();

    return Task(
      id: id,
      title: title,
      content: content,
      createTime: createTime,
      deadline: deadline,
      isCompleted: isCompleted,
    );
  }

  @override
  void write(BinaryWriter writer, Task obj) {
    writer.writeString(obj.id);
    writer.writeString(obj.title);
    writer.writeString(obj.content);
    writer.writeInt(obj.createTime.millisecondsSinceEpoch);
    writer.writeBool(obj.deadline != null);
    if (obj.deadline != null) {
      writer.writeInt(obj.deadline!.millisecondsSinceEpoch);
    }
    writer.writeBool(obj.isCompleted);
  }
}

Initialize Hive (main.dart):

import 'package:flutter/material.dart';
import 'package:hive_flutter/hive_flutter.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'models/task_model.dart';
import 'models/task_adapter.dart';
import 'pages/home_page.dart';
import 'utils/router.dart';
import 'providers/theme_provider.dart';

void main() async {
  // Initialize Hive
  await Hive.initFlutter();
  // Register adapter
  Hive.registerAdapter(TaskAdapter());
  // Open task box
  await Hive.openBox<Task>('tasks');
  // Open settings box
  await Hive.openBox('settings');

  runApp(ProviderScope(child: const MyApp()));
}

class MyApp extends ConsumerWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final themeMode = ref.watch(themeModeProvider);

    return MaterialApp(
      title: 'To-Do List',
      theme: ThemeData(
        brightness: Brightness.light,
        primarySwatch: Colors.blue,
        visualDensity: VisualDensity.adaptivePlatformDensity,
        scaffoldBackgroundColor: Colors.white,
        cardColor: Colors.white,
        textTheme: const TextTheme(
          bodyLarge: TextStyle(color: Colors.black87),
          bodyMedium: TextStyle(color: Colors.black54),
        ),
      ),
      darkTheme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: Colors.blue,
        visualDensity: VisualDensity.adaptivePlatformDensity,
        scaffoldBackgroundColor: Colors.grey[900],
        cardColor: Colors.grey[800],
        textTheme: const TextTheme(
          bodyLarge: TextStyle(color: Colors.white70),
          bodyMedium: TextStyle(color: Colors.white54),
        ),
      ),
      themeMode: themeMode,
      initialRoute: Router.home,
      routes: Router.routes,
      onGenerateRoute: Router.generateRoute,
      debugShowCheckedModeBanner: false,
    );
  }
}

Create a local storage utility class (utils/storage_utils.dart):

import 'package:hive/hive.dart';
import '../models/task_model.dart';

class StorageUtils {
  static Box<Task> get _taskBox => Hive.box<Task>('tasks');

  // Save task list
  static Future<void> saveTasks(List<Task> tasks) async {
    await _taskBox.clear();
    await _taskBox.addAll(tasks);
  }

  // Get all tasks
  static List<Task> getTasks() => _taskBox.values.toList();

  // Add a single task
  static Future<void> addTask(Task task) async {
    await _taskBox.put(task.id, task);
  }

  // Update a task
  static Future<void> updateTask(Task task) async {
    await _taskBox.put(task.id, task);
  }

  // Delete a task
  static Future<void> deleteTask(String id) async {
    await _taskBox.delete(id);
  }
}

II. Implementing State Management (Riverpod)

Create a task state management class (providers/task_provider.dart):

import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../models/task_model.dart';
import '../utils/network_utils.dart';
import '../utils/storage_utils.dart';

// Define task state data class, containing task list and loading state
class TaskState {
  final List<Task> tasks;
  final bool isLoading;
  final String? errorMessage;

  TaskState({
    required this.tasks,
    required this.isLoading,
    this.errorMessage,
  });

  // Copy method for easy state updates
  TaskState copyWith({
    List<Task>? tasks,
    bool? isLoading,
    String? errorMessage,
  }) {
    return TaskState(
      tasks: tasks ?? this.tasks,
      isLoading: isLoading ?? this.isLoading,
      errorMessage: errorMessage,
    );
  }
}

// Task state provider
final taskProvider = StateNotifierProvider<TaskNotifier, TaskState>((ref) {
  return TaskNotifier();
});

class TaskNotifier extends StateNotifier<TaskState> {
  TaskNotifier() : super(TaskState(tasks: [], isLoading: true)) {
    _loadTasks(); // Load tasks on initialization
  }

  // Load tasks from local storage
  Future<void> loadTasks() async {
    state = state.copyWith(isLoading: true, errorMessage: null);

    try {
      // First load local data
      final localTasks = StorageUtils.getTasks();
      state = state.copyWith(tasks: localTasks);

      // Then try to fetch latest data from network
      final networkTasks = await NetworkUtils.fetchTasks();
      state = state.copyWith(tasks: networkTasks);
      await StorageUtils.saveTasks(networkTasks);
    } catch (e) {
      // Keep local data if network request fails (if available)
      final errorMsg = NetworkUtils.getErrorMsg(e);
      state = state.copyWith(
        errorMessage: errorMsg,
        isLoading: false,
      );
    } finally {
      if (mounted) {
        state = state.copyWith(isLoading: false);
      }
    }
  }

  // Add task - still save to local if network fails
  Future<void> addTask(Task task, {bool skipNetwork = false}) async {
    final currentTasks = List<Task>.from(state.tasks);

    try {
      // Update UI first
      state = state.copyWith(
        tasks: [...state.tasks, task],
        errorMessage: null,
      );

      // Save to local storage (execute regardless of network success)
      await StorageUtils.addTask(task);

      // Return directly if network request is not needed
      if (skipNetwork) {
        return;
      }

      // Try to sync with network
      final newTask = await NetworkUtils.addTask(task);
      // Update with task returned from network (may contain server-generated ID)
      state = state.copyWith(
        tasks: state.tasks.map((t) => t.id == task.id ? newTask : t).toList(),
      );
    } catch (e) {
      // Keep locally saved state if network fails, no rollback
      state = state.copyWith(
        errorMessage: NetworkUtils.getErrorMsg(e),
      );
      rethrow;
    }
  }

  // Update task - still save to local if network fails
  Future<void> updateTask(Task task, {bool skipNetwork = false}) async {
    final currentTask = state.tasks.firstWhere((t) => t.id == task.id, orElse: () => task);

    try {
      // Update UI first
      state = state.copyWith(
        tasks: state.tasks.map((t) => t.id == task.id ? task : t).toList(),
        errorMessage: null,
      );

      // Save to local storage (execute regardless of network success)
      await StorageUtils.updateTask(task);

      // Return directly if network request is not needed
      if (skipNetwork) {
        return;
      }

      // Try to sync with network
      final updatedTask = await NetworkUtils.updateTask(task);
    } catch (e) {
      // Keep locally updated state if network fails
      state = state.copyWith(
        errorMessage: NetworkUtils.getErrorMsg(e),
      );
      rethrow;
    }
  }

  // Delete task
  Future<void> deleteTask(String id) async {
    // Save the task to be deleted for rollback on failure
    final deletedTask = state.tasks.firstWhere((t) => t.id == id, orElse: () => Task(id: id, title: ''));

    try {
      // Update UI first
      state = state.copyWith(
        tasks: state.tasks.where((t) => t.id != id).toList(),
        errorMessage: null,
      );

      // Sync to local storage
      await StorageUtils.deleteTask(id);

      // Try to sync with network
      await NetworkUtils.deleteTask(id);
    } catch (e) {
      // Rollback on failure
      state = state.copyWith(
        tasks: [...state.tasks, deletedTask],
        errorMessage: NetworkUtils.getErrorMsg(e),
      );
      rethrow;
    }
  }
}

Create theme state management (providers/theme_provider.dart):

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter/material.dart';
import 'package:hive/hive.dart';

final themeModeProvider = StateNotifierProvider<ThemeModeNotifier, ThemeMode>(
  (ref) => ThemeModeNotifier(),
);

class ThemeModeNotifier extends StateNotifier<ThemeMode> {
  static const _themeBox = 'settings';
  static const _themeKey = 'theme_mode';

  ThemeModeNotifier() : super(ThemeMode.system) {
    _loadThemeMode();
  }

  Future<void> _loadThemeMode() async {
    final box = await Hive.openBox(_themeBox);
    final mode = box.get(_themeKey);
    if (mode == 'light') {
      state = ThemeMode.light;
    } else if (mode == 'dark') {
      state = ThemeMode.dark;
    } else {
      state = ThemeMode.system;
    }
  }

  void setThemeMode(ThemeMode mode) {
    state = mode;
    final box = Hive.box(_themeBox);
    if (mode == ThemeMode.light) {
      box.put(_themeKey, 'light');
    } else if (mode == ThemeMode.dark) {
      box.put(_themeKey, 'dark');
    } else {
      box.put(_themeKey, 'system');
    }
  }
}

III. Completing Core Page Implementations

1. Home Page Implementation (pages/home_page.dart)

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../widgets/task/task_item.dart';
import '../models/task_model.dart';
import 'detail_page.dart';
import 'setting_page.dart';
import '../providers/task_provider.dart';
import '../utils/network_utils.dart';

class HomePage extends ConsumerWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final taskState = ref.watch(taskProvider);
    final taskNotifier = ref.read(taskProvider.notifier);

    // Load task data for the first time
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (taskState.tasks.isEmpty && taskState.isLoading) {
        taskNotifier.loadTasks();
      }
    });

    // Display error message
    if (taskState.errorMessage != null && taskState.tasks.isEmpty) {
      WidgetsBinding.instance.addPostFrameCallback((_) {
        if (context.mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(taskState.errorMessage!),
              backgroundColor: Colors.red,
              action: SnackBarAction(
                label: 'Retry',
                onPressed: () => taskNotifier.loadTasks(),
              ),
            ),
          );
        }
      });
    }

    return Scaffold(
      appBar: AppBar(
        title: const Text('To-Do List'),
        actions: [
          IconButton(
            icon: const Icon(Icons.settings),
            onPressed: () => Navigator.push(
              context,
              MaterialPageRoute(builder: (context) => const SettingPage()),
            ),
          ),
        ],
      ),
      body: _buildBody(context, taskState, taskNotifier),
      floatingActionButton: FloatingActionButton(
        child: const Icon(Icons.add),
        onPressed: () => _navigateToDetail(context, null, taskNotifier),
      ),
    );
  }

  Widget _buildBody(
    BuildContext context,
    TaskState taskState,
    TaskNotifier taskNotifier,
  ) {
    // Loading state
    if (taskState.isLoading) {
      return const Center(child: CircularProgressIndicator());
    }

    // Empty data state
    if (taskState.tasks.isEmpty) {
      return Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('No tasks yet. Add one!'),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: () => taskNotifier.loadTasks(),
              child: const Text('Reload'),
            ),
          ],
        ),
      );
    }

    // Normal task list display
    return RefreshIndicator(
      onRefresh: () async {
        await taskNotifier.loadTasks();
      },
      child: ListView.builder(
        padding: const EdgeInsets.all(16),
        itemCount: taskState.tasks.length,
        itemBuilder: (context, index) {
          final task = taskState.tasks[index];
          return TaskItem(
            task: task,
            onTap: () => _navigateToDetail(context, task, taskNotifier),
            onStatusChanged: (id) {
              final updatedTask = Task(
                id: task.id,
                title: task.title,
                content: task.content,
                createTime: task.createTime,
                deadline: task.deadline,
                isCompleted: !task.isCompleted,
              );
              taskNotifier.updateTask(updatedTask);
            },
            onDelete: (id) => taskNotifier.deleteTask(id),
          );
        },
      ),
    );
  }

  void _navigateToDetail(
    BuildContext context,
    Task? task,
    TaskNotifier notifier,
  ) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => DetailPage(
          task: task,
          onSave: (newTask) async {
            try {
              if (task == null) {
                // First attempt with network request
                await notifier.addTask(newTask);
                if (context.mounted) {
                  ScaffoldMessenger.of(context).showSnackBar(
                    const SnackBar(content: Text('Task added successfully')),
                  );
                  Navigator.pop(context);
                }
              } else {
                // First attempt with network request
                await notifier.updateTask(newTask);
                if (context.mounted) {
                  ScaffoldMessenger.of(context).showSnackBar(
                    const SnackBar(content: Text('Task updated successfully')),
                  );
                  Navigator.pop(context);
                }
              }
            } catch (e) {
              if (context.mounted) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(
                    content: Text('${NetworkUtils.getErrorMsg(e)}. Will save locally.'),
                    action: SnackBarAction(
                      label: 'Confirm',
                      onPressed: () => _saveAgain(context, newTask, task, notifier),
                    ),
                  ),
                );
              }
            }
          },
        ),
      ),
    );
  }

  // Retry saving task - save only locally, skip network request
  void _saveAgain(BuildContext context, Task newTask, Task? originalTask, TaskNotifier notifier) {
    if (originalTask == null) {
      // Skip network request, save only locally
      notifier.addTask(newTask, skipNetwork: true);
    } else {
      // Skip network request, save only locally
      notifier.updateTask(newTask, skipNetwork: true);
    }

    if (context.mounted) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Task saved locally')),
      );
      Navigator.pop(context);
    }
  }
}

2. Task List Item Component (widgets/task/task_item.dart)

import 'package:flutter/material.dart';
import '../../models/task_model.dart';
import '../../utils/date_utils.dart';

class TaskItem extends StatelessWidget {
  final Task task;
  final VoidCallback onTap;
  final Function(String) onStatusChanged;
  final Function(String) onDelete;

  const TaskItem({
    super.key,
    required this.task,
    required this.onTap,
    required this.onStatusChanged,
    required this.onDelete,
  });

  @override
  Widget build(BuildContext context) {
    return Dismissible(
      key: Key(task.id),
      direction: DismissDirection.endToStart,
      background: Container(
        color: Colors.red,
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.symmetric(horizontal: 16),
        child: const Icon(Icons.delete, color: Colors.white),
      ),
      confirmDismiss: (direction) async {
        return await showDialog(
          context: context,
          builder: (context) => AlertDialog(
            title: const Text('Confirm Deletion'),
            content: const Text('Are you sure you want to delete this task?'),
            actions: [
              TextButton(
                onPressed: () => Navigator.pop(context, false),
                child: const Text('Cancel'),
              ),
              TextButton(
                onPressed: () => Navigator.pop(context, true),
                child: const Text('Delete', style: TextStyle(color: Colors.red)),
              ),
            ],
          ),
        );
      },
      onDismissed: (direction) => onDelete(task.id),
      child: Card(
        elevation: 2,
        margin: const EdgeInsets.only(bottom: 12),
        child: ListTile(
          onTap: onTap,
          leading: Checkbox(
            value: task.isCompleted,
            onChanged: (value) => onStatusChanged(task.id),
          ),
          title: Text(
            task.title,
            style: TextStyle(
              decoration: task.isCompleted ? TextDecoration.lineThrough : null,
              color: task.isCompleted ? Colors.grey : null,
            ),
          ),
          subtitle: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisSize: MainAxisSize.min,
            children: [
              if (task.deadline != null)
                Text(
                  'Deadline: ${DateUtils.formatDate(task.deadline!)}',
                  style: const TextStyle(fontSize: 12, color: Colors.grey),
                ),
              Text(
                'Created: ${DateUtils.formatDate(task.createTime)}',
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ],
          ),
          trailing: const Icon(Icons.arrow_forward_ios, size: 18),
        ),
      ),
    );
  }
}

3. Detail Page Implementation (pages/detail_page.dart)

import 'package:flutter/material.dart';
import '../models/task_model.dart';
import '../utils/date_utils.dart';
import '../utils/network_utils.dart';

class DetailPage extends StatefulWidget {
  final Task? task;
  final Function(Task) onSave;

  const DetailPage({
    super.key,
    this.task,
    required this.onSave,
  });

  @override
  State<DetailPage> createState() => _DetailPageState();
}

class _DetailPageState extends State<DetailPage> {
  late final TextEditingController _titleController;
  late final TextEditingController _contentController;
  DateTime? _deadline;
  bool _isCompleted = false;
  bool _isSaving = false;

  @override
  void initState() {
    super.initState();
    if (widget.task != null) {
      _titleController = TextEditingController(text: widget.task!.title);
      _contentController = TextEditingController(text: widget.task!.content);
      _deadline = widget.task!.deadline;
      _isCompleted = widget.task!.isCompleted;
    } else {
      _titleController = TextEditingController();
      _contentController = TextEditingController();
    }
  }

  @override
  void dispose() {
    _titleController.dispose();
    _contentController.dispose();
    super.dispose();
  }

  void _saveTask() async {
    if (_titleController.text.isEmpty) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Please enter a task title')),
      );
      return;
    }

    setState(() => _isSaving = true);
    try {
      final task = Task(
        id: widget.task?.id ?? DateTime.now().microsecondsSinceEpoch.toString(),
        title: _titleController.text,
        content: _contentController.text,
        createTime: widget.task?.createTime ?? DateTime.now(),
        deadline: _deadline,
        isCompleted: _isCompleted,
      );

      await widget.onSave(task);
    } catch (e) {
      if (context.mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(NetworkUtils.getErrorMsg(e))),
        );
      }
    } finally {
      if (mounted) {
        setState(() => _isSaving = false);
      }
    }
  }

  Future<void> _selectDate() async {
    final picked = await showDatePicker(
      context: context,
      initialDate: _deadline ?? DateTime.now(),
      firstDate: DateTime.now(),
      lastDate: DateTime.now().add(const Duration(days: 365)),
    );
    if (picked != null) {
      setState(() => _deadline = picked);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.task == null ? 'Add Task' : 'Edit Task'),
        actions: [
          if (widget.task != null)
            IconButton(
              icon: const Icon(Icons.delete, color: Colors.red),
              onPressed: () async {
                final confirm = await showDialog<bool>(
                  context: context,
                  builder: (context) => AlertDialog(
                    title: const Text('Confirm Deletion'),
                    content: const Text('Are you sure you want to delete this task?'),
                    actions: [
                      TextButton(
                        onPressed: () => Navigator.pop(context, false),
                        child: const Text('Cancel'),
                      ),
                      TextButton(
                        onPressed: () => Navigator.pop(context, true),
                        child: const Text('Delete', style: TextStyle(color: Colors.red)),
                      ),
                    ],
                  ),
                );
                if (confirm == true && context.mounted) {
                  Navigator.pop(context);
                }
              },
            ),
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: ListView(
          children: [
            TextField(
              controller: _titleController,
              decoration: const InputDecoration(
                labelText: 'Task Title',
                border: OutlineInputBorder(),
              ),
              style: const TextStyle(fontSize: 18),
            ),
            const SizedBox(height: 16),
            TextField(
              controller: _contentController,
              decoration: const InputDecoration(
                labelText: 'Task Content',
                border: OutlineInputBorder(),
              ),
              maxLines: 4,
            ),
            const SizedBox(height: 16),
            ListTile(
              title: const Text('Deadline'),
              subtitle: Text(_deadline != null
                  ? DateUtils.formatDate(_deadline!)
                  : 'Not set'),
              trailing: const Icon(Icons.calendar_today),
              onTap: _selectDate,
            ),
            SwitchListTile(
              title: const Text('Completion Status'),
              value: _isCompleted,
              onChanged: (value) => setState(() => _isCompleted = value),
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _isSaving ? null : _saveTask,
              child: _isSaving
                  ? const SizedBox(
                      width: 20,
                      height: 20,
                      child: CircularProgressIndicator(
                        strokeWidth: 2,
                        valueColor: AlwaysStoppedAnimation<Color>(Colors.white),
                      ),
                    )
                  : const Padding(
                      padding: EdgeInsets.all(12),
                      child: Text('Save Task'),
                    ),
            ),
          ],
        ),
      ),
    );
  }
}

4. Settings Page Implementation (pages/setting_page.dart)

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:hive/hive.dart';
import '../providers/theme_provider.dart';
import '../models/task_model.dart';

class SettingPage extends ConsumerWidget {
  const SettingPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final themeMode = ref.watch(themeModeProvider);
    final themeNotifier = ref.read(themeModeProvider.notifier);

    return Scaffold(
      appBar: AppBar(title: const Text('Settings')),
      body: ListView(
        children: [
          SwitchListTile(
            title: const Text('Enable Notification Reminders'),
            value: true,
            onChanged: (value) {},
          ),
          ListTile(
            title: const Text('Dark Mode'),
            trailing: DropdownButton<ThemeMode>(
              value: themeMode,
              items: const [
                DropdownMenuItem(
                  value: ThemeMode.system,
                  child: Text('Follow System'),
                ),
                DropdownMenuItem(
                  value: ThemeMode.light,
                  child: Text('Light Mode'),
                ),
                DropdownMenuItem(
                  value: ThemeMode.dark,
                  child: Text('Dark Mode'),
                ),
              ],
              onChanged: (value) {
                if (value != null) {
                  themeNotifier.setThemeMode(value);
                }
              },
            ),
          ),
          ListTile(
            title: const Text('About Us'),
            trailing: const Icon(Icons.arrow_forward_ios),
            onTap: () {
              showAboutDialog(
                context: context,
                applicationName: 'To-Do List',
                applicationVersion: '1.0.0',
                children: const [
                  Padding(
                    padding: EdgeInsets.only(top: 16),
                    child: Text('A simple and efficient task management tool to help you better plan your life and work.'),
                  ),
                ],
              );
            },
          ),
          ListTile(
            title: const Text('Clear Cache'),
            trailing: const Icon(Icons.delete),
            onTap: () async {
              await Hive.box<Task>('tasks').clear();
              if (context.mounted) {
                ScaffoldMessenger.of(context).showSnackBar(
                  const SnackBar(content: Text('Cache cleared')),
                );
              }
            },
          ),
        ],
      ),
    );
  }
}

5. Routing Management Utility (utils/router.dart)

import 'package:flutter/material.dart';
import '../pages/home_page.dart';
import '../pages/detail_page.dart';
import '../pages/setting_page.dart';

class Router {
  static const String home = '/';
  static const String detail = '/detail';
  static const String setting = '/setting';

  static Map<String, WidgetBuilder> routes = {
    home: (context) => const HomePage(),
    setting: (context) => const SettingPage(),
  };

  static Route<dynamic> generateRoute(RouteSettings settings) {
    switch (settings.name) {
      case detail:
        final args = settings.arguments as Map<String, dynamic>?;
        return PageRouteBuilder(
          transitionDuration: const Duration(milliseconds: 300),
          pageBuilder: (context, animation, secondaryAnimation) => DetailPage(
            task: args?['task'],
            onSave: args?['onSave'],
          ),
          transitionsBuilder: (context, animation, secondaryAnimation, child) {
            const begin = Offset(1.0, 0.0);
            const end = Offset.zero;
            const curve = Curves.ease;
            final tween = Tween(begin: begin, end: end)
                .chain(CurveTween(curve: curve));
            return SlideTransition(
              position: animation.drive(tween),
              child: child,
            );
          },
        );
      default:
        return MaterialPageRoute(
          builder: (context) => const Scaffold(
            body: Center(child: Text('Page not found')),
          ),
        );
    }
  }
}

6. Date Utility Class (utils/date_utils.dart)

import 'package:intl/intl.dart';

class DateUtils {
  static String formatDate(DateTime date) {
    return DateFormat('yyyy-MM-dd').format(date);
  }

  static String formatDateTime(DateTime date) {
    return DateFormat('yyyy-MM-dd HH:mm').format(date);
  }

  static String formatFriendly(DateTime date) {
    final now = DateTime.now();
    final today = DateTime(now.year, now.month, now.day);
    final yesterday = today.subtract(const Duration(days: 1));
    final dateOnly = DateTime(date.year, date.month, date.day);

    if (dateOnly == today) {
      return 'Today ${DateFormat('HH:mm').format(date)}';
    } else if (dateOnly == yesterday) {
      return 'Yesterday ${DateFormat('HH:mm').format(date)}';
    } else if (date.year == now.year) {
      return DateFormat('MM-dd HH:mm').format(date);
    } else {
      return DateFormat('yyyy-MM-dd HH:mm').format(date);
    }
  }
}

IV. Summary and Extensions

Through this lesson, we've completed the full development process of the to-do list app, implementing the following features:

Data Persistence Solution:
- Integrated Dio for network requests, supporting CRUD operations for tasks
- Used Hive for local data storage, ensuring offline availability
- Implemented network and local data synchronization, with automatic local saving when network fails
State Management System:
- Implemented reactive state management with Riverpod
- Designed a comprehensive task state model including loading status and error messages
- Achieved atomicity of data operations, ensuring rollback capability or local data retention on failure
User Experience Optimization:
- Comprehensive loading states and error handling
- Local saving option when network requests fail
- Clear operation feedback to keep users informed of current status
- Support for dark mode switching to adapt to different usage scenarios
Interaction Design:
- Swipe-to-delete functionality for list items
- Page transition animations
- Real-time form operation feedback
- Pull-to-refresh for data updates

Flutter Lesson 16: Project Practice: Comprehensive Application Development (Part 1)

Ge Ji — Thu, 14 Aug 2025 01:14:47 +0000

today we'll be building a to-do list app to put our Flutter core knowledge into practice. As a classic introductory project, a to-do list covers key concepts like page navigation, data display, and basic interactions, making it perfect for reinforcing what we've learned so far.

I. Requirements Analysis and Page Design

1. Core Requirements Breakdown

The core goal of our to-do list app is to help users manage daily tasks. The key features we need to implement include:

Displaying all to-do tasks (categorized by completed/uncompleted status)
Viewing detailed information of individual tasks
Adding new tasks
Editing existing tasks
Marking task completion status
Deleting tasks
Basic settings (such as theme switch, about page, etc.)

2. Page Architecture Design

Based on the above requirements, we'll design three core pages:

Home Page (Task List Page): As the app's entry point, it will display a title and an add button at the top, with a list in the middle showing all tasks. It supports pull-to-refresh and swipe-to-delete operations. List items will show task titles, creation times, and completion status markers.
Detail Page: Accessed by clicking list items, it will display complete task information (title, content, creation time, deadline, etc.) with edit and delete buttons at the bottom.
Settings Page: Accessed via the settings icon on the home page, it will contain switch components (like notification toggle), an "About Us" entry, and a clear cache button.

3. Prototype Sketch Concept

The home page will use the classic "AppBar+ListView" structure, with a "+" icon button on the right side of the AppBar for adding tasks. The detail page will use a ScrollView to avoid content overflow, with an AppBar at the top providing a back button. The settings page will use ListView.builder to construct a list of settings items, where each item consists of an icon, text, and an operation component (switch/arrow).

II. Project Architecture Setup: Directory Structure

A reasonable directory structure makes the project more maintainable. We'll use the following organization:

1. pages Directory

Stores all complete pages, with each page in its own folder containing the corresponding Dart file. For example:

home_page: Code related to the home page
detail_page: Code related to the detail page
setting_page: Code related to the settings page

2. widgets Directory

Stores reusable custom components, with subdirectories categorized by function:

common: General components (like custom buttons, input fields)
task: Task-related components (like task list items, task status labels)

3. utils Directory

Stores utility classes and helper methods:

router.dart: Routing management tool
date_utils.dart: Date processing tool
storage_utils.dart: Local storage tool (to be implemented in detail in the next lesson)

4. models Directory

Stores data model classes, using Dart classes to define data structures:

// models/task_model.dart
class Task {
  final String id; // Unique task identifier
  String title; // Task title
  String content; // Task content
  DateTime createTime; // Creation time
  DateTime? deadline; // Deadline (optional)
  bool isCompleted; // Completion status

  Task({
    required this.id,
    required this.title,
    this.content = '',
    DateTime? createTime,
    this.deadline,
    this.isCompleted = false,
  }) : createTime = createTime ?? DateTime.now();
}

III. Implementation of Core Utility Classes

1. Date Processing Utility (utils/date_utils.dart)

import 'package:intl/intl.dart';

class DateUtils {
  /// Formats date to "yyyy-MM-dd"
  static String formatDate(DateTime date) {
    return DateFormat('yyyy-MM-dd').format(date);
  }

  /// Formats date to "yyyy-MM-dd HH:mm"
  static String formatDateTime(DateTime date) {
    return DateFormat('yyyy-MM-dd HH:mm').format(date);
  }

  /// Formats date to friendly display (e.g., "Today 14:30", "Yesterday 10:15")
  static String formatFriendly(DateTime date) {
    final now = DateTime.now();
    final today = DateTime(now.year, now.month, now.day);
    final yesterday = today.subtract(const Duration(days: 1));
    final dateOnly = DateTime(date.year, date.month, date.day);

    if (dateOnly == today) {
      return 'Today ${DateFormat('HH:mm').format(date)}';
    } else if (dateOnly == yesterday) {
      return 'Yesterday ${DateFormat('HH:mm').format(date)}';
    } else if (date.year == now.year) {
      return DateFormat('MM-dd HH:mm').format(date);
    } else {
      return DateFormat('yyyy-MM-dd HH:mm').format(date);
    }
  }
}

Before using, add the dependency to pubspec.yaml:

dependencies:
  intl: ^0.20.2

2. Routing Management Utility (utils/router.dart)

import 'package:flutter/material.dart';
import '../pages/home_page.dart';
import '../pages/detail_page.dart';
import '../pages/setting_page.dart';

class Router {
  // Route name constants
  static const String home = '/home';
  static const String detail = '/detail';
  static const String setting = '/setting';

  // Route configuration
  static Map<String, WidgetBuilder> routes = {
    home: (context) => const HomePage(),
    setting: (context) => const SettingPage(),
    // Detail page needs dynamic parameters, handled during navigation
  };

  // Generate routes
  static Route<dynamic> generateRoute(RouteSettings settings) {
    switch (settings.name) {
      case detail:
        final args = settings.arguments as Map<String, dynamic>?;
        return MaterialPageRoute(
          builder: (context) => DetailPage(
            task: args?['task'],
            onSave: args?['onSave'],
          ),
        );
      default:
        return MaterialPageRoute(
          builder: (context) => const Scaffold(
            body: Center(child: Text('Page not found')),
          ),
        );
    }
  }
}

3. Application Entry (main.dart)

import 'package:flutter/material.dart' hide Router;
import 'pages/home_page.dart';
import 'utils/router.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'To-Do List',
      // App theme configuration
      theme: ThemeData(
        primarySwatch: Colors.blue,
        visualDensity: VisualDensity.adaptivePlatformDensity,
        // Configure global text styles
        textTheme: const TextTheme(
          bodyLarge: TextStyle(fontSize: 16),
          bodyMedium: TextStyle(fontSize: 14),
          titleLarge: TextStyle(
            fontSize: 20,
            fontWeight: FontWeight.bold,
          ),
        ),
      ),
      // Disable debug mode banner
      debugShowCheckedModeBanner: false,
      // Initial route
      initialRoute: Router.home,
      // Route table
      routes: Router.routes,
      // Generate dynamic routes
      onGenerateRoute: Router.generateRoute,
      // Home page
      home: const HomePage(),
    );
  }
}

IV. Implementation of Basic Pages

1. Home Page Implementation (pages/home_page.dart)

The home page is the core entry point of the app, where we'll implement task list display, an add task button, and a settings entry.

import 'package:flutter/material.dart';
import '../widgets/task/task_item.dart';
import '../models/task_model.dart';
import 'detail_page.dart';
import 'setting_page.dart';

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  // Mock task data
  final List<Task> _tasks = [
    Task(
      id: '1',
      title: 'Learn Flutter',
      content: 'Complete the practical project in Lesson 16',
      deadline: DateTime.now().add(const Duration(days: 1)),
    ),
    Task(
      id: '2',
      title: 'Buy groceries',
      content: 'Milk, bread, fruits',
      isCompleted: true,
    ),
  ];

  // Navigate to detail page
  void _navigateToDetail({Task? task}) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => DetailPage(
          task: task,
          onSave: (newTask) {
            setState(() {
              if (task == null) {
                // Add new task
                _tasks.add(newTask);
              } else {
                // Edit existing task
                final index = _tasks.indexWhere((t) => t.id == task.id);
                if (index != -1) {
                  _tasks[index] = newTask;
                }
              }
            });
          },
        ),
      ),
    );
  }

  // Toggle task completion status
  void _toggleTaskStatus(String id) {
    setState(() {
      final task = _tasks.firstWhere((t) => t.id == id);
      task.isCompleted = !task.isCompleted;
    });
  }

  // Delete task
  void _deleteTask(String id) {
    setState(() {
      _tasks.removeWhere((t) => t.id == id);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('To-Do List'),
        actions: [
          // Settings button
          IconButton(
            icon: const Icon(Icons.settings),
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(builder: (context) => const SettingPage()),
              );
            },
          ),
        ],
      ),
      body: _tasks.isEmpty
          ? const Center(child: Text('No tasks yet, add one!'))
          : ListView.builder(
              padding: const EdgeInsets.all(16),
              itemCount: _tasks.length,
              itemBuilder: (context, index) {
                final task = _tasks[index];
                return TaskItem(
                  task: task,
                  onTap: () => _navigateToDetail(task: task),
                  onStatusChanged: _toggleTaskStatus,
                  onDelete: _deleteTask,
                );
              },
            ),
      // Add task button
      floatingActionButton: FloatingActionButton(
        child: const Icon(Icons.add),
        onPressed: () => _navigateToDetail(),
      ),
    );
  }
}

2. Detail Page Implementation (pages/detail_page.dart)

The detail page handles task viewing, editing, and deletion, requiring form input and data transmission.

import 'package:flutter/material.dart' hide DateUtils;
import '../models/task_model.dart';
import '../utils/date_utils.dart';

class DetailPage extends StatefulWidget {
  final Task? task;
  final Function(Task) onSave;

  const DetailPage({
    super.key,
    this.task,
    required this.onSave,
  });

  @override
  State<DetailPage> createState() => _DetailPageState();
}

class _DetailPageState extends State<DetailPage> {
  late final TextEditingController _titleController;
  late final TextEditingController _contentController;
  DateTime? _deadline;
  bool _isCompleted = false;

  @override
  void initState() {
    super.initState();
    // Initialize form data (edit mode)
    if (widget.task != null) {
      _titleController = TextEditingController(text: widget.task!.title);
      _contentController = TextEditingController(text: widget.task!.content);
      _deadline = widget.task!.deadline;
      _isCompleted = widget.task!.isCompleted;
    } else {
      // Add mode
      _titleController = TextEditingController();
      _contentController = TextEditingController();
    }
  }

  @override
  void dispose() {
    _titleController.dispose();
    _contentController.dispose();
    super.dispose();
  }

  // Save task
  void _saveTask() {
    if (_titleController.text.isEmpty) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Please enter a task title')),
      );
      return;
    }

    final task = Task(
      id: widget.task?.id ?? DateTime.now().microsecondsSinceEpoch.toString(),
      title: _titleController.text,
      content: _contentController.text,
      createTime: widget.task?.createTime ?? DateTime.now(),
      deadline: _deadline,
      isCompleted: _isCompleted,
    );

    widget.onSave(task);
    Navigator.pop(context);
  }

  // Select deadline
  Future<void> _selectDate() async {
    final picked = await showDatePicker(
      context: context,
      initialDate: _deadline ?? DateTime.now(),
      firstDate: DateTime.now(),
      lastDate: DateTime.now().add(const Duration(days: 365)),
    );
    if (picked != null) {
      setState(() => _deadline = picked);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.task == null ? 'Add Task' : 'Edit Task'),
        actions: [
          // Delete button (only shown in edit mode)
          if (widget.task != null)
            IconButton(
              icon: const Icon(Icons.delete, color: Colors.red),
              onPressed: () {
                Navigator.pop(context);
                // You can add a delete confirmation dialog here
              },
            ),
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: ListView(
          children: [
            // Task title input
            TextField(
              controller: _titleController,
              decoration: const InputDecoration(
                labelText: 'Task Title',
                border: OutlineInputBorder(),
              ),
              style: const TextStyle(fontSize: 18),
            ),
            const SizedBox(height: 16),
            // Task content input
            TextField(
              controller: _contentController,
              decoration: const InputDecoration(
                labelText: 'Task Content',
                border: OutlineInputBorder(),
              ),
              maxLines: 4,
            ),
            const SizedBox(height: 16),
            // Deadline selection
            ListTile(
              title: const Text('Deadline'),
              subtitle: Text(_deadline != null
                  ? DateUtils.formatDate(_deadline!)
                  : 'Not set'),
              trailing: const Icon(Icons.calendar_today),
              onTap: _selectDate,
            ),
            // Completion status toggle
            SwitchListTile(
              title: const Text('Completion Status'),
              value: _isCompleted,
              onChanged: (value) => setState(() => _isCompleted = value),
            ),
            const SizedBox(height: 20),
            // Save button
            ElevatedButton(
              onPressed: _saveTask,
              child: const Padding(
                padding: EdgeInsets.all(12),
                child: Text('Save Task'),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

3. Settings Page Implementation (pages/setting_page.dart)

The settings page provides basic configuration options for the app, displayed as a list of settings items.

import 'package:flutter/material.dart';

class SettingPage extends StatelessWidget {
  const SettingPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Settings'),
      ),
      body: ListView(
        children: [
          // Notification settings
          SwitchListTile(
            title: const Text('Enable Notification Reminders'),
            value: true, // Simulated enabled state
            onChanged: (value) {
              // Actual logic will be implemented in the state management section
            },
          ),
          // Dark mode settings (to be implemented in next lesson)
          ListTile(
            title: const Text('Dark Mode'),
            trailing: const Icon(Icons.arrow_forward_ios),
            onTap: () {
              // Navigate to dark mode settings page
            },
          ),
          // About us
          ListTile(
            title: const Text('About Us'),
            trailing: const Icon(Icons.arrow_forward_ios),
            onTap: () {
              showAboutDialog(
                context: context,
                applicationName: 'To-Do List',
                applicationVersion: '1.0.0',
                children: [
                  const Padding(
                    padding: EdgeInsets.only(top: 16),
                    child: Text('A simple and efficient task management tool to help you better plan your life and work.'),
                  ),
                ],
              );
            },
          ),
          // Clear cache
          ListTile(
            title: const Text('Clear Cache'),
            trailing: const Icon(Icons.delete),
            onTap: () {
              ScaffoldMessenger.of(context).showSnackBar(
                const SnackBar(content: Text('Cache cleared')),
              );
            },
          ),
        ],
      ),
    );
  }
}

V. Custom Component Implementation (widgets/task/task_item.dart)

Implementing the task list item component to improve code reusability:

import 'package:flutter/material.dart';
import '../../models/task_model.dart';
import '../../utils/date_utils.dart';

class TaskItem extends StatelessWidget {
  final Task task;
  final VoidCallback onTap;
  final Function(String) onStatusChanged;
  final Function(String) onDelete;

  const TaskItem({
    super.key,
    required this.task,
    required this.onTap,
    required this.onStatusChanged,
    required this.onDelete,
  });

  @override
  Widget build(BuildContext context) {
    return Card(
      elevation: 2,
      margin: const EdgeInsets.only(bottom: 12),
      child: ListTile(
        onTap: onTap,
        leading: Checkbox(
          value: task.isCompleted,
          onChanged: (value) => onStatusChanged(task.id),
        ),
        title: Text(
          task.title,
          style: TextStyle(
            decoration: task.isCompleted ? TextDecoration.lineThrough : null,
            color: task.isCompleted ? Colors.grey : null,
          ),
        ),
        subtitle: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          mainAxisSize: MainAxisSize.min,
          children: [
            if (task.deadline != null)
              Text(
                'Deadline: ${DateUtils.formatDate(task.deadline!)}',
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            Text(
              'Created: ${DateUtils.formatDate(task.createTime)}',
              style: const TextStyle(fontSize: 12, color: Colors.grey),
            ),
          ],
        ),
        // Right arrow icon
        trailing: const Icon(Icons.arrow_forward_ios, size: 18),
        onLongPress: () => onDelete(task.id),
      ),
    );
  }
}

Flutter Lesson 15: Custom Widgets and Component Encapsulation

Ge Ji — Wed, 13 Aug 2025 23:44:38 +0000

In Flutter development, as application scales grow, properly encapsulating custom widgets and reusable components becomes crucial. Well-designed components can significantly improve code reusability, reduce maintenance costs, and ensure UI consistency. This lesson will explore the design principles, implementation methods, and data transfer mechanisms for custom widgets in depth.

I. Principles of Encapsulating Reusable Components

Designing high-quality reusable components requires following core principles that help create flexible, robust, and maintainable components:

1. Single Responsibility Principle

Each component should focus on completing a single function. Avoid designing "all-purpose components." For example, a button component shouldn't handle form validation logic, and a list component shouldn't contain specific list item rendering logic.

Anti-pattern: A component that handles both network requests and UI display
Good practice: Separate network requests from UI display; UI components only handle data presentation

2. High Cohesion, Low Coupling

High cohesion: Related functions within a component should be tightly integrated, forming an organic whole
Low coupling: Components should communicate through well-defined interfaces, minimizing direct dependencies

3. Configuration Flexibility

Adapt components to different scenarios through parameter configuration, while balancing flexibility and complexity:

Provide reasonable default values to reduce usage costs
Key properties should be configurable, while secondary properties can be fixed
Use bool, enum, and other types to limit configuration options and avoid misuse

4. Extensibility

Design with extension points to facilitate future functionality expansion:

Allow custom child components through child or builder parameters
Extend base component functionality through inheritance or composition
Avoid hardcoding business logic

5. Consistency and Recognizability

Maintain component style consistency with the overall application design
Component behavior should meet user expectations (e.g., button click feedback)
Components with similar functionality should maintain consistent API design

6. Testability

Components should be easy to instantiate and test
Avoid creating global state within components
Critical logic should be testable independently

II. Basics of Custom Widgets

There are two main ways to create custom components in Flutter: composing existing widgets and creating custom RenderObjects. For most scenarios, we should prioritize composition as it's simpler and meets most needs.

1. Choosing Between StatelessWidget and StatefulWidget

StatelessWidget: Suitable for stateless components or components whose state is managed by parent components, such as static display components and pure UI components
StatefulWidget: Suitable for components with internal state management, such as counters and expandable/collapsible panels

Recommendation: Prefer StatelessWidget when possible, elevating state to parent components or state management frameworks to make components easier to test and reuse.

2. Component Naming Conventions

Use PascalCase, such as PrimaryButton, UserProfileCard
Names should accurately describe component functionality, avoiding excessive abstraction or generality
For components with similar basic functions but different styles, use consistent prefixes, such as PrimaryButton, SecondaryButton

III. Custom Widget Examples

1. Example 1: Button with Loading State (StatefulWidget)

This button component supports loading states, disabled states, custom styles, and other features, suitable for form submission, data requests, and similar scenarios.

import 'package:flutter/material.dart';

/// Button component with loading state
/// Supports normal, loading, and disabled states
/// Customizable colors, rounded corners, text styles, etc.
class LoadingButton extends StatefulWidget {
  /// Button text
  final String text;

  /// Click callback
  final VoidCallback? onPressed;

  /// Whether in loading state
  final bool isLoading;

  /// Button primary color
  final Color? color;

  /// Text color
  final Color textColor;

  /// Disabled state color
  final Color disabledColor;

  /// Disabled state text color
  final Color disabledTextColor;

  /// Button border radius
  final double borderRadius;

  /// Button padding
  final EdgeInsetsGeometry padding;

  /// Loading indicator color
  final Color indicatorColor;

  LoadingButton({
    super.key,
    required this.text,
    this.onPressed,
    this.isLoading = false,
    this.color,
    this.textColor = Colors.white,
    this.disabledColor = Colors.grey,
    this.disabledTextColor = Colors.grey,
    this.borderRadius = 8.0,
    this.padding = const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
    this.indicatorColor = Colors.white,
  }) : assert(text.isNotEmpty, "Button text cannot be empty");

  @override
  State<LoadingButton> createState() => _LoadingButtonState();
}

class _LoadingButtonState extends State<LoadingButton> {
  // Whether the button is clickable
  bool get _isEnabled => widget.onPressed != null && !widget.isLoading;

  @override
  Widget build(BuildContext context) {
    // Get the primary color from the theme as the default color
    final theme = Theme.of(context);
    final buttonColor = widget.color ?? theme.primaryColor;

    return ElevatedButton(
      onPressed: _isEnabled ? widget.onPressed : null,
      style: ElevatedButton.styleFrom(
        backgroundColor: _getButtonColor(buttonColor),
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(widget.borderRadius),
        ),
        padding: widget.padding,
        disabledBackgroundColor: widget.disabledColor,
      ),
      child: _buildButtonContent(buttonColor),
    );
  }

  // Get button color based on state
  Color _getButtonColor(Color defaultColor) {
    if (widget.isLoading) {
      return defaultColor.withOpacity(0.8);
    }
    return defaultColor;
  }

  // Build button content (text or loading indicator)
  Widget _buildButtonContent(Color buttonColor) {
    if (widget.isLoading) {
      return Row(
        mainAxisSize: MainAxisSize.min,
        children: [
          SizedBox(
            width: 20,
            height: 20,
            child: CircularProgressIndicator(
              strokeWidth: 2,
              valueColor: AlwaysStoppedAnimation<Color>(widget.indicatorColor),
            ),
          ),
          const SizedBox(width: 8),
          Text(
            "Loading...",
            style: TextStyle(
              color: _isEnabled ? widget.textColor : widget.disabledTextColor,
            ),
          ),
        ],
      );
    }

    return Text(
      widget.text,
      style: TextStyle(
        color: _isEnabled ? widget.textColor : widget.disabledTextColor,
      ),
    );
  }
}

// Usage example
class LoadingButtonDemo extends StatefulWidget {
  const LoadingButtonDemo({super.key});

  @override
  State<LoadingButtonDemo> createState() => _LoadingButtonDemoState();
}

class _LoadingButtonDemoState extends State<LoadingButtonDemo> {
  bool _isLoading = false;

  void _handlePress() async {
    // Simulate network request
    setState(() => _isLoading = true);
    await Future.delayed(const Duration(seconds: 2));
    setState(() => _isLoading = false);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Loading Button Demo')),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          children: [
            LoadingButton(
              text: "Submit",
              onPressed: _handlePress,
              isLoading: _isLoading,
            ),
            const SizedBox(height: 20),
            LoadingButton(
              text: "Disabled State",
              onPressed: null, // Button is disabled when onPressed is null
              color: Colors.grey,
            ),
            const SizedBox(height: 20),
            LoadingButton(
              text: "Custom Style",
              onPressed: () {},
              color: Colors.purple,
              borderRadius: 20,
              padding: const EdgeInsets.symmetric(horizontal: 30, vertical: 15),
            ),
          ],
        ),
      ),
    );
  }
}

2. Example 2: Common App Bar (StatelessWidget)

Implement a highly customizable app bar component that supports left/right buttons, custom title styles, background color settings, and other features.

import 'package:flutter/material.dart';

/// Common app bar component
/// Supports custom title, left/right buttons, background color, etc.
class CommonAppBar extends StatelessWidget implements PreferredSizeWidget {
  /// Title text
  final String title;

  /// Title widget, takes precedence over title
  final Widget? titleWidget;

  /// Left button
  final Widget? leading;

  /// List of right buttons
  final List<Widget>? actions;

  /// Background color
  final Color? backgroundColor;

  /// Title text style
  final TextStyle? titleStyle;

  /// Shadow elevation
  final double elevation;

  /// Whether title is centered
  final bool centerTitle;

  /// Left button click callback (only effective when leading is not customized)
  final VoidCallback? onLeadingPressed;

  const CommonAppBar({
    super.key,
    this.title = "",
    this.titleWidget,
    this.leading,
    this.actions,
    this.backgroundColor,
    this.titleStyle,
    this.elevation = 4.0,
    this.centerTitle = true,
    this.onLeadingPressed,
  });

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);

    return AppBar(
      title: titleWidget ?? 
        Text(
          title,
          style: titleStyle ?? 
            TextStyle(
              color: theme.appBarTheme.titleTextStyle?.color ?? Colors.white,
              fontSize: 18,
              fontWeight: FontWeight.bold,
            ),
        ),
      leading: leading ?? _buildDefaultLeading(context),
      actions: actions,
      backgroundColor: backgroundColor ?? theme.appBarTheme.backgroundColor,
      elevation: elevation,
      centerTitle: centerTitle,
    );
  }

  // Build default leading button (back button)
  Widget? _buildDefaultLeading(BuildContext context) {
    // Don't show back button if it's the first page in navigation stack
    if (Navigator.canPop(context)) {
      return IconButton(
        icon: const Icon(Icons.arrow_back),
        onPressed: onLeadingPressed ?? () => Navigator.pop(context),
      );
    }
    return null;
  }

  // Define app bar height, using default 56.0
  @override
  Size get preferredSize => const Size.fromHeight(56.0);
}

// Usage example
class CommonAppBarDemo extends StatelessWidget {
  const CommonAppBarDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: CommonAppBar(
        title: "Home Page",
        actions: [
          IconButton(
            icon: const Icon(Icons.search),
            onPressed: () => print("Search"),
          ),
          IconButton(
            icon: const Icon(Icons.more_vert),
            onPressed: () => print("More"),
          ),
        ],
      ),
      body: const Center(
        child: Text("Page content"),
      ),
    );
  }
}

// Custom title style example
class StyledAppBarDemo extends StatelessWidget {
  const StyledAppBarDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: CommonAppBar(
        titleWidget: const Row(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.star, color: Colors.yellow),
            SizedBox(width: 8),
            Text("Custom Title"),
          ],
        ),
        backgroundColor: Colors.purple,
        elevation: 0,
        leading: IconButton(
          icon: const Icon(Icons.menu),
          onPressed: () => print("Menu"),
        ),
      ),
      body: const Center(
        child: Text("Page with custom title"),
      ),
    );
  }
}

IV. Component Parameter Validation and Default Values

Good parameter design is key to component usability. Reasonable default values reduce usage costs, while strict parameter validation helps catch errors early.

1. Required vs. Optional Parameters

Use the required keyword to mark mandatory parameters, allowing the compiler to help check parameter completeness:

class CustomButton extends StatelessWidget {
  // Required parameters
  final String text;
  final VoidCallback onPressed;

  // Optional parameters
  final Color? color;

  // Mark required parameters with 'required'
  const CustomButton({
    super.key,
    required this.text,
    required this.onPressed,
    this.color,
  });

  // ...
}

2. Setting Default Values

Provide reasonable default values for optional parameters to reduce component complexity:

class CustomButton extends StatelessWidget {
  final String text;
  final VoidCallback onPressed;
  final Color color;
  final double borderRadius;
  final EdgeInsets padding;

  const CustomButton({
    super.key,
    required this.text,
    required this.onPressed,
    // Provide default values
    this.color = Colors.blue,
    this.borderRadius = 8.0,
    this.padding = const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
  });

  // ...
}

3. Parameter Validation

Use assert statements for parameter validation during development to catch errors early:

class Avatar extends StatelessWidget {
  final String url;
  final double radius;

  const Avatar({
    super.key,
    required this.url,
    this.radius = 24.0,
  }) : 
    // Validate that radius must be positive
    assert(radius > 0, "radius must be greater than 0"),
    // Validate that url is not empty
    assert(url.isNotEmpty, "url cannot be empty");

  @override
  Widget build(BuildContext context) {
    return ClipOval(
      child: Image.network(
        url,
        width: radius * 2,
        height: radius * 2,
        fit: BoxFit.cover,
      ),
    );
  }
}

4. Advanced Parameter Validation

For complex parameter validation logic, perform checks in initState or build methods:

class RangeSelector extends StatefulWidget {
  final double min;
  final double max;
  final double value;

  const RangeSelector({
    super.key,
    required this.min,
    required this.max,
    required this.value,
  });

  @override
  State<RangeSelector> createState() => _RangeSelectorState();
}

class _RangeSelectorState extends State<RangeSelector> {
  @override
  void initState() {
    super.initState();
    _validateParams();
  }

  // Complex parameter validation
  void _validateParams() {
    if (widget.min >= widget.max) {
      throw FlutterError("min must be less than max: min=${widget.min}, max=${widget.max}");
    }

    if (widget.value < widget.min || widget.value > widget.max) {
      throw FlutterError("value must be within [min, max] range: value=${widget.value}, min=${widget.min}, max=${widget.max}");
    }
  }

  // ...
}

V. Using InheritedWidget for Cross-Layer Data Transfer

In complex applications, component nesting can become very deep, making data passing through constructors cumbersome. InheritedWidget provides an efficient way to transfer data across layers, allowing child components to directly access data from upper layers.

1. InheritedWidget Basics

InheritedWidget is a special type of Widget that can pass data down the widget tree, allowing child components to access this data through BuildContext.

// 1. Create custom InheritedWidget
class ThemeData {
  final Color primaryColor;
  final Color secondaryColor;
  final TextStyle textStyle;

  ThemeData({
    required this.primaryColor,
    required this.secondaryColor,
    required this.textStyle,
  });
}

class AppTheme extends InheritedWidget {
  final ThemeData data;

  const AppTheme({
    super.key,
    required this.data,
    required super.child,
  });

  // Provide static method for child components to access
  static AppTheme? of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<AppTheme>();
  }

  // Whether to notify dependent child components when data changes
  @override
  bool updateShouldNotify(AppTheme oldWidget) {
    return data.primaryColor != oldWidget.data.primaryColor ||
           data.secondaryColor != oldWidget.data.secondaryColor ||
           data.textStyle != oldWidget.data.textStyle;
  }
}

2. Using in Widget Tree

// 2. Provide data at the top of the widget tree
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Create theme data
    final themeData = ThemeData(
      primaryColor: Colors.blue,
      secondaryColor: Colors.green,
      textStyle: const TextStyle(
        color: Colors.black87,
        fontSize: 16,
      ),
    );

    // Provide InheritedWidget
    return AppTheme(
      data: themeData,
      child: const MaterialApp(
        home: HomePage(),
      ),
    );
  }
}

// 3. Deep nested component accessing data
class DeepNestedWidget extends StatelessWidget {
  const DeepNestedWidget({super.key});

  @override
  Widget build(BuildContext context) {
    // Get theme data
    final appTheme = AppTheme.of(context);

    if (appTheme == null) {
      return const Text("Theme data not found");
    }

    return Container(
      color: appTheme.data.secondaryColor,
      padding: const EdgeInsets.all(16),
      child: Text(
        "Text using theme style",
        style: appTheme.data.textStyle,
      ),
    );
  }
}

// Intermediate component (no need to pass data)
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("InheritedWidget Example")),
      body: const Center(
        child: IntermediateWidget(),
      ),
    );
  }
}

class IntermediateWidget extends StatelessWidget {
  const IntermediateWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return const DeepNestedWidget();
  }
}

3. Dynamically Updating InheritedWidget Data

InheritedWidget itself is immutable. To achieve dynamic data updates, you need to combine it with StatefulWidget:

class ThemeProvider extends StatefulWidget {
  final Widget child;

  const ThemeProvider({
    super.key,
    required this.child,
  });

  // Provide static method to get state
  static _ThemeProviderState of(BuildContext context) {
    return context.findAncestorStateOfType<_ThemeProviderState>()!;
  }

  @override
  State<ThemeProvider> createState() => _ThemeProviderState();
}

class _ThemeProviderState extends State<ThemeProvider> {
  late ThemeData _themeData;

  @override
  void initState() {
    super.initState();
    // Initialize theme data
    _themeData = ThemeData(
      primaryColor: Colors.blue,
      secondaryColor: Colors.green,
      textStyle: const TextStyle(
        color: Colors.black87,
        fontSize: 16,
      ),
    );
  }

  // Method to toggle theme
  void toggleTheme() {
    setState(() {
      _themeData = _themeData.primaryColor == Colors.blue
          ? ThemeData(
              primaryColor: Colors.purple,
              secondaryColor: Colors.orange,
              textStyle: const TextStyle(
                color: Colors.white,
                fontSize: 16,
              ),
            )
          : ThemeData(
              primaryColor: Colors.blue,
              secondaryColor: Colors.green,
              textStyle: const TextStyle(
                color: Colors.black87,
                fontSize: 16,
              ),
            );
    });
  }

  @override
  Widget build(BuildContext context) {
    return AppTheme(
      data: _themeData,
      child: widget.child,
    );
  }
}

// Using dynamic theme
class ThemedButton extends StatelessWidget {
  const ThemedButton({super.key});

  @override
  Widget build(BuildContext context) {
    final appTheme = AppTheme.of(context);

    return ElevatedButton(
      onPressed: () {
        // Toggle theme
        ThemeProvider.of(context).toggleTheme();
      },
      style: ElevatedButton.styleFrom(
        backgroundColor: appTheme?.data.primaryColor,
      ),
      child: Text(
        "Toggle Theme",
        style: TextStyle(
          color: appTheme?.data.textStyle.color,
        ),
      ),
    );
  }
}

4. InheritedWidget Considerations

Performance considerations: The updateShouldNotify method should accurately determine if data has actually changed to avoid unnecessary rebuilds
Don't overuse: For simple scenarios, passing data through constructors is more straightforward
Data types: InheritedWidget is suitable for passing globally-shared data like configurations, themes, and user information
Dependency management: Using dependOnInheritedWidgetOfExactType establishes a dependency relationship that triggers rebuilds when data changes; using getInheritedWidgetOfExactType does not establish this relationship

VI. Component Communication Methods

In complex applications, components need to communicate with each other. Flutter provides various component communication methods:

1. Parent-Child Component Communication

Parent to child: Pass through constructor parameters
Child to parent: Pass through callback functions

class ParentWidget extends StatefulWidget {
  const ParentWidget({super.key});

  @override
  State<ParentWidget> createState() => _ParentWidgetState();
}

class _ParentWidgetState extends State<ParentWidget> {
  String _message = "Waiting for message...";

  // Callback to receive message from child component
  void _onMessageReceived(String message) {
    setState(() {
      _message = message;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text("Received message: $_message"),
        ChildWidget(
          // Parent passes data to child
          initialMessage: "Hello, child component",
          // Parent provides callback to child
          onSendMessage: _onMessageReceived,
        ),
      ],
    );
  }
}

class ChildWidget extends StatelessWidget {
  final String initialMessage;
  final ValueChanged<String> onSendMessage;

  const ChildWidget({
    super.key,
    required this.initialMessage,
    required this.onSendMessage,
  });

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text("Received initial message: $initialMessage"),
        ElevatedButton(
          onPressed: () {
            // Child sends message to parent through callback
            onSendMessage("Hello, parent component! This is the child component");
          },
          child: const Text("Send message to parent"),
        ),
      ],
    );
  }
}

2. Cross-Level Component Communication

In addition to InheritedWidget, you can use an event bus for cross-level component communication:

// Event bus implementation
class EventBus {
  // Singleton pattern
  static final EventBus _instance = EventBus._internal();
  factory EventBus() => _instance;
  EventBus._internal();

  // Store event subscribers
  final Map<Type, List<Function>> _eventListeners = {};

  // Subscribe to events
  void on<T>(void Function(T) listener) {
    if (!_eventListeners.containsKey(T)) {
      _eventListeners[T] = [];
    }
    _eventListeners[T]!.add(listener);
  }

  // Unsubscribe from events
  void off<T>(void Function(T) listener) {
    if (_eventListeners.containsKey(T)) {
      _eventListeners[T]!.remove(listener);
      if (_eventListeners[T]!.isEmpty) {
        _eventListeners.remove(T);
      }
    }
  }

  // Send event
  void emit<T>(T event) {
    if (_eventListeners.containsKey(T)) {
      // Make a copy of the list before iterating to avoid modification during iteration
      List<Function> listeners = List.from(_eventListeners[T]!);
      for (var listener in listeners) {
        listener(event);
      }
    }
  }
}

// Define event types
class UserLoginEvent {
  final String username;
  UserLoginEvent(this.username);
}

class UserLogoutEvent {
  UserLogoutEvent();
}

// Component that sends events
class LoginButton extends StatelessWidget {
  const LoginButton({super.key});

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        // Send login event
        EventBus().emit(UserLoginEvent("John Doe"));
      },
      child: const Text("Login"),
    );
  }
}

// Component that receives events
class UserStatusWidget extends StatefulWidget {
  const UserStatusWidget({super.key});

  @override
  State<UserStatusWidget> createState() => _UserStatusWidgetState();
}

class _UserStatusWidgetState extends State<UserStatusWidget> {
  String _status = "Not logged in";

  @override
  void initState() {
    super.initState();
    // Subscribe to login events
    EventBus().on<UserLoginEvent>((event) {
      setState(() {
        _status = "Logged in: ${event.username}";
      });
    });

    // Subscribe to logout events
    EventBus().on<UserLogoutEvent>((event) {
      setState(() {
        _status = "Not logged in";
      });
    });
  }

  @override
  void dispose() {
    // Unsubscribe to prevent memory leaks
    EventBus().off<UserLoginEvent>((event) {});
    EventBus().off<UserLogoutEvent>((event) {});
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Text("User status: $_status");
  }
}

3. Global State Management

For large applications, specialized state management solutions are recommended, such as:

Provider
Bloc/Cubit
Riverpod
GetX

These solutions build on InheritedWidget to provide more comprehensive state management capabilities, including state change notifications, dependency injection, and lifecycle management.

VII. Component Encapsulation Practice: Form Component Library

Next, we'll comprehensively apply the knowledge learned in this lesson to encapsulate a practical form component library, including input fields, selectors, form validation, and other features.

import 'package:flutter/material.dart';

// 1. Form field model
class FormFieldData {
  final String id;
  dynamic value;
  String? errorMessage;
  bool touched;

  FormFieldData({
    required this.id,
    this.value,
    this.errorMessage,
    this.touched = false,
  });
}

// 2. Form state management (using InheritedWidget)
class FormProvider extends InheritedWidget {
  final Map<String, FormFieldData> _fields = {};
  final void Function() onFormChanged;

  FormProvider({
    super.key,
    required super.child,
    required this.onFormChanged,
  });

  static FormProvider? of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<FormProvider>();
  }

  // Get field value
  dynamic getValue(String id) {
    return _fields[id]?.value;
  }

  // Set field value
  void setValue(String id, dynamic value, {bool validate = true}) {
    if (!_fields.containsKey(id)) {
      _fields[id] = FormFieldData(id: id);
    }
    _fields[id]!.value = value;
    _fields[id]!.touched = true;

    if (validate) {
      validateField(id);
    }

    onFormChanged();
  }

  // Validate field
  bool validateField(String id) {
    // In real applications, there would be more complex validation logic
    // Simplified here
    final field = _fields[id];
    if (field == null) return true;

    if (field.value == null || field.value.toString().isEmpty) {
      field.errorMessage = "This field cannot be empty";
      return false;
    }

    field.errorMessage = null;
    return true;
  }

  // Validate entire form
  bool validate() {
    bool isValid = true;
    for (var field in _fields.values) {
      field.touched = true;
      if (!validateField(field.id)) {
        isValid = false;
      }
    }
    onFormChanged();
    return isValid;
  }

  // Get field error message
  String? getError(String id) {
    return _fields[id]?.errorMessage;
  }

  // Check if field has been touched
  bool isTouched(String id) {
    return _fields[id]?.touched ?? false;
  }

  @override
  bool updateShouldNotify(FormProvider oldWidget) {
    return true;
  }
}

// 3. Form container component
class FormContainer extends StatefulWidget {
  final Widget child;
  final void Function(bool isValid) onValidationChanged;
  final void Function(Map<String, dynamic> values) onSubmit;

  const FormContainer({
    super.key,
    required this.child,
    required this.onValidationChanged,
    required this.onSubmit,
  });

  @override
  State<FormContainer> createState() => _FormContainerState();
}

class _FormContainerState extends State<FormContainer> {
  bool _isValid = false;

  void _onFormChanged(BuildContext context) {
    final formProvider = FormProvider.of(context);
    if (formProvider != null) {
      final isValid = formProvider.validate();
      setState(() {
        _isValid = isValid;
      });
      widget.onValidationChanged(isValid);
    }
  }

  void _handleSubmit(BuildContext context) {
    final formProvider = FormProvider.of(context);
    if (formProvider != null && formProvider.validate()) {
      // Collect form data
      final values = <String, dynamic>{};
      formProvider._fields.forEach((key, value) {
        values[key] = value.value;
      });
      widget.onSubmit(values);
    }
  }

  @override
  Widget build(BuildContext context) {
    return FormProvider(
      onFormChanged: () => _onFormChanged(context),
      child: Column(
        children: [
          widget.child,
          const SizedBox(height: 20),
          LoadingButton(
            text: "Submit",
            onPressed: _isValid ? () => _handleSubmit(context) : null,
          ),
        ],
      ),
    );
  }
}

// 4. Custom input field component
class FormInputField extends StatelessWidget {
  final String id;
  final String label;
  final String hintText;
  final TextInputType keyboardType;
  final bool obscureText;
  final FormFieldValidator<String>? validator;

  const FormInputField({
    super.key,
    required this.id,
    required this.label,
    this.hintText = "",
    this.keyboardType = TextInputType.text,
    this.obscureText = false,
    this.validator,
  });

  @override
  Widget build(BuildContext context) {
    final formProvider = FormProvider.of(context);
    if (formProvider == null) {
      return const SizedBox();
    }

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(
          label,
          style: const TextStyle(
            fontSize: 16,
            fontWeight: FontWeight.w500,
          ),
        ),
        const SizedBox(height: 8),
        TextFormField(
          initialValue: formProvider.getValue(id)?.toString() ?? "",
          keyboardType: keyboardType,
          obscureText: obscureText,
          decoration: InputDecoration(
            hintText: hintText,
            border: const OutlineInputBorder(),
            errorText: formProvider.isTouched(id) ? formProvider.getError(id) : null,
          ),
          onChanged: (value) {
            formProvider.setValue(id, value);
          },
        ),
        const SizedBox(height: 16),
      ],
    );
  }
}

// 5. Using the form component library
class RegisterFormDemo extends StatelessWidget {
  const RegisterFormDemo({super.key});

  void _onValidationChanged(bool isValid) {
    print("Form validation status: ${isValid ? "valid" : "invalid"}");
  }

  void _onSubmit(Map<String, dynamic> values) {
    print("Form submitted data: $values");
    // Form submission logic such as network requests can be handled here
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Registration Form')),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: FormContainer(
          onValidationChanged: _onValidationChanged,
          onSubmit: _onSubmit,
          child: Column(
            children: [
              FormInputField(
                id: "username",
                label: "Username",
                hintText: "Please enter your username",
              ),
              FormInputField(
                id: "email",
                label: "Email",
                hintText: "Please enter your email",
                keyboardType: TextInputType.emailAddress,
              ),
              FormInputField(
                id: "password",
                label: "Password",
                hintText: "Please enter your password",
                obscureText: true,
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Flutter Lesson 14: Animations and Transitions

Ge Ji — Wed, 13 Aug 2025 10:48:05 +0000

Animations are crucial for enhancing user experience, making app interfaces more lively, intuitive, and engaging. Flutter provides a powerful animation system that supports the implementation of various complex animation effects. This lesson will detailedly introduce the types and implementation methods of animations in Flutter, from basic implicit animations to complex custom explicit animations, helping you master the skills of adding smooth animation effects to your applications.

I. Flutter Animation Basics

Flutter's animation system is based on the following core concepts:

Animation: An object that generates values between 0.0 and 1.0. It doesn't contain rendering content itself but only provides animation values.
Curve: Defines the speed change of animation progress, such as acceleration and deceleration.
Controller: Controls the playback, pause, reverse, etc., of the animation and manages the animation life cycle.
Tween: Defines the start and end values of the animation, mapping the 0-1 values provided by Animation to the actual required value range.
Animatable: An object that can generate Tweens, supporting more complex value mapping.

Flutter animations are mainly divided into two categories:

Implicit animations: Animations automatically managed by Flutter, where you only need to define the start and end states.
Explicit animations: Animations that need to be manually controlled, providing more customization options and control capabilities.

II. Implicit Animations

Implicit animations are the simplest way to implement animations. Flutter provides a series of encapsulated implicit animation widgets that automatically transition smoothly from old values to new values when certain properties of the widget change.

1. AnimatedContainer

AnimatedContainer is the most commonly used implicit animation widget. When its properties (such as size, color, margin, etc.) change, it automatically produces transition animations.

class AnimatedContainerDemo extends StatefulWidget {
  const AnimatedContainerDemo({super.key});

  @override
  State<AnimatedContainerDemo> createState() => _AnimatedContainerDemoState();
}

class _AnimatedContainerDemoState extends State<AnimatedContainerDemo> {
  // State variable to control container properties
  bool _isExpanded = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AnimatedContainer Demo')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            AnimatedContainer(
              // Animation duration
              duration: const Duration(seconds: 1),
              // Animation curve
              curve: Curves.easeInOut,
              // Dynamically changing properties
              width: _isExpanded ? 300 : 100,
              height: _isExpanded ? 300 : 100,
              color: _isExpanded ? Colors.blue : Colors.red,
              padding: _isExpanded 
                  ? const EdgeInsets.all(20) 
                  : const EdgeInsets.all(10),
              // Content inside the container
              child: const Center(
                child: Text(
                  'Animate me!',
                  style: TextStyle(color: Colors.white, fontSize: 20),
                ),
              ),
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: () {
                // Toggle state when button is clicked to trigger animation
                setState(() {
                  _isExpanded = !_isExpanded;
                });
              },
              child: const Text('Toggle Animation'),
            )
          ],
        ),
      ),
    );
  }
}

2. Other Common Implicit Animation Widgets

Flutter also provides other implicit animation widgets for specific purposes:

AnimatedOpacity

Animation that controls the transparency change of a widget:

class AnimatedOpacityDemo extends StatefulWidget {
  const AnimatedOpacityDemo({super.key});

  @override
  State<AnimatedOpacityDemo> createState() => _AnimatedOpacityDemoState();
}

class _AnimatedOpacityDemoState extends State<AnimatedOpacityDemo> {
  double _opacity = 1.0;

  void _toggleOpacity() {
    setState(() {
      _opacity = _opacity == 1.0 ? 0.0 : 1.0;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AnimatedOpacity Demo')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            AnimatedOpacity(
              opacity: _opacity,
              duration: const Duration(seconds: 1),
              curve: Curves.fastOutSlowIn,
              child: Container(
                width: 200,
                height: 200,
                color: Colors.green,
                child: const Center(
                  child: Text(
                    'Fade me!',
                    style: TextStyle(color: Colors.white, fontSize: 24),
                  ),
                ),
              ),
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _toggleOpacity,
              child: const Text('Toggle Opacity'),
            )
          ],
        ),
      ),
    );
  }
}

AnimatedPositioned

Used in Stack to animate the position change of child widgets:

class AnimatedPositionedDemo extends StatefulWidget {
  const AnimatedPositionedDemo({super.key});

  @override
  State<AnimatedPositionedDemo> createState() => _AnimatedPositionedDemoState();
}

class _AnimatedPositionedDemoState extends State<AnimatedPositionedDemo> {
  bool _isMoved = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AnimatedPositioned Demo')),
      body: Stack(
        children: [
          AnimatedPositioned(
            duration: const Duration(seconds: 1),
            curve: Curves.bounceOut,
            left: _isMoved ? 200 : 50,
            top: _isMoved ? 300 : 100,
            width: 100,
            height: 100,
            child: Container(
              color: Colors.purple,
              child: const Center(
                child: Text(
                  'Move me!',
                  style: TextStyle(color: Colors.white),
                ),
              ),
            ),
          ),
          Positioned(
            bottom: 50,
            left: 0,
            right: 0,
            child: Center(
              child: ElevatedButton(
                onPressed: () {
                  setState(() {
                    _isMoved = !_isMoved;
                  });
                },
                child: const Text('Move the Box'),
              ),
            ),
          )
        ],
      ),
    );
  }
}

AnimatedPadding, AnimatedSize, etc.

There are other similar implicit animation widgets with similar usage:

AnimatedPadding: Controls the change of padding.
AnimatedSize: Automatically adjusts according to the size of the child widget and produces animation.
AnimatedTransform: Controls the animation of transformation effects.
AnimatedDefaultTextStyle: Controls the animation of text style changes.

3. Advantages and Disadvantages of Implicit Animations

Advantages:

Easy to use, just modify the state to trigger the animation.
No need to manually manage the animation controller.
Suitable for implementing simple transition effects.

Disadvantages:

Low customization, unable to implement complex animations.
Lack of fine control capabilities (such as pause, reverse playback).
Difficult to coordinate when multiple properties are animated at the same time.

III. Explicit Animations

Explicit animations require manual creation and management of animation controllers, providing more precise control and greater flexibility, suitable for implementing complex animation effects.

1. AnimationController and Animation

AnimationController is the core of explicit animations, responsible for controlling the time and state of the animation:

class BasicExplicitAnimation extends StatefulWidget {
  const BasicExplicitAnimation({super.key});

  @override
  State<BasicExplicitAnimation> createState() => _BasicExplicitAnimationState();
}

class _BasicExplicitAnimationState extends State<BasicExplicitAnimation> 
    with SingleTickerProviderStateMixin {
  // Animation controller
  late AnimationController _controller;
  // Animation object
  late Animation<double> _animation;

  @override
  void initState() {
    super.initState();

    // Initialize the animation controller
    _controller = AnimationController(
      vsync: this, // Associated with the current widget's lifecycle
      duration: const Duration(seconds: 2), // Animation duration
    );

    // Create an animation from 0 to 300
    _animation = Tween<double>(begin: 0, end: 300).animate(_controller)
      // Listen for animation value changes to trigger reconstruction
      ..addListener(() {
        setState(() {});
      })
      // Listen for animation state changes
      ..addStatusListener((status) {
        if (status == AnimationStatus.completed) {
          // Reverse playback after animation completion
          _controller.reverse();
        } else if (status == AnimationStatus.dismissed) {
          // Forward playback after animation returns to the starting point
          _controller.forward();
        }
      });

    // Start the animation
    _controller.forward();
  }

  @override
  void dispose() {
    // Release the animation controller resources
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Basic Explicit Animation')),
      body: Center(
        child: Container(
          width: _animation.value, // Use the animation value
          height: _animation.value,
          color: Colors.orange,
          child: const Center(
            child: Text(
              'Growing Box',
              style: TextStyle(color: Colors.white, fontSize: 18),
            ),
          ),
        ),
      ),
    );
  }
}

Note: SingleTickerProviderStateMixin provides a vsync callback to prevent the animation from continuing to consume resources when the widget is invisible. If multiple animation controllers are needed, TickerProviderStateMixin should be used.

2. CurvedAnimation

Using CurvedAnimation can add non-linear speed changes to the animation:

class CurvedAnimationDemo extends StatefulWidget {
  const CurvedAnimationDemo({super.key});

  @override
  State<CurvedAnimationDemo> createState() => _CurvedAnimationDemoState();
}

class _CurvedAnimationDemoState extends State<CurvedAnimationDemo> 
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _animation;

  @override
  void initState() {
    super.initState();

    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 2),
    );

    // Create a curved animation
    final curve = CurvedAnimation(
      parent: _controller,
      curve: Curves.bounceOut, // Bounce effect
      reverseCurve: Curves.bounceIn, // Curve for reverse direction
    );

    // Use the curved animation
    _animation = Tween<double>(begin: 50, end: 300).animate(curve)
      ..addListener(() {
        setState(() {});
      })
      ..addStatusListener((status) {
        if (status == AnimationStatus.completed) {
          _controller.reverse();
        } else if (status == AnimationStatus.dismissed) {
          _controller.forward();
        }
      });

    _controller.forward();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Curved Animation')),
      body: Center(
        child: Container(
          width: _animation.value,
          height: 100,
          color: Colors.pink,
          child: const Center(
            child: Text(
              'Bouncy!',
              style: TextStyle(color: Colors.white, fontSize: 20),
            ),
          ),
        ),
      ),
    );
  }
}

Flutter provides a variety of predefined curves, such as:

Curves.linear: Linear animation
Curves.easeIn, Curves.easeOut, Curves.easeInOut: Ease in, ease out, ease in and out
Curves.bounceIn, Curves.bounceOut: Bounce effect
Curves.elasticIn, Curves.elasticOut: Elastic effect

3. Tween and Multi-property Animations

Tween defines the value range of the animation, which can be any type. Multiple Tweens can be combined to implement multi-property animations:

class MultiPropertyAnimation extends StatefulWidget {
  const MultiPropertyAnimation({super.key});

  @override
  State<MultiPropertyAnimation> createState() => _MultiPropertyAnimationState();
}

class _MultiPropertyAnimationState extends State<MultiPropertyAnimation> 
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _sizeAnimation;
  late Animation<double> _opacityAnimation;
  late Animation<Color?> _colorAnimation;

  @override
  void initState() {
    super.initState();

    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 3),
    );

    // Size animation
    _sizeAnimation = Tween<double>(begin: 50, end: 250).animate(
      CurvedAnimation(parent: _controller, curve: Curves.easeInOut)
    );

    // Opacity animation
    _opacityAnimation = Tween<double>(begin: 0.2, end: 1.0).animate(
      CurvedAnimation(parent: _controller, curve: const Interval(0.3, 1.0)) // Start with delay
    );

    // Color animation
    _colorAnimation = ColorTween(begin: Colors.blue, end: Colors.green).animate(
      CurvedAnimation(parent: _controller, curve: const Interval(0.0, 0.7)) // End early
    );

    // Listen for animation value changes
    _controller.addListener(() {
      setState(() {});
    });

    // Play in a loop
    _controller.repeat(reverse: true);
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Multi-property Animation')),
      body: Center(
        child: Opacity(
          opacity: _opacityAnimation.value,
          child: Container(
            width: _sizeAnimation.value,
            height: _sizeAnimation.value,
            decoration: BoxDecoration(
              color: _colorAnimation.value,
              // Using borderRadius property
              borderRadius: BorderRadius.circular(_sizeAnimation.value / 10)
            ),
            child: const Center(
              child: Text(
                'Fancy!',
                style: TextStyle(color: Colors.white, fontSize: 24),
              ),
            ),
          ),
        ),
      ),
    );
  }
}

Interval can set different time intervals for different animation properties, enabling more complex animation choreography.

4. AnimatedBuilder for Optimizing Reconstruction Performance

Using addListener with setState will cause the entire widget to rebuild. Using AnimatedBuilder can only rebuild the part that needs animation, improving performance:

class AnimatedBuilderDemo extends StatefulWidget {
  const AnimatedBuilderDemo({super.key});

  @override
  State<AnimatedBuilderDemo> createState() => _AnimatedBuilderDemoState();
}

class _AnimatedBuilderDemoState extends State<AnimatedBuilderDemo> 
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _rotationAnimation;

  @override
  void initState() {
    super.initState();

    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 5),
    );

    _rotationAnimation = Tween<double>(begin: 0, end: 2 * 3.14159).animate(
      CurvedAnimation(parent: _controller, curve: Curves.linear)
    );

    _controller.repeat();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AnimatedBuilder Demo')),
      body: Center(
        // Wrap the part that needs animation with AnimatedBuilder
        child: AnimatedBuilder(
          animation: _rotationAnimation,
          // The builder method only rebuilds the animation-related part
          builder: (context, child) {
            return Transform.rotate(
              angle: _rotationAnimation.value,
              child: child, // Pass in the static child widget to avoid repeated construction
            );
          },
          // Static child widget, which will be built only once
          child: Container(
            width: 200,
            height: 200,
            decoration: BoxDecoration(
              color: Colors.amber,
              // Using borderRadius property
              borderRadius: BorderRadius.circular(20)
            ),
            child: const Center(
              child: Text(
                'Spinning!',
                style: TextStyle(color: Colors.black, fontSize: 24),
              ),
            ),
          ),
        ),
      ),
    );
  }
}

IV. Page Transition Animations

Flutter allows custom transition animations between pages. Various transition effects can be achieved through PageRouteBuilder.

1. Fade Transition

class FadeTransitionDemo extends StatelessWidget {
  const FadeTransitionDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Fade Transition Demo')),
      body: Center(
        child: ElevatedButton(
          child: const Text('Go to Second Screen'),
          onPressed: () {
            // Navigate to the second page with custom transition animation
            Navigator.push(
              context,
              PageRouteBuilder(
                transitionDuration: const Duration(seconds: 1), // Transition time
                // Build page content
                pageBuilder: (context, animation, secondaryAnimation) {
                  return const SecondScreen();
                },
                // Build transition effect
                transitionsBuilder: (context, animation, secondaryAnimation, child) {
                  // Fade transition
                  return FadeTransition(
                    opacity: animation,
                    child: child,
                  );
                },
              ),
            );
          },
        ),
      ),
    );
  }
}

class SecondScreen extends StatelessWidget {
  const SecondScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Second Screen'),
        backgroundColor: Colors.green,
      ),
      body: Center(
        child: ElevatedButton(
          child: const Text('Go Back'),
          onPressed: () {
            Navigator.pop(context);
          },
        ),
      ),
    );
  }
}

2. Slide Transition

// Use this transition when navigating
PageRouteBuilder(
  transitionDuration: const Duration(milliseconds: 500),
  pageBuilder: (context, animation, secondaryAnimation) {
    return const SecondScreen();
  },
  transitionsBuilder: (context, animation, secondaryAnimation, child) {
    // Slide transition - slide in from the right
    const begin = Offset(1.0, 0.0); // Starting position (right side)
    const end = Offset.zero; // Ending position (inside the screen)
    const curve = Curves.easeInOut;

    // Create an animation from begin to end
    var tween = Tween(begin: begin, end: end).chain(CurveTween(curve: curve));
    var offsetAnimation = animation.drive(tween);

    return SlideTransition(
      position: offsetAnimation,
      child: child,
    );
  },
)

3. Scale Transition

PageRouteBuilder(
  transitionDuration: const Duration(milliseconds: 500),
  pageBuilder: (context, animation, secondaryAnimation) {
    return const SecondScreen();
  },
  transitionsBuilder: (context, animation, secondaryAnimation, child) {
    // Scale transition
    return ScaleTransition(
      scale: animation.drive(
        Tween(begin: 0.0, end: 1.0).chain(
          CurveTween(curve: Curves.bounceOut)
        )
      ),
      child: child,
    );
  },
)

4. Combined Transition Effects

Multiple transition effects can be combined:

PageRouteBuilder(
  transitionDuration: const Duration(milliseconds: 700),
  pageBuilder: (context, animation, secondaryAnimation) {
    return const SecondScreen();
  },
  transitionsBuilder: (context, animation, secondaryAnimation, child) {
    // Combine scale and fade effects
    return ScaleTransition(
      scale: animation.drive(
        Tween(begin: 0.8, end: 1.0).chain(
          CurveTween(curve: Curves.easeInOut)
        )
      ),
      child: FadeTransition(
        opacity: animation.drive(
          Tween(begin: 0.0, end: 1.0).chain(
            CurveTween(curve: const Interval(0.2, 1.0))
          )
        ),
        child: child,
      ),
    );
  },
)

V. Example: Button Click Scale Effect

Implement a button with click feedback that produces a complete scale effect when clicked:

class BounceButton extends StatefulWidget {
  final Widget child;
  final VoidCallback onPressed;
  final double scaleFactor;
  final Duration duration;

  const BounceButton({
    super.key,
    required this.child,
    required this.onPressed,
    this.scaleFactor = 0.8,
    this.duration = const Duration(milliseconds: 300),
  });

  @override
  State<BounceButton> createState() => _BounceButtonState();
}

class _BounceButtonState extends State<BounceButton>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _scaleAnimation;

  @override
  void initState() {
    super.initState();

    _controller = AnimationController(vsync: this, duration: widget.duration);

    _scaleAnimation = Tween<double>(
      begin: 1.0,
      end: widget.scaleFactor,
    ).animate(CurvedAnimation(parent: _controller, curve: Curves.easeInOut));
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  // Handle press - do not execute forward directly, controlled uniformly by onTapUp
  void _onTapDown(TapDownDetails details) {
    print("Pressed: Prepare to start animation");
  }

  // Handle release - control the animation process uniformly to ensure complete execution
  void _onTapUp(TapUpDetails details) {
    print("Released: Start animation process");
    // First execute the complete forward animation, then the reverse animation, and finally trigger the callback
    _controller.forward().then((_) {
      _controller.reverse().then((_) {
        widget.onPressed();
      });
    });
  }

  // Handle cancel
  void _onTapCancel() {
    print("Cancelled: Reverse animation");
    _controller.reverse();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _scaleAnimation,
      builder: (context, child) {
        return Transform.scale(scale: _scaleAnimation.value, child: child);
      },
      child: GestureDetector(
        onTapDown: _onTapDown,
        onTapUp: _onTapUp,
        onTapCancel: _onTapCancel,
        behavior: HitTestBehavior.opaque,
        child: widget.child,
      ),
    );
  }
}

// Usage example
class BounceButtonDemo extends StatelessWidget {
  const BounceButtonDemo({super.key});

  void _handlePress() {
    print('Button pressed!');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Bounce Button Demo')),
      body: Center(
        child: BounceButton(
          onPressed: _handlePress,
          scaleFactor: 0.7,
          child: Container(
            padding: const EdgeInsets.symmetric(horizontal: 40, vertical: 20),
            decoration: BoxDecoration(
              color: Colors.blue,
              borderRadius: BorderRadius.circular(12),
              boxShadow: const [
                BoxShadow(
                  color: Colors.black26,
                  blurRadius: 10,
                  offset: Offset(0, 4),
                ),
              ],
            ),
            child: const Text(
              'Click Me',
              style: TextStyle(
                color: Colors.white,
                fontSize: 20,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        ),
      ),
    );
  }
}

Optimization Description:

Do not directly execute _controller.forward() in _onTapDown, only mark the button as pressed.
Uniformly control the animation process in _onTapUp, first execute the complete forward animation (button shrinks), then the reverse animation (button recovers), and finally trigger the business callback.

VII. Animation Performance Optimization

Animation performance is crucial for user experience. Here are some optimization suggestions:

Use AnimatedBuilder to reduce reconstruction scope: Only rebuild the part that needs animation, avoiding the entire page reconstruction.
Avoid complex calculations during animation: Animation callbacks should be as concise as possible; complex calculations will cause stuttering.
Use hardware acceleration: Most animations will automatically use hardware acceleration, but operations that trigger software rendering (such as using saveLayer) should be avoided.
Control animation frame rate: In most cases, 60fps is sufficient; a higher frame rate will consume more resources.
Set reasonable animation duration: Generally, the animation duration is between 200-300ms; a longer duration will make users feel delayed.
Use RepaintBoundary to isolate redraw areas: For animation widgets that are frequently redrawn, wrap them with RepaintBoundary to avoid affecting other widgets.

RepaintBoundary(
  child: AnimatedWidget(...),
)

7 . Avoid using opacity animation and shadow at the same time: Using these two effects together will reduce performance; shadows can be temporarily removed during animation.

Flutter Lesson 13: Local Storage

Ge Ji — Tue, 12 Aug 2025 13:14:10 +0000

In mobile application development, local storage is a critical feature used to save user preferences, offline data, login status, and other information. Flutter provides various local storage solutions suitable for different scenario requirements. This lesson will introduce commonly used local storage methods in Flutter, including lightweight key-value storage and more complex database storage, with practical examples demonstrating their real-world applications.

I. Overview of Local Storage

Local storage plays an important role in mobile applications, with main application scenarios including:

Saving user login status to avoid repeated logins
Storing application configurations and user preferences
Caching network request data to implement offline functionality
Storing structured data such as chat records and task lists

Common local storage solutions in Flutter include:

shared_preferences: Lightweight key-value storage, suitable for simple data
sqflite: SQLite database wrapper, suitable for structured data
hive: High-performance NoSQL database, pure Dart implementation
flutter_secure_storage: Secure storage, suitable for sensitive information like tokens

This lesson focuses on the first two most commonly used storage solutions.

II. Lightweight Storage: shared_preferences

shared_preferences is a plugin provided by the Flutter community for storing simple key-value pair data. It uses NSUserDefaults on iOS and SharedPreferences on Android, providing a consistent cross-platform API.

1. Installation and Configuration

Add the dependency to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^2.5.3  # Use the latest version

Run flutter pub get to install the dependency.

2. Basic Usage

shared_preferences supports storing data types including: String, int, double, bool, and List.

Basic operation steps:

Obtain the SharedPreferences instance
Use corresponding methods for data reading and writing
No need to manually close the instance

import 'package:shared_preferences/shared_preferences.dart';

// Save data
Future<void> saveData() async {
  // Get instance
  final prefs = await SharedPreferences.getInstance();

  // Store different types of data
  await prefs.setString('username', 'john_doe');
  await prefs.setInt('age', 30);
  await prefs.setDouble('height', 1.75);
  await prefs.setBool('isPremium', false);
  await prefs.setStringList('hobbies', ['reading', 'sports', 'coding']);
}

// Read data
Future<void> readData() async {
  final prefs = await SharedPreferences.getInstance();

  // Read data, providing default values
  String username = prefs.getString('username') ?? 'Guest';
  int age = prefs.getInt('age') ?? 0;
  double height = prefs.getDouble('height') ?? 0.0;
  bool isPremium = prefs.getBool('isPremium') ?? false;
  List<String> hobbies = prefs.getStringList('hobbies') ?? [];

  print('Username: $username');
  print('Age: $age');
  print('Height: $height');
  print('Is Premium: $isPremium');
  print('Hobbies: $hobbies');
}

// Update data
Future<void> updateData() async {
  final prefs = await SharedPreferences.getInstance();
  // Update values for existing keys
  await prefs.setInt('age', 31);
  await prefs.setBool('isPremium', true);
}

// Delete data
Future<void> deleteData() async {
  final prefs = await SharedPreferences.getInstance();
  // Delete a specific key
  await prefs.remove('height');

  // Clear all data
  // await prefs.clear();
}

3. shared_preferences Encapsulation

To simplify usage and avoid code duplication, you can encapsulate a utility class:

import 'package:shared_preferences/shared_preferences.dart';

class PrefsService {
  // Singleton pattern
  static final PrefsService _instance = PrefsService._internal();
  factory PrefsService() => _instance;
  PrefsService._internal();

  late SharedPreferences _prefs;

  // Initialization
  Future<void> init() async {
    _prefs = await SharedPreferences.getInstance();
  }

  // Storage methods
  Future<void> setString(String key, String value) async {
    await _prefs.setString(key, value);
  }

  Future<void> setInt(String key, int value) async {
    await _prefs.setInt(key, value);
  }

  Future<void> setDouble(String key, double value) async {
    await _prefs.setDouble(key, value);
  }

  Future<void> setBool(String key, bool value) async {
    await _prefs.setBool(key, value);
  }

  Future<void> setStringList(String key, List<String> value) async {
    await _prefs.setStringList(key, value);
  }

  // Reading methods
  String getString(String key, {String defaultValue = ''}) {
    return _prefs.getString(key) ?? defaultValue;
  }

  int getInt(String key, {int defaultValue = 0}) {
    return _prefs.getInt(key) ?? defaultValue;
  }

  double getDouble(String key, {double defaultValue = 0.0}) {
    return _prefs.getDouble(key) ?? defaultValue;
  }

  bool getBool(String key, {bool defaultValue = false}) {
    return _prefs.getBool(key) ?? defaultValue;
  }

  List<String> getStringList(String key, {List<String> defaultValue = const []}) {
    return _prefs.getStringList(key) ?? defaultValue;
  }

  // Deletion methods
  Future<void> remove(String key) async {
    await _prefs.remove(key);
  }

  Future<void> clear() async {
    await _prefs.clear();
  }

  // Check if key exists
  bool containsKey(String key) {
    return _prefs.containsKey(key);
  }
}

Using the encapsulated class:

// Initialization (usually at app startup)
await PrefsService().init();

// Store data
await PrefsService().setString('username', 'jane_smith');
await PrefsService().setInt('score', 100);

// Read data
String username = PrefsService().getString('username');
int score = PrefsService().getInt('score');

4. shared_preferences Use Cases and Limitations

Suitable scenarios:

Storing user preferences (e.g., theme mode, language selection)
Saving simple user states (e.g., login status flag)
Storing small amounts of configuration information

Limitations:

Not suitable for storing large amounts of data
Does not support complex data structures
Data is stored in plain text files, not suitable for sensitive information
No query functionality, can only get values by key

III. Database Storage: sqflite Basics

For scenarios requiring storage of large amounts of structured data, sqflite is a better choice. sqflite is a wrapper for SQLite databases in Flutter, providing full SQL operation capabilities.

1. Installation and Configuration

Add dependencies to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  sqflite: ^2.4.2  # SQLite database
  path: ^1.9.1     # For handling file paths

Run flutter pub get to install dependencies.

2. Basic Database Operations

SQLite database operations mainly include: creating databases and tables, inserting data, querying data, updating data, and deleting data.

Creating Databases and Tables

import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart';

class DatabaseHelper {
  // Database name
  static const _databaseName = "MyDatabase.db";
  // Database version
  static const _databaseVersion = 1;

  // Table name
  static const table = 'notes';

  // Column names
  static const columnId = '_id';
  static const columnTitle = 'title';
  static const columnContent = 'content';
  static const columnCreatedAt = 'created_at';

  // Singleton pattern
  DatabaseHelper._privateConstructor();
  static final DatabaseHelper instance = DatabaseHelper._privateConstructor();

  // Database instance
  static Database? _database;
  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  // Initialize database
  _initDatabase() async {
    String path = join(await getDatabasesPath(), _databaseName);
    return await openDatabase(path,
        version: _databaseVersion,
        onCreate: _onCreate);
  }

  // Create table
  Future _onCreate(Database db, int version) async {
    await db.execute('''
          CREATE TABLE $table (
            $columnId INTEGER PRIMARY KEY AUTOINCREMENT,
            $columnTitle TEXT NOT NULL,
            $columnContent TEXT,
            $columnCreatedAt TEXT NOT NULL
          )
          ''');
  }
}

Inserting Data

// Insert data
Future<int> insertNote(Map<String, dynamic> note) async {
  Database db = await DatabaseHelper.instance.database;
  // Insert data and return ID of new record
  return await db.insert(DatabaseHelper.table, note);
}

// Usage example
void addNote() async {
  Map<String, dynamic> newNote = {
    DatabaseHelper.columnTitle: 'First Note',
    DatabaseHelper.columnContent: 'This is my first note',
    DatabaseHelper.columnCreatedAt: DateTime.now().toIso8601String()
  };

  int id = await insertNote(newNote);
  print('Inserted note with id: $id');
}

Querying Data

// Query all data
Future<List<Map<String, dynamic>>> queryAllNotes() async {
  Database db = await DatabaseHelper.instance.database;
  return await db.query(DatabaseHelper.table);
}

// Query by ID
Future<List<Map<String, dynamic>>> queryNote(int id) async {
  Database db = await DatabaseHelper.instance.database;
  return await db.query(DatabaseHelper.table,
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [id]);
}

// Usage example
void getNotes() async {
  List<Map<String, dynamic>> notes = await queryAllNotes();
  print('All notes: $notes');

  if (notes.isNotEmpty) {
    List<Map<String, dynamic>> singleNote = await queryNote(notes[0][DatabaseHelper.columnId]);
    print('First note: $singleNote');
  }
}

Updating Data

// Update data
Future<int> updateNote(Map<String, dynamic> note) async {
  Database db = await DatabaseHelper.instance.database;
  int id = note[DatabaseHelper.columnId];
  // Return number of affected rows
  return await db.update(DatabaseHelper.table, note,
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [id]);
}

// Usage example
void modifyNote(int noteId) async {
  Map<String, dynamic> updatedNote = {
    DatabaseHelper.columnId: noteId,
    DatabaseHelper.columnTitle: 'Updated Note',
    DatabaseHelper.columnContent: 'This note has been updated',
    DatabaseHelper.columnCreatedAt: DateTime.now().toIso8601String()
  };

  int rowsAffected = await updateNote(updatedNote);
  print('Updated $rowsAffected rows');
}

Deleting Data

// Delete data
Future<int> deleteNote(int id) async {
  Database db = await DatabaseHelper.instance.database;
  // Return number of affected rows
  return await db.delete(DatabaseHelper.table,
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [id]);
}

// Usage example
void removeNote(int noteId) async {
  int rowsDeleted = await deleteNote(noteId);
  print('Deleted $rowsDeleted rows');
}

3. Database Version Migration

When application upgrades require database structure modifications, database migration is necessary:

// Modify _initDatabase method in DatabaseHelper class
_initDatabase() async {
  String path = join(await getDatabasesPath(), _databaseName);
  return await openDatabase(path,
      version: _databaseVersion,
      onCreate: _onCreate,
      onUpgrade: _onUpgrade, // Add upgrade callback
      onDowngrade: onDatabaseDowngradeDelete // Delete database on downgrade
  );
}

// Database upgrade
Future _onUpgrade(Database db, int oldVersion, int newVersion) async {
  if (oldVersion < 2) {
    // Version 2 adds a 'category' column
    await db.execute('''
      ALTER TABLE ${DatabaseHelper.table} 
      ADD COLUMN category TEXT
    ''');
  }
  if (oldVersion < 3) {
    // Version 3 adds a 'priority' column
    await db.execute('''
      ALTER TABLE ${DatabaseHelper.table} 
      ADD COLUMN priority INTEGER DEFAULT 0
    ''');
  }
}

4. Model Classes and Database Operation Encapsulation

To better manage data, you typically create model classes and encapsulate database operations:

// Note model class
class Note {
  final int? id;
  final String title;
  final String? content;
  final String createdAt;
  final String? category;
  final int priority;

  Note({
    this.id,
    required this.title,
    this.content,
    required this.createdAt,
    this.category,
    this.priority = 0,
  });

  // Convert from Map to Note object
  factory Note.fromMap(Map<String, dynamic> map) {
    return Note(
      id: map[DatabaseHelper.columnId],
      title: map[DatabaseHelper.columnTitle],
      content: map[DatabaseHelper.columnContent],
      createdAt: map[DatabaseHelper.columnCreatedAt],
      category: map['category'],
      priority: map['priority'] ?? 0,
    );
  }

  // Convert to Map
  Map<String, dynamic> toMap() {
    return {
      DatabaseHelper.columnId: id,
      DatabaseHelper.columnTitle: title,
      DatabaseHelper.columnContent: content,
      DatabaseHelper.columnCreatedAt: createdAt,
      'category': category,
      'priority': priority,
    };
  }
}

// Encapsulate database operations
class NoteService {
  // Insert note
  Future<int> insertNote(Note note) async {
    Database db = await DatabaseHelper.instance.database;
    return await db.insert(DatabaseHelper.table, note.toMap());
  }

  // Get all notes
  Future<List<Note>> getAllNotes() async {
    Database db = await DatabaseHelper.instance.database;
    List<Map<String, dynamic>> maps = await db.query(DatabaseHelper.table);
    return List.generate(maps.length, (i) => Note.fromMap(maps[i]));
  }

  // Get note by ID
  Future<Note?> getNoteById(int id) async {
    Database db = await DatabaseHelper.instance.database;
    List<Map<String, dynamic>> maps = await db.query(
      DatabaseHelper.table,
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [id],
    );
    if (maps.isNotEmpty) {
      return Note.fromMap(maps.first);
    }
    return null;
  }

  // Update note
  Future<int> updateNote(Note note) async {
    Database db = await DatabaseHelper.instance.database;
    return await db.update(
      DatabaseHelper.table,
      note.toMap(),
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [note.id],
    );
  }

  // Delete note
  Future<int> deleteNote(int id) async {
    Database db = await DatabaseHelper.instance.database;
    return await db.delete(
      DatabaseHelper.table,
      where: '${DatabaseHelper.columnId} = ?',
      whereArgs: [id],
    );
  }

  // Query notes by category
  Future<List<Note>> getNotesByCategory(String category) async {
    Database db = await DatabaseHelper.instance.database;
    List<Map<String, dynamic>> maps = await db.query(
      DatabaseHelper.table,
      where: 'category = ?',
      whereArgs: [category],
    );
    return List.generate(maps.length, (i) => Note.fromMap(maps[i]));
  }

  // Query sorted by priority
  Future<List<Note>> getNotesSortedByPriority() async {
    Database db = await DatabaseHelper.instance.database;
    List<Map<String, dynamic>> maps = await db.query(
      DatabaseHelper.table,
      orderBy: 'priority DESC',
    );
    return List.generate(maps.length, (i) => Note.fromMap(maps[i]));
  }
}

IV. Example: Saving User Login State

The following implements a function to save user login state using shared_preferences to store login information:

import 'package:shared_preferences/shared_preferences.dart';

class AuthService {
  static const _tokenKey = 'auth_token';
  static const _userIdKey = 'user_id';
  static const _usernameKey = 'username';

  // Save login state
  Future<void> saveLoginState({
    required String token,
    required String userId,
    required String username,
  }) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(_tokenKey, token);
    await prefs.setString(_userIdKey, userId);
    await prefs.setString(_usernameKey, username);
  }

  // Get current logged-in user information
  Future<Map<String, String>?> getCurrentUser() async {
    final prefs = await SharedPreferences.getInstance();
    final token = prefs.getString(_tokenKey);
    final userId = prefs.getString(_userIdKey);
    final username = prefs.getString(_usernameKey);

    if (token != null && userId != null && username != null) {
      return {
        'token': token,
        'userId': userId,
        'username': username,
      };
    }
    return null;
  }

  // Check if user is logged in
  Future<bool> isLoggedIn() async {
    final user = await getCurrentUser();
    return user != null;
  }

  // Logout, clear login state
  Future<void> logout() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.remove(_tokenKey);
    await prefs.remove(_userIdKey);
    await prefs.remove(_usernameKey);
  }

  // Get authentication token
  Future<String?> getAuthToken() async {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getString(_tokenKey);
  }
}

Checking login state when the application starts:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Check login state
  AuthService authService = AuthService();
  bool isLoggedIn = await authService.isLoggedIn();

  runApp(MyApp(isLoggedIn: isLoggedIn));
}

class MyApp extends StatelessWidget {
  final bool isLoggedIn;

  const MyApp({super.key, required this.isLoggedIn});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Local Storage Demo',
      home: isLoggedIn ? const HomeScreen() : const LoginScreen(),
    );
  }
}

class LoginScreen extends StatefulWidget {
  const LoginScreen({super.key});

  @override
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  final _usernameController = TextEditingController();
  final _passwordController = TextEditingController();
  final _authService = AuthService();
  bool _isLoading = false;

  Future<void> _login(BuildContext context) async {
    setState(() {
      _isLoading = true;
    });

    // Simulate API login request
    await Future.delayed(const Duration(seconds: 2));

    // In a real application, you should validate username and password
    if (_usernameController.text.isNotEmpty && _passwordController.text.isNotEmpty) {
      // Save login state
      await _authService.saveLoginState(
        token: 'fake_auth_token_123456',
        userId: 'user_123',
        username: _usernameController.text,
      );

      // Navigate to home page
      if (mounted) {
        Navigator.pushReplacement(
          context,
          MaterialPageRoute(builder: (context) => const HomeScreen()),
        );
      }
    } else {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text('Please enter username and password')),
        );
      }
    }

    setState(() {
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Login')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            TextField(
              controller: _usernameController,
              decoration: const InputDecoration(labelText: 'Username'),
            ),
            TextField(
              controller: _passwordController,
              decoration: const InputDecoration(labelText: 'Password'),
              obscureText: true,
            ),
            const SizedBox(height: 20),
            _isLoading
                ? const CircularProgressIndicator()
                : ElevatedButton(
                    onPressed: () => _login(context),
                    child: const Text('Login'),
                  ),
          ],
        ),
      ),
    );
  }
}

Home page implementation:

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  final _authService = AuthService();
  String? _username;

  @override
  void initState() {
    super.initState();
    _loadUserInfo();
  }

  Future<void> _loadUserInfo() async {
    final user = await _authService.getCurrentUser();
    setState(() {
      _username = user?['username'];
    });
  }

  Future<void> _logout(BuildContext context) async {
    await _authService.logout();
    if (mounted) {
      Navigator.pushReplacement(
        context,
        MaterialPageRoute(builder: (context) => const LoginScreen()),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout),
            onPressed: () => _logout(context),
          ),
        ],
      ),
      body: Center(
        child: _username != null
            ? Text('Welcome, $_username! You are logged in.')
            : const Text('Loading user info...'),
      ),
    );
  }
}

V. Example: Offline Data Caching

Using sqflite to implement local caching of network data for offline viewing functionality:

// News model class
class Article {
  final String id;
  final String title;
  final String? description;
  final String url;
  final String? urlToImage;
  final String publishedAt;
  final String? content;

  Article({
    required this.id,
    required this.title,
    this.description,
    required this.url,
    this.urlToImage,
    required this.publishedAt,
    this.content,
  });

  // Convert from Map
  factory Article.fromMap(Map<String, dynamic> map) {
    return Article(
      id: map['id'],
      title: map['title'],
      description: map['description'],
      url: map['url'],
      urlToImage: map['urlToImage'],
      publishedAt: map['publishedAt'],
      content: map['content'],
    );
  }

  // Convert to Map
  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'title': title,
      'description': description,
      'url': url,
      'urlToImage': urlToImage,
      'publishedAt': publishedAt,
      'content': content,
      'cachedAt': DateTime.now().toIso8601String(), // Cache time
    };
  }
}

// News database helper class
class NewsDatabaseHelper {
  static const _databaseName = "NewsDatabase.db";
  static const _databaseVersion = 1;
  static const table = 'articles';

  NewsDatabaseHelper._privateConstructor();
  static final NewsDatabaseHelper instance = NewsDatabaseHelper._privateConstructor();

  static Database? _database;
  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  _initDatabase() async {
    String path = join(await getDatabasesPath(), _databaseName);
    return await openDatabase(path,
        version: _databaseVersion,
        onCreate: _onCreate);
  }

  Future _onCreate(Database db, int version) async {
    await db.execute('''
          CREATE TABLE $table (
            id TEXT PRIMARY KEY,
            title TEXT NOT NULL,
            description TEXT,
            url TEXT NOT NULL,
            urlToImage TEXT,
            publishedAt TEXT NOT NULL,
            content TEXT,
            cachedAt TEXT NOT NULL
          )
          ''');
  }

  // Batch insert or update articles
  Future<void> batchInsertOrUpdateArticles(List<Article> articles) async {
    Database db = await instance.database;
    Batch batch = db.batch();

    for (var article in articles) {
      batch.insert(
        table,
        article.toMap(),
        conflictAlgorithm: ConflictAlgorithm.replace, // Replace if exists
      );
    }

    await batch.commit();
  }

  // Get all cached articles
  Future<List<Article>> getCachedArticles() async {
    Database db = await instance.database;
    List<Map<String, dynamic>> maps = await db.query(
      table,
      orderBy: 'publishedAt DESC',
    );
    return List.generate(maps.length, (i) => Article.fromMap(maps[i]));
  }

  // Get single article
  Future<Article?> getArticleById(String id) async {
    Database db = await instance.database;
    List<Map<String, dynamic>> maps = await db.query(
      table,
      where: 'id = ?',
      whereArgs: [id],
    );
    if (maps.isNotEmpty) {
      return Article.fromMap(maps.first);
    }
    return null;
  }

  // Clear expired cache (e.g., older than 7 days)
  Future<void> clearExpiredCache() async {
    Database db = await instance.database;
    final sevenDaysAgo = DateTime.now().subtract(const Duration(days: 7)).toIso8601String();
    await db.delete(
      table,
      where: 'cachedAt < ?',
      whereArgs: [sevenDaysAgo],
    );
  }

  // Clear all cache
  Future<void> clearAllCache() async {
    Database db = await instance.database;
    await db.delete(table);
  }
}

News repository class, integrating network requests and local caching:

class NewsRepository {
  final Dio _dio = Dio();
  final NewsDatabaseHelper _dbHelper = NewsDatabaseHelper.instance;
  final String _apiKey = 'your_news_api_key';

  // Get top headlines, prioritize network, use cache on failure
  Future<List<Article>> getTopHeadlines({bool forceRefresh = false}) async {
    try {
      // If not force refreshing, check cache first
      if (!forceRefresh) {
        final cachedArticles = await _dbHelper.getCachedArticles();
        if (cachedArticles.isNotEmpty) {
          return cachedArticles;
        }
      }

      // Network request
      Response response = await _dio.get(
        'https://newsapi.org/v2/top-headlines',
        queryParameters: {
          'country': 'us',
          'apiKey': _apiKey,
        },
      );

      // Parse data
      List<Article> articles = (response.data['articles'] as List)
          .map((item) => Article(
                id: item['url'], // Use url as unique identifier
                title: item['title'],
                description: item['description'],
                url: item['url'],
                urlToImage: item['urlToImage'],
                publishedAt: item['publishedAt'],
                content: item['content'],
              ))
          .toList();

      // Cache to local database
      await _dbHelper.batchInsertOrUpdateArticles(articles);

      // Clear expired cache
      await _dbHelper.clearExpiredCache();

      return articles;
    } catch (e) {
      // Network request failed, try to return cache
      final cachedArticles = await _dbHelper.getCachedArticles();
      if (cachedArticles.isNotEmpty) {
        return cachedArticles;
      }
      // No cache available, throw error
      throw Exception('Failed to fetch news and no cache available');
    }
  }
}

VI. Introduction to Other Storage Solutions

1. flutter_secure_storage

Used for storing sensitive information such as tokens and passwords, data is encrypted:

dependencies:
  flutter_secure_storage: ^9.2.4

Usage example:

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final storage = FlutterSecureStorage();

// Store sensitive data
await storage.write(key: 'auth_token', value: 'sensitive_token_123');

// Read data
String? token = await storage.read(key: 'auth_token');

// Delete data
await storage.delete(key: 'auth_token');

2. Hive

Hive is a high-performance, lightweight NoSQL database, pure Dart implementation, fast and easy to use:

dependencies:
  hive: ^2.2.3
  hive_flutter: ^1.1.0

Usage example:

// Initialization
await Hive.initFlutter();
Hive.registerAdapter(NoteAdapter()); // Register adapter
await Hive.openBox<Note>('notes');

// Get box
var box = Hive.box<Note>('notes');

// Add data
var note = Note(id: 1, title: 'Hive Demo', content: 'Hello Hive');
await box.put(note.id, note);

// Get data
Note? savedNote = box.get(1);

// Query all data
List<Note> allNotes = box.values.toList();

// Update data
note.title = 'Updated Title';
await box.put(note.id, note);

// Delete data
await box.delete(1);

VII. Local Storage Best Practices

Choose the right storage solution:
- Use shared_preferences for simple key-value data
- Use flutter_secure_storage for sensitive information
- Use sqflite or hive for structured data
Data layering management:
- Encapsulate storage operations, separate from business logic
- Use Repository Pattern to integrate network and local storage
Performance optimization:
- Batch database operations to reduce IO times
- Clean up expired cache in time to avoid excessive storage space
- Perform database operations on background threads to avoid blocking UI
Error handling:
- Add exception catching for all storage operations
- Provide a fallback strategy using cached data when network requests fail
Data migration:
- Plan database versions properly and prepare upgrade migration plans
- Consider data backup and recovery mechanisms for major updates
Security considerations:
- Sensitive data must be stored encrypted
- Avoid storing unnecessary user privacy data

Flutter Lesson 12: Network Requests and JSON Parsing

Ge Ji — Tue, 12 Aug 2025 02:52:47 +0000

In modern mobile application development, nearly all apps need to interact with backend servers to fetch remote data and display it to users. Flutter provides various ways to handle network requests and data parsing. This lesson will detail how to make network requests, process response data, and parse JSON-formatted data in Flutter.

I. HTTP Library Selection: dio Installation and Basic Usage

While Flutter officially provides the http package for network requests, the dio library is widely used in practical development due to its more powerful features and cleaner API. dio is a robust Dart HTTP client that supports interceptors, FormData, request cancellation, timeout settings, and other advanced features.

1. Installing dio

Add the dependency to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.9.0  # Use the latest version

Run flutter pub get to install the dependency.

2. Basic dio Usage

First, import the dio package:

import 'package:dio/dio.dart';

Create a dio instance:

// Create a default instance
Dio dio = Dio();

// Or configure an instance with BaseOptions
BaseOptions options = BaseOptions(
  baseUrl: 'https://api.example.com',
  connectTimeout: const Duration(milliseconds: 5000),
  receiveTimeout: const Duration(milliseconds: 3000),
  headers: {
    'Content-Type': 'application/json',
  },
);

Dio dio = Dio(options);

II. Making GET/POST Requests and Parameter Handling

1. Making GET Requests

GET requests are typically used to retrieve data from a server:

// Simple GET request
Future<void> fetchData() async {
  try {
    Response response = await dio.get('/users');
    print('Response data: ${response.data}');
    print('Status code: ${response.statusCode}');
  } catch (e) {
    print('Error: $e');
  }
}

// GET request with query parameters
Future<void> fetchUserData() async {
  try {
    // Method 1: Add parameters directly in the URL
    Response response1 = await dio.get('/users?userId=123&name=John');

    // Method 2: Use queryParameters
    Response response2 = await dio.get(
      '/users',
      queryParameters: {
        'userId': 123,
        'name': 'John',
      },
    );

    print('Response data: ${response2.data}');
  } catch (e) {
    print('Error: $e');
  }
}

2. Making POST Requests

POST requests are typically used to submit data to a server:

// Submit JSON data
Future<void> submitData() async {
  try {
    Response response = await dio.post(
      '/users',
      data: {
        'name': 'John Doe',
        'email': 'john@example.com',
        'age': 30,
      },
    );
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

// Submit FormData
Future<void> uploadForm() async {
  try {
    FormData formData = FormData.fromMap({
      'name': 'John Doe',
      'avatar': await MultipartFile.fromFile(
        '/path/to/avatar.jpg',
        filename: 'avatar.jpg',
      ),
      'hobbies': [
        'reading',
        'sports',
      ],
    });

    Response response = await dio.post(
      '/user/profile',
      data: formData,
    );
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

3. Custom Request Headers

You can set custom headers for individual requests:

Future<void> fetchWithHeaders() async {
  try {
    Response response = await dio.get(
      '/protected/data',
      options: Options(
        headers: {
          'Authorization': 'Bearer your_token_here',
          'Custom-Header': 'custom_value',
        },
      ),
    );
    print('Response data: ${response.data}');
  } catch (e) {
    print('Error: $e');
  }
}

4. Handling Request Timeouts

You can set timeout times for individual requests:

Future<void> fetchWithTimeout() async {
  try {
    Response response = await dio.get(
      '/slow/endpoint',
      options: Options(
        sendTimeout: const Duration(seconds: 2),
        receiveTimeout: const Duration(seconds: 5),
      ),
    );
    print('Response data: ${response.data}');
  } on DioException catch (e) {
    if (e.type == DioExceptionType.connectionTimeout) {
      print('Connection timeout');
    } else if (e.type == DioExceptionType.receiveTimeout) {
      print('Receive timeout');
    } else {
      print('Other error: $e');
    }
  }
}

III. JSON Data Parsing

Data returned from servers is usually in JSON format. Flutter provides several ways to parse JSON data.

1. Manual JSON Parsing

Dart has a built-in dart:convert library that can manually parse JSON data:

import 'dart:convert';

// Assume the server returns the following JSON data:
// {
//   "id": 1,
//   "name": "John Doe",
//   "email": "john@example.com",
//   "age": 30,
//   "hobbies": ["reading", "sports"]
// }

// Create a model class
class User {
  final int id;
  final String name;
  final String email;
  final int age;
  final List<String> hobbies;

  User({
    required this.id,
    required this.name,
    required this.email,
    required this.age,
    required this.hobbies,
  });

  // Create a User instance from a JSON map
  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
      age: json['age'],
      hobbies: List<String>.from(json['hobbies']),
    );
  }

  // Convert to a JSON map
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
      'age': age,
      'hobbies': hobbies,
    };
  }
}

// Parse JSON data
Future<void> parseUserJson() async {
  try {
    Response response = await dio.get('/users/1');

    // Convert JSON string to Map
    Map<String, dynamic> jsonData = response.data;

    // Convert to User object
    User user = User.fromJson(jsonData);

    print('User name: ${user.name}');
    print('User email: ${user.email}');
  } catch (e) {
    print('Error: $e');
  }
}

// Parse JSON array
Future<void> parseUsersJson() async {
  try {
    Response response = await dio.get('/users');

    // Convert JSON array to List
    List<dynamic> jsonList = response.data;

    // Convert to List of User objects
    List<User> users = jsonList.map((json) => User.fromJson(json)).toList();

    print('Number of users: ${users.length}');
    print('First user: ${users[0].name}');
  } catch (e) {
    print('Error: $e');
  }
}

Manual parsing is simple and straightforward without additional dependencies, but it becomes tedious and error-prone when dealing with complex JSON structures or many fields.

2. Using json_serializable for Automatic Code Generation

json_serializable is an automated source code generator that generates code for JSON serialization and deserialization, reducing the work of writing parsing code manually.

Install Dependencies

Add dependencies to pubspec.yaml:

dependencies:
  # ... other dependencies
  json_annotation: ^4.8.1  # Annotation package

dev_dependencies:
  # ... other dev dependencies
  build_runner: ^2.4.4     # Build tool
  json_serializable: ^6.7.1 # Code generator

Run flutter pub get to install dependencies.

Create Model Classes

import 'package:json_annotation/json_annotation.dart';

// Generated code will be in user.g.dart
part 'user.g.dart';

@JsonSerializable()
class User {
  final int id;
  final String name;

  // Use @JsonKey annotation when JSON field name differs from class property
  @JsonKey(name: 'email_address')
  final String email;

  final int age;

  // Ignore this field in serialization/deserialization
  @JsonKey(ignore: true)
  final String? token;

  final List<String> hobbies;

  User({
    required this.id,
    required this.name,
    required this.email,
    required this.age,
    this.token,
    required this.hobbies,
  });

  // Create a User instance from a JSON map
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);

  // Convert to a JSON map
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

Generate Code

Run the following command in the project root directory to generate serialization code:

flutter pub run build_runner build

For automatic code generation during development (when model classes change), use watch mode:

flutter pub run build_runner watch

After successful execution, a user.g.dart file will be generated containing automatically generated serialization and deserialization code.

Using Generated Code

Future<void> useGeneratedCode() async {
  try {
    Response response = await dio.get('/users/1');

    // Parse using the automatically generated fromJson method
    User user = User.fromJson(response.data);

    print('User name: ${user.name}');
    print('User email: ${user.email}');

    // Serialization example
    Map<String, dynamic> userJson = user.toJson();
    print('Serialized user: $userJson');
  } catch (e) {
    print('Error: $e');
  }
}

The advantage of json_serializable is that it reduces the work of writing parsing code manually, improving code reliability and maintainability, especially for complex JSON structures.

IV. Network State Handling

In practical applications, network requests typically have several states: loading, success, and error. We need to display different UIs based on these states.

1. Create Network State Management Class

enum NetworkStatus { initial, loading, success, error }

class NetworkResult<T> {
  final NetworkStatus status;
  final T? data;
  final String? errorMessage;

  NetworkResult.initial()
      : status = NetworkStatus.initial,
        data = null,
        errorMessage = null;

  NetworkResult.loading()
      : status = NetworkStatus.loading,
        data = null,
        errorMessage = null;

  NetworkResult.success(this.data)
      : status = NetworkStatus.success,
        errorMessage = null;

  NetworkResult.error(this.errorMessage)
      : status = NetworkStatus.error,
        data = null;
}

2. Display Different UIs Based on State

class DataScreen extends StatefulWidget {
  const DataScreen({super.key});

  @override
  State<DataScreen> createState() => _DataScreenState();
}

class _DataScreenState extends State<DataScreen> {
  final Dio _dio = Dio();
  NetworkResult<List<User>> _result = NetworkResult.initial();

  @override
  void initState() {
    super.initState();
    fetchUsers();
  }

  Future<void> fetchUsers() async {
    setState(() {
      _result = NetworkResult.loading();
    });

    try {
      Response response = await _dio.get('https://api.example.com/users');
      List<User> users = (response.data as List)
          .map((json) => User.fromJson(json))
          .toList();

      setState(() {
        _result = NetworkResult.success(users);
      });
    } catch (e) {
      setState(() {
        _result = NetworkResult.error(e.toString());
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('User List')),
      body: _buildBody(),
    );
  }

  Widget _buildBody() {
    switch (_result.status) {
      case NetworkStatus.initial:
        return const Center(child: Text('Tap to load data'));
      case NetworkStatus.loading:
        return const Center(child: CircularProgressIndicator());
      case NetworkStatus.success:
        return _buildUserList(_result.data!);
      case NetworkStatus.error:
        return Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text('Error: ${_result.errorMessage}'),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: fetchUsers,
                child: const Text('Retry'),
              ),
            ],
          ),
        );
    }
  }

  Widget _buildUserList(List<User> users) {
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (context, index) {
        User user = users[index];
        return ListTile(
          title: Text(user.name),
          subtitle: Text(user.email),
          trailing: Text('Age: ${user.age}'),
        );
      },
    );
  }
}

V. dio Interceptors

dio provides interceptor functionality that can handle requests before they're sent or responses after they're received, such as adding authentication tokens or handling errors.

1. Request Interceptor

// Add request interceptor
dio.interceptors.add(
  InterceptorsWrapper(
    onRequest: (options, handler) {
      // Do something before request is sent
      print('Request: ${options.method} ${options.uri}');

      // Add authentication token
      options.headers['Authorization'] = 'Bearer your_token_here';

      // Continue with the request
      return handler.next(options);

      // If you want to cancel the request, call handler.reject()
      // return handler.reject(DioException(requestOptions: options, type: DioExceptionType.cancel));
    },
  ),
);

2. Response Interceptor

// Add response interceptor
dio.interceptors.add(
  InterceptorsWrapper(
    onResponse: (response, handler) {
      // Do something with response data
      print('Response: ${response.statusCode} ${response.data}');

      // Continue with the response
      return handler.next(response);
    },
  ),
);

3. Error Interceptor

// Add error interceptor
dio.interceptors.add(
  InterceptorsWrapper(
    onError: (DioException e, handler) {
      // Handle error
      print('Error: ${e.message}');

      // Unified handling of 401 unauthorized errors
      if (e.response?.statusCode == 401) {
        // You can navigate to login page here
        print('Unauthorized, redirecting to login');
      }

      // Continue with the error
      return handler.next(e);

      // If you want to mask the error, return a successful response
      // return handler.resolve(Response(requestOptions: e.requestOptions, data: {}));
    },
  ),
);

4. Log Interceptor

dio provides a built-in log interceptor for debugging:

import 'package:dio/io.dart';

dio.interceptors.add(LogInterceptor(
  request: true,  // Print request information
  requestHeader: true,  // Print request headers
  requestBody: true,  // Print request body
  responseHeader: true,  // Print response headers
  responseBody: true,  // Print response body
  error: true,  // Print error information
  logPrint: (object) {
    print('Dio Log: $object');
  },
));

VI. Example: Fetch and Display News List with Open API

We'll implement a complete example that fetches and displays a news list using a public news API.

1. Create News Model Classes

import 'package:json_annotation/json_annotation.dart';

part 'news.g.dart';

@JsonSerializable()
class NewsArticle {
  @JsonKey(name: 'source')
  final NewsSource source;

  @JsonKey(name: 'author')
  final String? author;

  @JsonKey(name: 'title')
  final String title;

  @JsonKey(name: 'description')
  final String? description;

  @JsonKey(name: 'url')
  final String url;

  @JsonKey(name: 'urlToImage')
  final String? urlToImage;

  @JsonKey(name: 'publishedAt')
  final String publishedAt;

  @JsonKey(name: 'content')
  final String? content;

  NewsArticle({
    required this.source,
    this.author,
    required this.title,
    this.description,
    required this.url,
    this.urlToImage,
    required this.publishedAt,
    this.content,
  });

  factory NewsArticle.fromJson(Map<String, dynamic> json) =>
      _$NewsArticleFromJson(json);

  Map<String, dynamic> toJson() => _$NewsArticleToJson(this);
}

@JsonSerializable()
class NewsSource {
  @JsonKey(name: 'id')
  final String? id;

  @JsonKey(name: 'name')
  final String name;

  NewsSource({
    this.id,
    required this.name,
  });

  factory NewsSource.fromJson(Map<String, dynamic> json) =>
      _$NewsSourceFromJson(json);

  Map<String, dynamic> toJson() => _$NewsSourceToJson(this);
}

@JsonSerializable()
class NewsResponse {
  @JsonKey(name: 'status')
  final String status;

  @JsonKey(name: 'totalResults')
  final int totalResults;

  @JsonKey(name: 'articles')
  final List<NewsArticle> articles;

  NewsResponse({
    required this.status,
    required this.totalResults,
    required this.articles,
  });

  factory NewsResponse.fromJson(Map<String, dynamic> json) =>
      _$NewsResponseFromJson(json);

  Map<String, dynamic> toJson() => _$NewsResponseToJson(this);
}

Run the code generation command:

flutter pub run build_runner build

2. Create News Service Class

import 'package:dio/dio.dart';

class NewsService {
  final Dio _dio = Dio();
  final String _apiKey = 'your_news_api_key'; // Replace with your API Key
  final String _baseUrl = 'https://newsapi.org/v2';

  NewsService() {
    // Configure dio
    _dio.options.baseUrl = _baseUrl;
    _dio.options.connectTimeout = const Duration(seconds: 5);
    _dio.options.receiveTimeout = const Duration(seconds: 3);

    // Add log interceptor
    _dio.interceptors.add(LogInterceptor(responseBody: true));
  }

  // Get top headlines
  Future<NewsResponse> getTopHeadlines({String country = 'us'}) async {
    try {
      Response response = await _dio.get(
        '/top-headlines',
        queryParameters: {
          'country': country,
          'apiKey': _apiKey,
        },
      );
      return NewsResponse.fromJson(response.data);
    } on DioException catch (e) {
      print('News API error: ${e.message}');
      throw Exception('Failed to fetch news: ${e.message}');
    }
  }

  // Search news
  Future<NewsResponse> searchNews(String query) async {
    try {
      Response response = await _dio.get(
        '/everything',
        queryParameters: {
          'q': query,
          'apiKey': _apiKey,
        },
      );
      return NewsResponse.fromJson(response.data);
    } on DioException catch (e) {
      print('News API error: ${e.message}');
      throw Exception('Failed to search news: ${e.message}');
    }
  }
}

Note: You need to register at News API to get an API Key.

3. Implement News List Page

class NewsListScreen extends StatefulWidget {
  const NewsListScreen({super.key});

  @override
  State<NewsListScreen> createState() => _NewsListScreenState();
}

class _NewsListScreenState extends State<NewsListScreen> {
  final NewsService _newsService = NewsService();
  NetworkResult<List<NewsArticle>> _newsResult = NetworkResult.initial();
  final TextEditingController _searchController = TextEditingController();

  @override
  void initState() {
    super.initState();
    _fetchTopHeadlines();
  }

  Future<void> _fetchTopHeadlines() async {
    setState(() {
      _newsResult = NetworkResult.loading();
    });

    try {
      NewsResponse response = await _newsService.getTopHeadlines();
      setState(() {
        _newsResult = NetworkResult.success(response.articles);
      });
    } catch (e) {
      setState(() {
        _newsResult = NetworkResult.error(e.toString());
      });
    }
  }

  Future<void> _searchNews() async {
    String query = _searchController.text.trim();
    if (query.isEmpty) return;

    setState(() {
      _newsResult = NetworkResult.loading();
    });

    try {
      NewsResponse response = await _newsService.searchNews(query);
      setState(() {
        _newsResult = NetworkResult.success(response.articles);
      });
    } catch (e) {
      setState(() {
        _newsResult = NetworkResult.error(e.toString());
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Latest News'),
      ),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: TextField(
              controller: _searchController,
              decoration: InputDecoration(
                hintText: 'Search news...',
                suffixIcon: IconButton(
                  icon: const Icon(Icons.search),
                  onPressed: _searchNews,
                ),
                border: const OutlineInputBorder(),
              ),
              onSubmitted: (value) => _searchNews(),
            ),
          ),
          Expanded(
            child: _buildNewsContent(),
          ),
        ],
      ),
    );
  }

  Widget _buildNewsContent() {
    switch (_newsResult.status) {
      case NetworkStatus.initial:
        return const Center(child: Text('Loading news...'));
      case NetworkStatus.loading:
        return const Center(child: CircularProgressIndicator());
      case NetworkStatus.success:
        return _buildNewsList(_newsResult.data!);
      case NetworkStatus.error:
        return Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text('Error: ${_newsResult.errorMessage}'),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: _fetchTopHeadlines,
                child: const Text('Retry'),
              ),
            ],
          ),
        );
    }
  }

  Widget _buildNewsList(List<NewsArticle> articles) {
    if (articles.isEmpty) {
      return const Center(child: Text('No news found'));
    }

    return ListView.builder(
      itemCount: articles.length,
      itemBuilder: (context, index) {
        NewsArticle article = articles[index];
        return Card(
          margin: const EdgeInsets.symmetric(horizontal: 10, vertical: 6),
          child: Column(
            children: [
              if (article.urlToImage != null)
                Image.network(
                  article.urlToImage!,
                  height: 180,
                  width: double.infinity,
                  fit: BoxFit.cover,
                  errorBuilder: (context, error, stackTrace) {
                    return Container(
                      height: 180,
                      color: Colors.grey[200],
                      child: const Center(child: Icon(Icons.image_not_supported)),
                    );
                  },
                ),
              Padding(
                padding: const EdgeInsets.all(12.0),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
                      article.source.name,
                      style: TextStyle(
                        color: Colors.grey[600],
                        fontSize: 12,
                      ),
                    ),
                    const SizedBox(height: 8),
                    Text(
                      article.title,
                      style: const TextStyle(
                        fontSize: 16,
                        fontWeight: FontWeight.bold,
                      ),
                    ),
                    const SizedBox(height: 8),
                    if (article.description != null)
                      Text(
                        article.description!,
                        style: const TextStyle(fontSize: 14),
                        maxLines: 3,
                        overflow: TextOverflow.ellipsis,
                      ),
                    const SizedBox(height: 8),
                    Text(
                      _formatDate(article.publishedAt),
                      style: TextStyle(
                        color: Colors.grey[600],
                        fontSize: 12,
                      ),
                    ),
                  ],
                ),
              ),
            ],
          ),
        );
      },
    );
  }

  String _formatDate(String dateString) {
    DateTime date = DateTime.parse(dateString);
    return DateFormat.yMMMd().add_jm().format(date);
  }
}

Note: You need to add the intl dependency for date formatting. Add intl: ^0.18.1 to pubspec.yaml and run flutter pub get.

4. Configure Network Permissions

For Android, add network permissions in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

For iOS, add in ios/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

VII. Network Request Best Practices

Encapsulate network layer: Encapsulate network request logic in dedicated service classes, separating it from the UI layer to improve code reusability and maintainability.
Unified error handling: Use interceptors to handle network errors uniformly, such as timeouts, no network, and authentication failures.
Manage request states properly: Clearly display loading, success, error, and other states to provide a good user experience.
Data caching: Implement local caching for infrequently changing data to reduce network requests and improve app performance.
Request cancellation: Cancel unfinished network requests when a page is destroyed to avoid memory leaks and unnecessary resource consumption.
Image handling: Use libraries like cached_network_image to handle network images, implementing caching and placeholder functionality.
Avoid complex tasks on UI thread: Ensure network requests execute on asynchronous threads to avoid blocking the UI.
Add logging: Add detailed network logs in the development environment for debugging; disable or simplify logs in the production environment.

Flutter Lesson 11: Advanced State Management: Provider

Ge Ji — Mon, 11 Aug 2025 10:29:56 +0000

In Flutter app development, as applications grow in size, state sharing and communication between widgets become increasingly complex. When multiple widgets need to access and modify the same state, the traditional approach of passing parameters through constructors leads to redundant code, high coupling, and poor maintainability. This lesson introduces Provider, a popular state management solution in Flutter that builds on InheritedWidget to elegantly solve cross-widget state sharing problems simply and efficiently.

I. Why We Need State Management

In Flutter, all UI is composed of Widgets, which are immutable, while state represents the mutable data within Widgets. For simple applications, we can manage a single widget's state with setState(), but when state needs to be shared across multiple widgets, we face several challenges:

Difficult cross-widget communication: Deeply nested child widgets needing access to parent state must receive parameters through multiple levels, creating a "prop drilling" problem.
Complex state synchronization: Manually synchronizing state when multiple widgets depend on the same state leads to messy code logic.
Poor code maintainability: State scattered across various widgets makes modifications and debugging difficult.
Performance issues: Inefficient state management causes unnecessary widget rebuilds, affecting app performance.

For example, shopping cart state in an e-commerce app might need access and modification in product lists, cart pages, checkout pages, and more. With traditional methods, cart data would need to be passed between pages, and all related pages manually notified of changes—an inefficient and error-prone approach.

State management solutions address these issues, with Provider being one of the simplest, most user-friendly, and officially recommended options.

II. Provider Basic Concepts and Core Classes

Provider is a state management library built on Flutter's native InheritedWidget. Its core idea involves extracting shared state into an independent class, providing this state in the widget tree through a Provider widget, and finally consuming this state in child widgets that need it.

1. Core Classes

ChangeNotifier: A class implementing the observer pattern that notifies all listeners of updates by calling notifyListeners() when state changes.
ChangeNotifierProvider: A widget that provides a ChangeNotifier instance in the widget tree, making it accessible to widgets in its subtree.
Consumer: Used to retrieve and listen to a ChangeNotifier instance in child widgets, rebuilding itself when state changes.
Provider.of: Another method to retrieve ChangeNotifier instances, with an option to listen for state changes.

2. Installing Provider

Before using Provider, add the dependency to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  provider: ^6.1.5  # Use the latest version

Run flutter pub get to install the dependency.

III. Basic Provider Workflow

Using Provider for state management typically follows these steps:

Create a state class inheriting from ChangeNotifier, encapsulating shared state and methods to modify it.
Use ChangeNotifierProvider to provide the state instance at an appropriate location in the widget tree.
Retrieve and use the state in child widgets using Consumer or Provider.of.

Let's demonstrate basic usage with a simple counter example:

1. Create the State Class

import 'package:flutter/foundation.dart';

// Inherit from ChangeNotifier
class Counter with ChangeNotifier {
  int _count = 0;

  // Provide method to access state
  int get count => _count;

  // Provide methods to modify state
  void increment() {
    _count++;
    // Notify all listeners
    notifyListeners();
  }

  void decrement() {
    _count--;
    notifyListeners();
  }

  void reset() {
    _count = 0;
    notifyListeners();
  }
}

2. Provide the State

Use ChangeNotifierProvider to provide the state in the widget tree, typically at the app's root:

import 'package:provider/provider.dart';

void main() {
  runApp(
    // Provide Counter instance
    ChangeNotifierProvider(
      create: (context) => Counter(),
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Provider Demo',
      home: const CounterPage(),
    );
  }
}

3. Consume the State

Retrieve and use the state in child widgets with Consumer or Provider.of:

Using Consumer

class CounterPage extends StatelessWidget {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter Demo')),
      body: Center(
        // Use Consumer to get Counter instance
        child: Consumer<Counter>(
          builder: (context, counter, child) {
            // Builder method rebuilds when state changes
            return Text(
              'Current count: ${counter.count}',
              style: const TextStyle(fontSize: 24),
            );
          },
        ),
      ),
      floatingActionButton: Row(
        mainAxisAlignment: MainAxisAlignment.end,
        children: [
          FloatingActionButton(
            onPressed: () {
              // Use Provider.of to get instance (without listening)
              Provider.of<Counter>(context, listen: false).decrement();
            },
            child: const Icon(Icons.remove),
          ),
          const SizedBox(width: 10),
          FloatingActionButton(
            onPressed: () {
              Provider.of<Counter>(context, listen: false).increment();
            },
            child: const Icon(Icons.add),
          ),
        ],
      ),
    );
  }
}

Consumer Performance Optimization

The child parameter in Consumer optimizes performance by avoiding unnecessary rebuilds:

Consumer<Counter>(
  builder: (context, counter, child) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        // This Text rebuilds when state changes
        Text('Count: ${counter.count}'),
        // This child doesn't rebuild as it's extracted to the child parameter
        child!,
      ],
    );
  },
  // This child builds only once
  child: const Text('This is static text'),
)

Using Provider.of

Provider.of(context) retrieves the nearest Provider of type T and rebuilds the current widget when state changes:

// Listen for state changes, rebuilds when state changes
final counter = Provider.of<Counter>(context);

// Don't listen for state changes, typically for state modification
final counter = Provider.of<Counter>(context, listen: false);

Example usage:

class CounterDisplay extends StatelessWidget {
  const CounterDisplay({super.key});

  @override
  Widget build(BuildContext context) {
    // Get Counter instance and listen for changes
    final counter = Provider.of<Counter>(context);

    return Text(
      'Count: ${counter.count}',
      style: const TextStyle(fontSize: 24),
    );
  }
}

class CounterActions extends StatelessWidget {
  const CounterActions({super.key});

  @override
  Widget build(BuildContext context) {
    return FloatingActionButton(
      onPressed: () {
        // Get Counter instance without listening
        Provider.of<Counter>(context, listen: false).increment();
      },
      child: const Icon(Icons.add),
    );
  }
}

IV. Managing Multiple States

When an application has multiple independent states to manage, use MultiProvider to organize them:

void main() {
  runApp(
    MultiProvider(
      providers: [
        ChangeNotifierProvider(create: (context) => Counter()),
        ChangeNotifierProvider(create: (context) => ThemeProvider()),
        ChangeNotifierProvider(create: (context) => UserProvider()),
      ],
      child: const MyApp(),
    ),
  );
}

Then retrieve different states in child widgets:

// Get counter state
final counter = Provider.of<Counter>(context);

// Get theme state
final themeProvider = Provider.of<ThemeProvider>(context);

V. Example: Managing Shopping Cart State with Provider

Let's implement a complete shopping cart example to demonstrate managing complex state with Provider:

1. Define Data Models

// Product model
class Product {
  final String id;
  final String name;
  final double price;
  final String imageUrl;

  Product({
    required this.id,
    required this.name,
    required this.price,
    required this.imageUrl,
  });
}

// Cart item model
class CartItem {
  final String id;
  final String productId;
  final String name;
  final int quantity;
  final double price;

  CartItem({
    required this.id,
    required this.productId,
    required this.name,
    required this.quantity,
    required this.price,
  });

  // Calculate subtotal
  double get totalPrice => price * quantity;
}

2. Create Shopping Cart State Management Class

import 'package:flutter/foundation.dart';
import 'dart:collection';

class Cart with ChangeNotifier {
  // Store cart items with product IDs as keys
  final Map<String, CartItem> _items = {};

  // Provide unmodifiable view of cart items
  UnmodifiableMapView<String, CartItem> get items => UnmodifiableMapView(_items);

  // Get total number of items in cart
  int get itemCount => _items.length;

  // Calculate total cart amount
  double get totalAmount {
    var total = 0.0;
    _items.forEach((key, cartItem) {
      total += cartItem.price * cartItem.quantity;
    });
    return total;
  }

  // Add product to cart
  void addItem(Product product) {
    if (_items.containsKey(product.id)) {
      // If product exists, increase quantity
      _items.update(
        product.id,
        (existingItem) => CartItem(
          id: existingItem.id,
          productId: existingItem.productId,
          name: existingItem.name,
          quantity: existingItem.quantity + 1,
          price: existingItem.price,
        ),
      );
    } else {
      // If new product, add to cart
      _items.putIfAbsent(
        product.id,
        () => CartItem(
          id: DateTime.now().toString(),
          productId: product.id,
          name: product.name,
          quantity: 1,
          price: product.price,
        ),
      );
    }
    notifyListeners();
  }

  // Remove product from cart
  void removeItem(String productId) {
    _items.remove(productId);
    notifyListeners();
  }

  // Decrease product quantity in cart
  void removeSingleItem(String productId) {
    if (!_items.containsKey(productId)) {
      return;
    }

    if (_items[productId]!.quantity > 1) {
      _items.update(
        productId,
        (existingItem) => CartItem(
          id: existingItem.id,
          productId: existingItem.productId,
          name: existingItem.name,
          quantity: existingItem.quantity - 1,
          price: existingItem.price,
        ),
      );
    } else {
      _items.remove(productId);
    }
    notifyListeners();
  }

  // Clear cart
  void clear() {
    _items.clear();
    notifyListeners();
  }
}

3. Create Product List State Class

class Products with ChangeNotifier {
  final List<Product> _items = [
    Product(
      id: 'p1',
      name: 'Red Shirt',
      price: 29.99,
      imageUrl: 'https://picsum.photos/200/300?random=1',
    ),
    Product(
      id: 'p2',
      name: 'Trousers',
      price: 59.99,
      imageUrl: 'https://picsum.photos/200/300?random=2',
    ),
    Product(
      id: 'p3',
      name: 'Yellow Scarf',
      price: 19.99,
      imageUrl: 'https://picsum.photos/200/300?random=3',
    ),
    Product(
      id: 'p4',
      name: 'A Shoes',
      price: 99.99,
      imageUrl: 'https://picsum.photos/200/300?random=4',
    ),
  ];

  // Get product list
  List<Product> get items => [..._items];
}

4. Provide States in Application

void main() {
  runApp(
    MultiProvider(
      providers: [
        ChangeNotifierProvider(create: (ctx) => Products()),
        ChangeNotifierProvider(create: (ctx) => Cart()),
      ],
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Shopping Cart Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        visualDensity: VisualDensity.adaptivePlatformDensity,
      ),
      home: const ProductsOverviewScreen(),
      routes: {
        CartScreen.routeName: (ctx) => const CartScreen(),
      },
    );
  }
}

5. Implement Product List Page

class ProductsOverviewScreen extends StatelessWidget {
  const ProductsOverviewScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // Get product list
    final productsData = Provider.of<Products>(context);
    final products = productsData.items;

    return Scaffold(
      appBar: AppBar(
        title: const Text('My Shop'),
        actions: [
          // Cart icon with item count badge
          Consumer<Cart>(
            builder: (ctx, cart, ch) => Badge(
              label: Text(cart.itemCount.toString()),
              child: ch!,
            ),
            child: IconButton(
              icon: const Icon(Icons.shopping_cart),
              onPressed: () {
                Navigator.of(context).pushNamed(CartScreen.routeName);
              },
            ),
          ),
        ],
      ),
      body: GridView.builder(
        padding: const EdgeInsets.all(10.0),
        itemCount: products.length,
        gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
          crossAxisCount: 2,
          childAspectRatio: 3 / 2,
          crossAxisSpacing: 10,
          mainAxisSpacing: 10,
        ),
        itemBuilder: (ctx, i) => ProductItem(products[i]),
      ),
    );
  }
}

class ProductItem extends StatelessWidget {
  final Product product;

  const ProductItem(this.product, {super.key});

  @override
  Widget build(BuildContext context) {
    return ClipRRect(
      borderRadius: BorderRadius.circular(10),
      child: GridTile(
        footer: GridTileBar(
          backgroundColor: Colors.black87,
          title: Text(
            product.name,
            textAlign: TextAlign.center,
          ),
          trailing: IconButton(
            icon: const Icon(Icons.shopping_cart),
            onPressed: () {
              // Add product to cart
              Provider.of<Cart>(context, listen: false).addItem(product);
              // Show success message
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(
                  content: const Text('Added item to cart!'),
                  duration: const Duration(seconds: 2),
                  action: SnackBarAction(
                    label: 'UNDO',
                    onPressed: () {
                      Provider.of<Cart>(context, listen: false)
                          .removeSingleItem(product.id);
                    },
                  ),
                ),
              );
            },
            color: Theme.of(context).colorScheme.secondary,
          ),
        ),
        child: Image.network(
          product.imageUrl,
          fit: BoxFit.cover,
        ),
      ),
    );
  }
}

6. Implement Cart Page

class CartScreen extends StatelessWidget {
  static const routeName = '/cart';

  const CartScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final cart = Provider.of<Cart>(context);

    return Scaffold(
      appBar: AppBar(
        title: const Text('Your Cart'),
      ),
      body: Column(
        children: [
          Card(
            margin: const EdgeInsets.all(15),
            child: Padding(
              padding: const EdgeInsets.all(8),
              child: Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  const Text('Total', style: TextStyle(fontSize: 20)),
                  const Spacer(),
                  Chip(
                    label: Text(
                      '\$${cart.totalAmount.toStringAsFixed(2)}',
                      style: TextStyle(
                        color: Theme.of(context).primaryTextTheme. titleLarge?.color,
                      ),
                    ),
                    backgroundColor: Theme.of(context).primaryColor,
                  ),
                  TextButton(
                    onPressed: () {
                      // Add checkout logic here
                    },
                    child: const Text('ORDER NOW'),
                  )
                ],
              ),
            ),
          ),
          const SizedBox(height: 10),
          Expanded(
            child: ListView.builder(
              itemCount: cart.items.length,
              itemBuilder: (ctx, i) {
                final cartItem = cart.items.values.toList()[i];
                return ListTile(
                  leading: CircleAvatar(
                    child: FittedBox(
                      child: Text('\$${cartItem.price}'),
                    ),
                  ),
                  title: Text(cartItem.name),
                  subtitle: Text('Total: \$${(cartItem.price * cartItem.quantity).toStringAsFixed(2)}'),
                  trailing: Row(
                    mainAxisSize: MainAxisSize.min,
                    children: [
                      IconButton(
                        icon: const Icon(Icons.remove),
                        onPressed: () {
                          cart.removeSingleItem(cartItem.productId);
                        },
                      ),
                      Text('${cartItem.quantity}'),
                      IconButton(
                        icon: const Icon(Icons.add),
                        onPressed: () {
                          // Add logic to increase quantity here
                          // Not implemented in this simplified example
                        },
                      ),
                    ],
                  ),
                );
              },
            ),
          )
        ],
      ),
    );
  }
}

VI. Advanced Provider Usage

1. Selector for Optimized Rebuilds

Selector is an advanced version of Consumer that determines whether to rebuild based on specified conditions, further optimizing performance:

Selector<Counter, int>(
  // Select the state to listen to
  selector: (context, counter) => counter.count,
  // Only rebuild when selected state changes
  builder: (context, count, child) {
    return Text('Count: $count');
  },
)

Selector takes two generic parameters: the first is the ChangeNotifier type, and the second is the type of state to monitor. The builder is only called when the value returned by the selector method changes.

2. State Persistence

Combining with local storage libraries like shared_preferences or hive enables state persistence:

class Counter with ChangeNotifier {
  int _count = 0;
  final SharedPreferences _prefs;

  Counter(this._prefs) {
    // Load state from local storage
    _count = _prefs.getInt('count') ?? 0;
  }

  int get count => _count;

  void increment() {
    _count++;
    // Save state to local storage
    _prefs.setInt('count', _count);
    notifyListeners();
  }
}

// Provide state with persistence
ChangeNotifierProvider(
  create: (context) => Counter(SharedPreferences.getInstance()),
  child: MyApp(),
)

3. State Encapsulation and Business Logic Separation

For complex applications, separate business logic from state management to keep ChangeNotifier clean:

// Business logic layer
class CartService {
  Future<void> addToCart(Product product) async {
    // Handle business logic for adding to cart, such as network requests
    await Future.delayed(const Duration(milliseconds: 300));
  }
}

// State management layer
class Cart with ChangeNotifier {
  final CartService _cartService;
  final List<CartItem> _items = [];

  Cart(this._cartService);

  List<CartItem> get items => [..._items];

  Future<void> addItem(Product product) async {
    try {
      // Call business logic
      await _cartService.addToCart(product);
      // Update state
      _items.add(CartItem(...));
      notifyListeners();
    } catch (e) {
      // Handle errors
      rethrow;
    }
  }
}

VII. Provider Best Practices

Appropriate state granularity: Avoid creating overly large state classes; split state by functional modules.
Minimal rebuild principle: Use Consumer and Selector to limit rebuild scope and avoid unnecessary rebuilds.
Single responsibility: Each state class should manage only a related set of states, following the single responsibility principle.
Immutable data: For complex data structures in state classes, use immutable objects and update state by replacing entire objects.
Avoid state creation in build methods: Ensure ChangeNotifier instances are created in the create method, not in build methods.
Clean up resources: If your state class uses resources that need manual release (like timers), clean them up in the dispose method:

class TimerModel with ChangeNotifier {
  late Timer _timer;
  int _seconds = 0;

  TimerModel() {
    _timer = Timer.periodic(const Duration(seconds: 1), (timer) {
      _seconds++;
      notifyListeners();
    });
  }

  int get seconds => _seconds;

  @override
  void dispose() {
    // Clean up resources
    _timer.cancel();
    super.dispose();
  }
}

Flutter Lesson 10: Forms and Inputs

Ge Ji — Mon, 11 Aug 2025 08:15:34 +0000

In mobile application development, forms are essential for collecting user input. Whether it's for login/registration, personal information entry, or data submission, form components are indispensable. Flutter provides a comprehensive form handling mechanism, including form widgets, input validation, and data processing capabilities. This lesson will detailedly introduce form and input-related components in Flutter, helping you build fully functional and user-friendly form interfaces.

I. Basic Form Components

Flutter provides the Form widget as a container for forms, which works with various input controls (such as TextFormField) to implement complete form functionality. The Form widget itself doesn't render any visible content; it's primarily used for managing the state, validation, and submission of form fields.

1. Form Widget and GlobalKey

The Form widget needs a GlobalKey to manage form state, enabling form validation and data submission. A GlobalKey is a way to access state across widgets, uniquely identifying a widget and retrieving its state.

Basic usage example:

class BasicFormExample extends StatefulWidget {
  const BasicFormExample({super.key});

  @override
  State<BasicFormExample> createState() => _BasicFormExampleState();
}

class _BasicFormExampleState extends State<BasicFormExample> {
  // Create a global key for the form
  final _formKey = GlobalKey<FormState>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Basic Form')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        // Form widget
        child: Form(
          key: _formKey, // Associate with the global key
          autovalidateMode: AutovalidateMode.onUserInteraction, // Validation mode
          child: Column(
            children: [
              // Form field
              TextFormField(
                decoration: const InputDecoration(
                  labelText: 'Username',
                  border: OutlineInputBorder(),
                ),
                // Validator
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please enter your username';
                  }
                  return null; // Validation passed
                },
              ),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: () {
                  // Validate the form
                  if (_formKey.currentState!.validate()) {
                    // Validation passed, process data
                    ScaffoldMessenger.of(context).showSnackBar(
                      const SnackBar(content: Text('Processing data')),
                    );
                  }
                },
                child: const Text('Submit'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Core parameters of the Form widget:

key: A GlobalKey used to access the form state
autovalidateMode: Automatic validation mode, determining when to validate input automatically
- AutovalidateMode.disabled: Disable automatic validation (default)
- AutovalidateMode.always: Always validate automatically
- AutovalidateMode.onUserInteraction: Validate on user interaction (e.g., input, focus change)

2. TextFormField Widget

TextFormField is the most commonly used input widget in forms. It inherits from TextField and adds form validation capabilities. It supports various input types (text, numbers, email, etc.) and can be customized in appearance and behavior.

Example of common properties:

TextFormField(
  // Input box decoration
  decoration: InputDecoration(
    labelText: 'Email',
    hintText: 'Enter your email address',
    prefixIcon: const Icon(Icons.email),
    border: const OutlineInputBorder(),
    // Error提示样式
    errorBorder: OutlineInputBorder(
      borderSide: const BorderSide(color: Colors.red),
      borderRadius: BorderRadius.circular(4),
    ),
  ),
  // Input type
  keyboardType: TextInputType.emailAddress,
  // Input formatters (can restrict input content)
  inputFormatters: [
    FilteringTextInputFormatter.deny(RegExp(r'\s')), // Deny spaces
  ],
  // Text capitalization
  textCapitalization: TextCapitalization.none,
  // Password obfuscation
  obscureText: false, // Set to true for password fields
  // Autocorrect
  autocorrect: false,
  // Autofocus
  autofocus: false,
  // Maximum length
  maxLength: 50,
  // Maximum lines
  maxLines: 1,
  // Validator
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Please enter your email';
    }
    // Simple email format validation
    if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(value)) {
      return 'Please enter a valid email';
    }
    return null;
  },
  // Input change callback
  onChanged: (value) {
    print('Email changed: $value');
  },
  // Input completion callback
  onFieldSubmitted: (value) {
    print('Email submitted: $value');
  },
)

3. Other Input Widgets

In addition to text input, Flutter provides other commonly used form input widgets:

Checkbox: For selecting multiple options
Radio: For selecting one option from multiple choices
Switch: For turning a feature on/off
DropdownButton: For selecting from preset options

These widgets can be wrapped with FormField to integrate into forms:

// Checkbox form field
FormField<bool>(
  initialValue: false,
  validator: (value) {
    if (value == false) {
      return 'Please agree to the terms';
    }
    return null;
  },
  builder: (formFieldState) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Row(
          children: [
            Checkbox(
              value: formFieldState.value,
              onChanged: (value) {
                formFieldState.didChange(value);
              },
            ),
            const Text('I agree to the terms and conditions'),
          ],
        ),
        if (formFieldState.hasError)
          Padding(
            padding: const EdgeInsets.only(top: 4, left: 4),
            child: Text(
              formFieldState.errorText!,
              style: const TextStyle(
                color: Colors.red,
                fontSize: 12,
              ),
            ),
          ),
      ],
    );
  },
)

// Dropdown selection box
FormField<String>(
  initialValue: 'male',
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Please select gender';
    }
    return null;
  },
  builder: (formFieldState) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        DropdownButton<String>(
          value: formFieldState.value,
          isExpanded: true,
          items: const [
            DropdownMenuItem(value: 'male', child: Text('Male')),
            DropdownMenuItem(value: 'female', child: Text('Female')),
            DropdownMenuItem(value: 'other', child: Text('Other')),
          ],
          onChanged: (value) {
            formFieldState.didChange(value);
          },
        ),
        if (formFieldState.hasError)
          Padding(
            padding: const EdgeInsets.only(top: 4, left: 4),
            child: Text(
              formFieldState.errorText!,
              style: const TextStyle(
                color: Colors.red,
                fontSize: 12,
              ),
            ),
          ),
      ],
    );
  },
)

II. Input Validation and Form Submission

Form validation is crucial for ensuring user input meets requirements. Flutter provides a flexible validation mechanism that can implement various validation logic from simple to complex.

1. Basic Validation Logic

Each TextFormField can specify a validation function through the validator property. This function receives the input value and returns an error message (validation failed) or null (validation succeeded).

Examples of common validations:

// Username validation
validator: (value) {
  if (value == null || value.isEmpty) {
    return 'Please enter username';
  }
  if (value.length < 3) {
    return 'Username must be at least 3 characters';
  }
  if (value.length > 20) {
    return 'Username cannot exceed 20 characters';
  }
  return null;
}

// Password validation
validator: (value) {
  if (value == null || value.isEmpty) {
    return 'Please enter password';
  }
  if (value.length < 6) {
    return 'Password must be at least 6 characters';
  }
  if (!RegExp(r'[A-Z]').hasMatch(value)) {
    return 'Password must contain at least one uppercase letter';
  }
  return null;
}

// Confirm password validation (needs comparison with password field)
validator: (value) {
  if (value == null || value.isEmpty) {
    return 'Please confirm password';
  }
  if (value != _passwordController.text) {
    return 'Passwords do not match';
  }
  return null;
}

2. Form Submission and Data Processing

Form validation and data retrieval can be triggered through GlobalKey:

class FormSubmissionExample extends StatefulWidget {
  const FormSubmissionExample({super.key});

  @override
  State<FormSubmissionExample> createState() => _FormSubmissionExampleState();
}

class _FormSubmissionExampleState extends State<FormSubmissionExample> {
  final _formKey = GlobalKey<FormState>();
  final _usernameController = TextEditingController();
  final _emailController = TextEditingController();

  @override
  void dispose() {
    // Release controller resources
    _usernameController.dispose();
    _emailController.dispose();
    super.dispose();
  }

  // Submit the form
  void _submitForm() {
    // Validate all fields
    if (_formKey.currentState!.validate()) {
      // Validation passed, save form state
      _formKey.currentState!.save();

      // Get input values
      final username = _usernameController.text;
      final email = _emailController.text;

      // Process form data (e.g., submit to server)
      _processFormData(username, email);
    }
  }

  // Process form data
  void _processFormData(String username, String email) {
    print('Username: $username');
    print('Email: $email');

    // Show submission success message
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('Form submitted successfully')),
    );

    // Can navigate to other pages here
    // Navigator.pushNamed(context, '/success');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Form Submission')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Form(
          key: _formKey,
          autovalidateMode: AutovalidateMode.onUserInteraction,
          child: Column(
            children: [
              TextFormField(
                controller: _usernameController,
                decoration: const InputDecoration(
                  labelText: 'Username',
                  border: OutlineInputBorder(),
                ),
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please enter username';
                  }
                  if (value.length < 3) {
                    return 'Username must be at least 3 characters';
                  }
                  return null;
                },
                // Save callback (triggered when save() is called)
                onSaved: (value) {
                  print('Username saved: $value');
                },
              ),
              const SizedBox(height: 16),
              TextFormField(
                controller: _emailController,
                decoration: const InputDecoration(
                  labelText: 'Email',
                  border: OutlineInputBorder(),
                ),
                keyboardType: TextInputType.emailAddress,
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please enter email';
                  }
                  if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(value)) {
                    return 'Please enter a valid email';
                  }
                  return null;
                },
              ),
              const SizedBox(height: 24),
              ElevatedButton(
                onPressed: _submitForm,
                child: const Text('Submit'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Form processing flow:

User enters data
Validation is triggered (manually or automatically)
User clicks the submit button
Call _formKey.currentState!.validate() to validate all fields
After successful validation, call _formKey.currentState!.save() to save all field values
Retrieve input data and process it (e.g., submit to server)

3. Manually Controlling Validation Timing

In addition to automatic validation, you can also manually control when validation occurs:

// Only validate on submission
Form(
  key: _formKey,
  autovalidateMode: AutovalidateMode.disabled, // Disable automatic validation
  // ...
)

// Manually trigger validation for a single field
void _validateUsername() {
  _usernameFieldKey.currentState?.validate();
}

// Reset the form
void _resetForm() {
  _formKey.currentState?.reset();
}

III. Text Controller: TextEditingController

TextEditingController is used to control the content of text input widgets. It can retrieve, set, and listen to changes in input content, making it an important tool for handling form data.

1. Basic Usage

class TextEditingControllerExample extends StatefulWidget {
  const TextEditingControllerExample({super.key});

  @override
  State<TextEditingControllerExample> createState() => _TextEditingControllerExampleState();
}

class _TextEditingControllerExampleState extends State<TextEditingControllerExample> {
  // Create text controller
  final _controller = TextEditingController();

  @override
  void initState() {
    super.initState();

    // Set initial value
    _controller.text = 'Initial value';

    // Listen to text changes
    _controller.addListener(_onTextChanged);
  }

  @override
  void dispose() {
    // Remove listener and release resources
    _controller.removeListener(_onTextChanged);
    _controller.dispose();
    super.dispose();
  }

  // Text change callback
  void _onTextChanged() {
    print('Text changed: ${_controller.text}');
  }

  // Get input value
  void _getValue() {
    final text = _controller.text;
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Current value: $text')),
    );
  }

  // Set input value
  void _setValue() {
    _controller.text = 'New value set programmatically';
  }

  // Clear input
  void _clearValue() {
    _controller.clear();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Text Controller')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            TextField(
              controller: _controller, // Associate with controller
              decoration: const InputDecoration(
                labelText: 'Enter text',
                border: OutlineInputBorder(),
              ),
            ),
            const SizedBox(height: 16),
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceAround,
              children: [
                ElevatedButton(
                  onPressed: _getValue,
                  child: const Text('Get Value'),
                ),
                ElevatedButton(
                  onPressed: _setValue,
                  child: const Text('Set Value'),
                ),
                ElevatedButton(
                  onPressed: _clearValue,
                  child: const Text('Clear'),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

2. Advanced Usage

TextEditingController also provides some advanced features:

Selecting text:

// Select text
_controller.selection = TextSelection(
  baseOffset: 2,
  extentOffset: 5,
);

// Select all text
_controller.selection = TextSelection(
  baseOffset: 0,
  extentOffset: _controller.text.length,
);

Setting cursor position:

// Set cursor position to the end
_controller.selection = TextSelection.fromPosition(
  TextPosition(offset: _controller.text.length),
);

Styled text: Using TextSpan to set rich text:

final _richTextController = TextEditingController(
  text: 'Hello World',
);

// In build method
TextField(
  controller: _richTextController,
  decoration: const InputDecoration(labelText: 'Rich Text'),
  style: const TextStyle(fontSize: 16),
  // Can restrict input format through inputFormatters
)

IV. Example: Implementing Login and Registration Forms

The following implements complete login and registration forms with features including input validation, form submission, and password show/hide toggle.

1. Login Form

class LoginForm extends StatefulWidget {
  const LoginForm({super.key});

  @override
  State<LoginForm> createState() => _LoginFormState();
}

class _LoginFormState extends State<LoginForm> {
  final _formKey = GlobalKey<FormState>();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();
  bool _obscurePassword = true; // Controls whether password is visible
  bool _isLoading = false; // Controls loading state

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  // Toggle password visibility
  void _togglePasswordVisibility() {
    setState(() {
      _obscurePassword = !_obscurePassword;
    });
  }

  // Submit login form
  Future<void> _submitLogin() async {
    if (_formKey.currentState!.validate()) {
      setState(() {
        _isLoading = true;
      });

      // Simulate login request
      try {
        await Future.delayed(const Duration(seconds: 2));
        // Login successful, navigate to home page
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Login successful')),
          );
          // Navigator.pushReplacementNamed(context, '/home');
        }
      } catch (e) {
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Login failed: $e')),
          );
        }
      } finally {
        if (mounted) {
          setState(() {
            _isLoading = false;
          });
        }
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      autovalidateMode: AutovalidateMode.onUserInteraction,
      child: Column(
        children: [
          TextFormField(
            controller: _emailController,
            decoration: const InputDecoration(
              labelText: 'Email',
              prefixIcon: Icon(Icons.email),
              border: OutlineInputBorder(),
            ),
            keyboardType: TextInputType.emailAddress,
            enabled: !_isLoading,
            validator: (value) {
              if (value == null || value.isEmpty) {
                return 'Please enter your email';
              }
              if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(value)) {
                return 'Please enter a valid email';
              }
              return null;
            },
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: _passwordController,
            decoration: InputDecoration(
              labelText: 'Password',
              prefixIcon: const Icon(Icons.lock),
              border: const OutlineInputBorder(),
              // Password visibility toggle button
              suffixIcon: IconButton(
                icon: Icon(
                  _obscurePassword ? Icons.visibility : Icons.visibility_off,
                ),
                onPressed: _togglePasswordVisibility,
              ),
            ),
            obscureText: _obscurePassword,
            enabled: !_isLoading,
            validator: (value) {
              if (value == null || value.isEmpty) {
                return 'Please enter your password';
              }
              if (value.length < 6) {
                return 'Password must be at least 6 characters';
              }
              return null;
            },
          ),
          const SizedBox(height: 8),
          // Forgot password link
          Align(
            alignment: Alignment.centerRight,
            child: TextButton(
              onPressed: () {
                // Navigate to forgot password page
                // Navigator.pushNamed(context, '/forgot-password');
              },
              child: const Text('Forgot Password?'),
            ),
          ),
          const SizedBox(height: 16),
          // Login button
          SizedBox(
            width: double.infinity,
            child: ElevatedButton(
              onPressed: _isLoading ? null : _submitLogin,
              style: ElevatedButton.styleFrom(
                padding: const EdgeInsets.symmetric(vertical: 16),
              ),
              child: _isLoading
                  ? const CircularProgressIndicator(color: Colors.white)
                  : const Text('Login'),
            ),
          ),
          const SizedBox(height: 16),
          // Register link
          Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              const Text("Don't have an account?"),
              TextButton(
                onPressed: () {
                  // Navigate to register page
                  // Navigator.pushNamed(context, '/register');
                },
                child: const Text('Register'),
              ),
            ],
          ),
        ],
      ),
    );
  }
}

2. Registration Form

class RegisterForm extends StatefulWidget {
  const RegisterForm({super.key});

  @override
  State<RegisterForm> createState() => _RegisterFormState();
}

class _RegisterFormState extends State<RegisterForm> {
  final _formKey = GlobalKey<FormState>();
  final _usernameController = TextEditingController();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();
  final _confirmPasswordController = TextEditingController();

  bool _obscurePassword = true;
  bool _obscureConfirmPassword = true;
  bool _isLoading = false;
  String? _selectedGender;

  @override
  void dispose() {
    _usernameController.dispose();
    _emailController.dispose();
    _passwordController.dispose();
    _confirmPasswordController.dispose();
    super.dispose();
  }

  void _togglePasswordVisibility() {
    setState(() {
      _obscurePassword = !_obscurePassword;
    });
  }

  void _toggleConfirmPasswordVisibility() {
    setState(() {
      _obscureConfirmPassword = !_obscureConfirmPassword;
    });
  }

  Future<void> _submitRegistration() async {
    if (_formKey.currentState!.validate()) {
      setState(() {
        _isLoading = true;
      });

      // Simulate registration request
      try {
        await Future.delayed(const Duration(seconds: 2));
        // Registration successful
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Registration successful')),
          );
          Navigator.pop(context); // Return to login page
        }
      } catch (e) {
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Registration failed: $e')),
          );
        }
      } finally {
        if (mounted) {
          setState(() {
            _isLoading = false;
          });
        }
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      autovalidateMode: AutovalidateMode.onUserInteraction,
      child: SingleChildScrollView(
        child: Column(
          children: [
            TextFormField(
              controller: _usernameController,
              decoration: const InputDecoration(
                labelText: 'Username',
                prefixIcon: Icon(Icons.person),
                border: OutlineInputBorder(),
              ),
              enabled: !_isLoading,
              validator: (value) {
                if (value == null || value.isEmpty) {
                  return 'Please enter your username';
                }
                if (value.length < 3) {
                  return 'Username must be at least 3 characters';
                }
                if (value.length > 20) {
                  return 'Username cannot exceed 20 characters';
                }
                return null;
              },
            ),
            const SizedBox(height: 16),
            TextFormField(
              controller: _emailController,
              decoration: const InputDecoration(
                labelText: 'Email',
                prefixIcon: Icon(Icons.email),
                border: OutlineInputBorder(),
              ),
              keyboardType: TextInputType.emailAddress,
              enabled: !_isLoading,
              validator: (value) {
                if (value == null || value.isEmpty) {
                  return 'Please enter your email';
                }
                if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(value)) {
                  return 'Please enter a valid email';
                }
                return null;
              },
            ),
            const SizedBox(height: 16),
            // Gender selection
            DropdownButtonFormField<String>(
              value: _selectedGender,
              decoration: const InputDecoration(
                labelText: 'Gender',
                prefixIcon: Icon(Icons.person_2),
                border: OutlineInputBorder(),
              ),
              items: const [
                DropdownMenuItem(value: 'male', child: Text('Male')),
                DropdownMenuItem(value: 'female', child: Text('Female')),
                DropdownMenuItem(value: 'other', child: Text('Other')),
              ],
              onChanged: !_isLoading ? (value) {
                setState(() {
                  _selectedGender = value;
                });
              } : null,
              validator: (value) {
                if (value == null) {
                  return 'Please select your gender';
                }
                return null;
              },
            ),
            const SizedBox(height: 16),
            TextFormField(
              controller: _passwordController,
              decoration: InputDecoration(
                labelText: 'Password',
                prefixIcon: const Icon(Icons.lock),
                border: const OutlineInputBorder(),
                suffixIcon: IconButton(
                  icon: Icon(
                    _obscurePassword ? Icons.visibility : Icons.visibility_off,
                  ),
                  onPressed: _togglePasswordVisibility,
                ),
              ),
              obscureText: _obscurePassword,
              enabled: !_isLoading,
              validator: (value) {
                if (value == null || value.isEmpty) {
                  return 'Please enter your password';
                }
                if (value.length < 6) {
                  return 'Password must be at least 6 characters';
                }
                if (!RegExp(r'[A-Z]').hasMatch(value)) {
                  return 'Password must contain at least one uppercase letter';
                }
                if (!RegExp(r'[0-9]').hasMatch(value)) {
                  return 'Password must contain at least one number';
                }
                return null;
              },
            ),
            const SizedBox(height: 16),
            TextFormField(
              controller: _confirmPasswordController,
              decoration: InputDecoration(
                labelText: 'Confirm Password',
                prefixIcon: const Icon(Icons.lock_clock),
                border: const OutlineInputBorder(),
                suffixIcon: IconButton(
                  icon: Icon(
                    _obscureConfirmPassword ? Icons.visibility : Icons.visibility_off,
                  ),
                  onPressed: _toggleConfirmPasswordVisibility,
                ),
              ),
              obscureText: _obscureConfirmPassword,
              enabled: !_isLoading,
              validator: (value) {
                if (value == null || value.isEmpty) {
                  return 'Please confirm your password';
                }
                if (value != _passwordController.text) {
                  return 'Passwords do not match';
                }
                return null;
              },
            ),
            const SizedBox(height: 16),
            // Agree to terms
            FormField<bool>(
              initialValue: false,
              validator: (value) {
                if (value == false) {
                  return 'Please agree to the terms';
                }
                return null;
              },
              builder: (formFieldState) {
                return Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Row(
                      children: [
                        Checkbox(
                          value: formFieldState.value,
                          onChanged: _isLoading ? null : (value) {
                            formFieldState.didChange(value);
                          },
                        ),
                        const Text('I agree to the Terms of Service and Privacy Policy'),
                      ],
                    ),
                    if (formFieldState.hasError)
                      Padding(
                        padding: const EdgeInsets.only(top: 4, left: 4),
                        child: Text(
                          formFieldState.errorText!,
                          style: const TextStyle(
                            color: Colors.red,
                            fontSize: 12,
                          ),
                        ),
                      ),
                  ],
                );
              },
            ),
            const SizedBox(height: 24),
            // Register button
            SizedBox(
              width: double.infinity,
              child: ElevatedButton(
                onPressed: _isLoading ? null : _submitRegistration,
                style: ElevatedButton.styleFrom(
                  padding: const EdgeInsets.symmetric(vertical: 16),
                ),
                child: _isLoading
                    ? const CircularProgressIndicator(color: Colors.white)
                    : const Text('Register'),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

3. Form Page Integration

class AuthScreen extends StatefulWidget {
  const AuthScreen({super.key});

  @override
  State<AuthScreen> createState() => _AuthScreenState();
}

class _AuthScreenState extends State<AuthScreen> {
  bool _isLogin = true; // Toggle between login/register modes

  // Toggle form mode
  void _toggleFormMode() {
    setState(() {
      _isLogin = !_isLogin;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Padding(
        padding: const EdgeInsets.all(24.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // Title
            Text(
              _isLogin ? 'Welcome Back' : 'Create Account',
              style: const TextStyle(
                fontSize: 28,
                fontWeight: FontWeight.bold,
              ),
            ),
            const SizedBox(height: 8),
            Text(
              _isLogin 
                  ? 'Sign in to your account to continue' 
                  : 'Fill in the details to create a new account',
              style: const TextStyle(
                color: Colors.grey,
                fontSize: 16,
              ),
            ),
            const SizedBox(height: 32),
            // Show login or register form
            _isLogin ? const LoginForm() : const RegisterForm(),
            // Toggle form button
            if (!_isLogin)
              TextButton(
                onPressed: _toggleFormMode,
                child: const Text('Already have an account? Login'),
              ),
          ],
        ),
      ),
    );
  }
}

Flutter Lesson 9: Common List Components

Ge Ji — Sun, 10 Aug 2025 11:12:18 +0000

In mobile application development, lists are one of the most common ways to display data. Whether it's contact lists, product displays, or news feeds, list components are essential. Flutter provides a rich set of list-related components that can meet various complex layout and performance requirements. This lesson will detail the commonly used list components in Flutter and their advanced usage, helping you build efficient and beautiful list interfaces.

I. Basic Lists: ListView

ListView is the most basic list component in Flutter, which can arrange child components linearly along one direction. ListView has multiple constructors suitable for different usage scenarios.

1. Basic Usage: ListView with Direct Children

The simplest way to use ListView is to directly pass a list of child components in the children property:

ListView(
  // List padding
  padding: const EdgeInsets.all(16),
  // List items
  children: const [
    Text('Item 1', style: TextStyle(fontSize: 18)),
    Text('Item 2', style: TextStyle(fontSize: 18)),
    Text('Item 3', style: TextStyle(fontSize: 18)),
    Text('Item 4', style: TextStyle(fontSize: 18)),
    Text('Item 5', style: TextStyle(fontSize: 18)),
  ],
)

This approach is suitable for cases with a small number of child components, as it creates all child components at once, even if they haven't been displayed on the screen yet.

2. Optimizing Long Lists: ListView.builder

When the number of list items is large (more than 10) or the list length is uncertain, you should use ListView.builder to build the list. It dynamically creates and destroys list items based on the scroll position, significantly improving performance:

class LongListExample extends StatelessWidget {
  const LongListExample({super.key});

  @override
  Widget build(BuildContext context) {
    // Simulate 1000 items of data
    return ListView.builder(
      // Number of list items
      itemCount: 1000,
      // List padding
      padding: const EdgeInsets.all(16),
      // Item builder
      itemBuilder: (context, index) {
        // Only created when needed for display
        return ListTile(
          title: Text('Item ${index + 1}'),
          subtitle: Text('This is item ${index + 1} in the list'),
          leading: const Icon(Icons.list),
          trailing: const Icon(Icons.arrow_forward_ios),
        );
      },
    );
  }
}

Core parameters of ListView.builder:

itemCount: The number of list items; when specified, the list will have a definite length
itemBuilder: Item construction function that receives an index parameter and returns the item at the corresponding position
physics: Controls scrolling behavior (e.g., NeverScrollableScrollPhysics disables scrolling)
shrinkWrap: Whether to determine the list size based on child component dimensions, default is false

3. Other ListView Constructors

ListView.separated: Allows adding separators between list items, suitable for scenarios requiring dividers:

ListView.separated(
  itemCount: 50,
  // Item builder
  itemBuilder: (context, index) {
    return ListTile(
      title: Text('Contact ${index + 1}'),
      leading: const CircleAvatar(child: Icon(Icons.person)),
    );
  },
  // Separator builder
  separatorBuilder: (context, index) {
    // Divider between each pair of items
    return const Divider(height: 1);
  },
)

ListView.custom: Fully customizes how list items are built, suitable for complex scenarios, needs to work with SliverChildBuilderDelegate or SliverChildListDelegate.

4. List Scroll Control

ScrollController allows you to control list scrolling behavior, such as scrolling to a specific position and listening to scroll events:

class ControlledListExample extends StatefulWidget {
  const ControlledListExample({super.key});

  @override
  State<ControlledListExample> createState() => _ControlledListExampleState();
}

class _ControlledListExampleState extends State<ControlledListExample> {
  // Create scroll controller
  final ScrollController _scrollController = ScrollController();

  @override
  void dispose() {
    // Release resources
    _scrollController.dispose();
    super.dispose();
  }

  // Scroll to top
  void _scrollToTop() {
    _scrollController.animateTo(
      0,
      duration: const Duration(milliseconds: 500),
      curve: Curves.easeInOut,
    );
  }

  // Scroll to bottom
  void _scrollToBottom() {
    _scrollController.animateTo(
      _scrollController.position.maxScrollExtent,
      duration: const Duration(milliseconds: 500),
      curve: Curves.easeInOut,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Controlled List')),
      body: ListView.builder(
        // Associate scroll controller
        controller: _scrollController,
        itemCount: 50,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text('Item ${index + 1}'),
          );
        },
      ),
      floatingActionButton: Row(
        mainAxisAlignment: MainAxisAlignment.end,
        children: [
          FloatingActionButton(
            onPressed: _scrollToTop,
            child: const Icon(Icons.arrow_upward),
          ),
          const SizedBox(width: 10),
          FloatingActionButton(
            onPressed: _scrollToBottom,
            child: const Icon(Icons.arrow_downward),
          ),
        ],
      ),
    );
  }
}

II. List Items: ListTile and Custom List Items

List items are the basic building blocks of lists. Flutter provides the preset ListTile style as well as support for fully custom list items.

1. ListTile Component

ListTile is a Material Design-style list item component that contains common list item elements such as icons, titles, and subtitles:

ListTile(
  // Leading icon
  leading: const Icon(Icons.email),
  // Main title
  title: const Text('Contact Us'),
  // Subtitle
  subtitle: const Text('support@example.com'),
  // Trailing icon
  trailing: const Icon(Icons.arrow_forward_ios),
  // Whether it's clickable
  enabled: true,
  // Whether it's selected
  selected: false,
  // Tap event
  onTap: () {
    print('ListTile tapped');
  },
  // Long press event
  onLongPress: () {
    print('ListTile long pressed');
  },
  // Spacing between leading icon and text
  contentPadding: const EdgeInsets.symmetric(horizontal: 16),
)

ListTile variants:

CheckboxListTile: List item with checkbox
RadioListTile: List item with radio button
SwitchListTile: List item with switch

Examples:

// List item with checkbox
CheckboxListTile(
  title: const Text('Remember me'),
  value: true,
  onChanged: (value) {},
  controlAffinity: ListTileControlAffinity.leading, // Checkbox position
)

// List item with switch
SwitchListTile(
  title: const Text('Dark mode'),
  value: false,
  onChanged: (value) {},
  secondary: const Icon(Icons.dark_mode),
)

2. Custom List Items

When ListTile can't meet your needs, you can build custom list items using basic components like Container and Row:

final products = [
  PItem(
    'a',
    11.2,
    'https://picsum.photos/300/400?random=$3',
    23.1,
  ),
  PItem(
    'b',
    12.2,
    'https://picsum.photos/300/400?random=$5',
    26.1,
  ),
];

class PItem {
  final String name;
  final double price;
  final String imageUrl;
  final double rating;

  PItem(this.name, this.price, this.imageUrl, this.rating);
}

// Custom product list item
class ProductItem extends StatelessWidget {
  final String name;
  final double price;
  final String imageUrl;
  final double rating;

  const ProductItem({
    super.key,
    required this.name,
    required this.price,
    required this.imageUrl,
    required this.rating,
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(12),
      margin: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
      decoration: BoxDecoration(
        color: Colors.white,
        borderRadius: BorderRadius.circular(8),
        boxShadow: [
          BoxShadow(
            color: Colors.grey.withOpacity(0.2),
            blurRadius: 4,
            offset: const Offset(0, 2),
          ),
        ],
      ),
      child: Row(
        children: [
          // Product image
          ClipRRect(
            borderRadius: BorderRadius.circular(4),
            child: Image.network(
              imageUrl,
              width: 80,
              height: 80,
              fit: BoxFit.cover,
            ),
          ),
          const SizedBox(width: 12),
          // Product information
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  name,
                  style: const TextStyle(
                    fontSize: 16,
                    fontWeight: FontWeight.bold,
                  ),
                  maxLines: 2,
                  overflow: TextOverflow.ellipsis,
                ),
                const SizedBox(height: 4),
                // Rating
                Row(
                  children: [
                    const Icon(Icons.star, color: Colors.yellow, size: 16),
                    const SizedBox(width: 4),
                    Text(
                      rating.toString(),
                      style: const TextStyle(
                        fontSize: 14,
                        color: Colors.grey,
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ),
          // Price
          Text(
            '\$${price.toStringAsFixed(2)}',
            style: const TextStyle(
              fontSize: 16,
              fontWeight: FontWeight.bold,
              color: Colors.red,
            ),
          ),
        ],
      ),
    );
  }
}

// Using custom list items
ListView.builder(
  itemCount: products.length,
  itemBuilder: (context, index) {
    final product = products[index];
    return ProductItem(
      name: product.name,
      price: product.price,
      imageUrl: product.imageUrl,
      rating: product.rating,
    );
  },
)

III. Grid Layout: GridView

GridView is used to build grid layouts, suitable for scenarios like image galleries and product grids. It also provides multiple constructors to adapt to different usage needs.

1. GridView.count

GridView.count allows specifying the number of columns per row and is the most commonly used grid layout constructor:

GridView.count(
  // Number of columns per row
  crossAxisCount: 2,
  // Spacing between columns
  crossAxisSpacing: 10,
  // Spacing between rows
  mainAxisSpacing: 10,
  // Grid padding
  padding: const EdgeInsets.all(10),
  // Aspect ratio of child components
  childAspectRatio: 1.0, // Equal width and height
  // List of child components
  children: List.generate(20, (index) {
    return Container(
      color: Colors.blue[100 * ((index % 9) + 1)],
      child: Center(
        child: Text(
          'Item $index',
          style: const TextStyle(fontSize: 18),
        ),
      ),
    );
  }),
)

Core parameters:

crossAxisCount: Number of components in the cross-axis direction (i.e., columns per row)
childAspectRatio: Aspect ratio of child components, affecting the shape of grid items
crossAxisSpacing and mainAxisSpacing: Control spacing between grid items

2. GridView.builder

When there are many grid items, you should use GridView.builder to optimize performance, as it dynamically creates and destroys grid items:

class ImageGallery extends StatelessWidget {
  const ImageGallery({super.key});

  @override
  Widget build(BuildContext context) {
    return GridView.builder(
      // Grid layout delegate
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
        crossAxisCount: 3, // 3 columns
        crossAxisSpacing: 4,
        mainAxisSpacing: 4,
        childAspectRatio: 0.75, // 4:3 aspect ratio
      ),
      // Number of grid items
      itemCount: 50,
      // Grid item builder
      itemBuilder: (context, index) {
        // Build image grid item
        return ClipRRect(
          borderRadius: BorderRadius.circular(4),
          child: Image.network(
            // Use network image
            'https://picsum.photos/300/400?random=$index',
            fit: BoxFit.cover,
          ),
        );
      },
    );
  }
}

GridView.builder needs to specify grid layout rules through the gridDelegate parameter. Common ones are:

SliverGridDelegateWithFixedCrossAxisCount: Fixed number of columns
SliverGridDelegateWithMaxCrossAxisExtent: Automatically calculates number of columns based on maximum width

3. GridView.extent

GridView.extent allows specifying the maximum width of grid items and automatically calculates how many columns can fit in each row:

GridView.extent(
  // Maximum width of grid items
  maxCrossAxisExtent: 150,
  // Column spacing
  crossAxisSpacing: 10,
  // Row spacing
  mainAxisSpacing: 10,
  // Padding
  padding: const EdgeInsets.all(10),
  // Child components
  children: List.generate(12, (index) {
    return Container(
      color: Colors.green[100 * ((index % 9) + 1)],
      child: Center(
        child: Text('Item $index'),
      ),
    );
  }),
)

This approach is suitable for scenarios where you need to automatically adjust the number of columns on different screen sizes.

IV. List Scroll Listening and Pull-to-Refresh

In practical applications, we often need to listen to the scroll state of lists (e.g., to implement infinite scroll loading) or provide pull-to-refresh functionality.

1. Pull-to-Refresh: RefreshIndicator

RefreshIndicator is the official component for implementing pull-to-refresh functionality, which is simple to use and conforms to Material Design specifications:

class RefreshableList extends StatefulWidget {
  const RefreshableList({super.key});

  @override
  State<RefreshableList> createState() => _RefreshableListState();
}

class _RefreshableListState extends State<RefreshableList> {
  List<int> _items = List.generate(20, (index) => index);

  // Simulate refreshing data
  Future<void> _refreshData() async {
    // Simulate network request delay
    await Future.delayed(const Duration(seconds: 2));

    // Update data
    setState(() {
      _items = List.generate(20, (index) => index);
    });
  }

  @override
  Widget build(BuildContext context) {
    return RefreshIndicator(
      // Refresh indicator color
      color: Colors.blue,
      // Refresh background color
      backgroundColor: Colors.white,
      // Refresh callback function (must return Future)
      onRefresh: _refreshData,
      // Child list
      child: ListView.builder(
        itemCount: _items.length,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text('Item ${_items[index] + 1}'),
          );
        },
      ),
    );
  }
}

The core of RefreshIndicator is the onRefresh callback function, which must return a Future. When the Future completes, the refresh indicator will stop animating.

2. Infinite Scroll and Scroll Listening

By listening to list scroll events, you can implement infinite scroll loading functionality (automatically loading more data when the user scrolls to the bottom of the list):

class InfiniteScrollList extends StatefulWidget {
  const InfiniteScrollList({super.key});

  @override
  State<InfiniteScrollList> createState() => _InfiniteScrollListState();
}

class _InfiniteScrollListState extends State<InfiniteScrollList> {
  final List<int> _items = List.generate(20, (index) => index);
  final ScrollController _scrollController = ScrollController();
  bool _isLoading = false;
  int _page = 1;

  @override
  void initState() {
    super.initState();
    // Listen to scroll events
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    // Remove listener and release resources
    _scrollController.removeListener(_onScroll);
    _scrollController.dispose();
    super.dispose();
  }

  // Scroll event handling
  void _onScroll() {
    // Check if scrolled to near the bottom
    if (_scrollController.position.pixels >=
            _scrollController.position.maxScrollExtent - 200 &&
        !_isLoading) {
      // Load more data
      _loadMoreData();
    }
  }

  // Simulate loading more data
  Future<void> _loadMoreData() async {
    setState(() {
      _isLoading = true;
    });

    // Simulate network request delay
    await Future.delayed(const Duration(seconds: 2));

    setState(() {
      _page++;
      // Add new data
      final newItems = List.generate(10, (index) => _items.length + index);
      _items.addAll(newItems);
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      controller: _scrollController,
      // Number of list items (existing data + loading indicator)
      itemCount: _items.length + (_isLoading ? 1 : 0),
      itemBuilder: (context, index) {
        // If it's the last item and loading, show loading indicator
        if (index == _items.length) {
          return const Padding(
            padding: EdgeInsets.symmetric(vertical: 20),
            child: Center(
              child: CircularProgressIndicator(),
            ),
          );
        }

        // Normal list item
        return ListTile(
          title: Text('Item ${_items[index] + 1}'),
          subtitle: Text('Page ${(_items[index] ~/ 10) + 1}'),
        );
      },
    );
  }
}

Key points for implementing infinite scroll:

Use ScrollController to listen to scroll events
Determine if scrolling to near the bottom position (usually a certain distance from the bottom)
Trigger logic to load more data and display loading indicator
Update list data after loading is complete and hide loading indicator

3. Scroll Position Restoration

In some scenarios (such as after screen rotation or returning after page switching), you need to restore the scroll position of the list. Flutter provides the keepScrollOffset property of ScrollController to achieve this:

final ScrollController _scrollController = ScrollController(
  keepScrollOffset: true, // Default is true, will save scroll position
);

For scenarios where list items change dynamically, you may need to use PageStorageKey to help Flutter save and restore scroll positions:

ListView.builder(
  key: const PageStorageKey<String>('my_list_key'),
  // ...other parameters
)

V. List Performance Optimization

When a list contains a large amount of data or complex list items, performance optimization becomes particularly important. Here are some common list performance optimization techniques:

1. Use Appropriate List Constructors

Small amount of fixed data: Use regular constructors of ListView or GridView
Large amount of data or dynamic data: Use ListView.builder or GridView.builder
Need separators: Use ListView.separated

2. Reduce Rebuild Scope

Extract list items into independent StatelessWidget or StatefulWidget
Use const constructors to create immutable list items:

// Before optimization
itemBuilder: (context, index) {
  return ListTile(
    title: Text('Item $index'),
    leading: Icon(Icons.item),
  );
}

// After optimization
itemBuilder: (context, index) {
  return MyListItem(
    index: index,
  );
}

// List item component
class MyListItem extends StatelessWidget {
  final int index;

  // Use const constructor
  const MyListItem({super.key, required this.index});

  @override
  Widget build(BuildContext context) {
    return ListTile(
      title: Text('Item $index'),
      leading: const Icon(Icons.item), // Use const for unchanged parts
    );
  }
}

3. Image Optimization

Use appropriately sized images to avoid shrinking large images
Implement image caching (can use cached_network_image library)
Pause image loading when list is scrolling, resume after scrolling stops

4. Avoid Time-Consuming Operations in Build Methods

Ensure the itemBuilder method is concise and efficient. Avoid performing:

Complex calculations
Network requests
Creation of a large number of objects

5. Use RepaintBoundary to Reduce Redraws

For list items that redraw frequently, wrap them with RepaintBoundary to avoid affecting other list items:

itemBuilder: (context, index) {
  return RepaintBoundary(
    child: AnimatedListItem(index: index),
  );
}

VI. Example: Product List Application

The following implements a fully functional product list application with features including grid/list switching, pull-to-refresh, and infinite scrolling:

// Product model
class Product {
  final int id;
  final String name;
  final String description;
  final double price;
  final double rating;
  final String imageUrl;

  Product({
    required this.id,
    required this.name,
    required this.description,
    required this.price,
    required this.rating,
    required this.imageUrl,
  });
}

// Main application
class ProductListApp extends StatefulWidget {
  const ProductListApp({super.key});

  @override
  State<ProductListApp> createState() => _ProductListAppState();
}

class _ProductListAppState extends State<ProductListApp> {
  // Product list data
  final List<Product> _products = [];
  // Scroll controller
  final ScrollController _scrollController = ScrollController();
  // Loading state
  bool _isLoading = false;
  // Current page number
  int _page = 1;
  // Layout mode (grid/list)
  bool _isGridMode = true;

  @override
  void initState() {
    super.initState();
    // Initial data loading
    _loadProducts();
    // Listen to scroll events
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    _scrollController.dispose();
    super.dispose();
  }

  // Load product data
  Future<void> _loadProducts({bool isRefresh = false}) async {
    if (isRefresh) {
      // Reset page number when refreshing
      _page = 1;
    }

    setState(() {
      _isLoading = true;
    });

    // Simulate network request
    await Future.delayed(const Duration(seconds: 1));

    // Generate mock data
    final newProducts = List.generate(10, (index) {
      final id = ((_page - 1) * 10) + index + 1;
      return Product(
        id: id,
        name: 'Product $id',
        description: 'This is a description for product $id',
        price: 10.0 + (id * 0.5),
        rating: 3.0 + (id % 2) + (id % 10) * 0.1,
        imageUrl: 'https://picsum.photos/300/300?random=$id',
      );
    });

    setState(() {
      if (isRefresh) {
        _products.clear();
      }
      _products.addAll(newProducts);
      _page++;
      _isLoading = false;
    });
  }

  // Pull to refresh
  Future<void> _refreshProducts() async {
    await _loadProducts(isRefresh: true);
  }

  // Load more when scrolling to bottom
  void _onScroll() {
    if (_scrollController.position.pixels >=
            _scrollController.position.maxScrollExtent - 300 &&
        !_isLoading) {
      _loadProducts();
    }
  }

  // Toggle layout mode
  void _toggleLayoutMode() {
    setState(() {
      _isGridMode = !_isGridMode;
    });
  }

  // Build product item
  Widget _buildProductItem(Product product) {
    if (_isGridMode) {
      // Grid mode item
      return Card(
        elevation: 2,
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Expanded(
              child: ClipRRect(
                borderRadius: const BorderRadius.vertical(top: Radius.circular(4)),
                child: Image.network(
                  product.imageUrl,
                  width: double.infinity,
                  fit: BoxFit.cover,
                ),
              ),
            ),
            Padding(
              padding: const EdgeInsets.all(8),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    product.name,
                    maxLines: 1,
                    overflow: TextOverflow.ellipsis,
                    style: const TextStyle(fontWeight: FontWeight.bold),
                  ),
                  const SizedBox(height: 4),
                  Row(
                    mainAxisAlignment: MainAxisAlignment.spaceBetween,
                    children: [
                      Text(
                        '\$${product.price.toStringAsFixed(2)}',
                        style: const TextStyle(color: Colors.red),
                      ),
                      Row(
                        children: [
                          const Icon(Icons.star, color: Colors.yellow, size: 16),
                          const SizedBox(width: 2),
                          Text(
                            product.rating.toStringAsFixed(1),
                            style: const TextStyle(fontSize: 14),
                          ),
                        ],
                      ),
                    ],
                  ),
                ],
              ),
            ),
          ],
        ),
      );
    } else {
      // List mode item
      return ListTile(
        leading: ClipRRect(
          borderRadius: BorderRadius.circular(4),
          child: Image.network(
            product.imageUrl,
            width: 50,
            height: 50,
            fit: BoxFit.cover,
          ),
        ),
        title: Text(product.name),
        subtitle: Text(
          product.description,
          maxLines: 1,
          overflow: TextOverflow.ellipsis,
        ),
        trailing: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              '\$${product.price.toStringAsFixed(2)}',
              style: const TextStyle(
                color: Colors.red,
                fontWeight: FontWeight.bold,
              ),
            ),
            Row(
              mainAxisSize: MainAxisSize.min,
              children: [
                const Icon(Icons.star, color: Colors.yellow, size: 14),
                const SizedBox(width: 2),
                Text(
                  product.rating.toStringAsFixed(1),
                  style: const TextStyle(fontSize: 12),
                ),
              ],
            ),
          ],
        ),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Product List'),
        actions: [
          // Layout toggle button
          IconButton(
            icon: Icon(_isGridMode ? Icons.list : Icons.grid_view),
            onPressed: _toggleLayoutMode,
          ),
        ],
      ),
      body: RefreshIndicator(
        onRefresh: _refreshProducts,
        child: _products.isEmpty && _isLoading
            ? const Center(child: CircularProgressIndicator())
            : _products.isEmpty
                ? const Center(child: Text('No products found'))
                : _isGridMode
                    ? GridView.builder(
                        controller: _scrollController,
                        padding: const EdgeInsets.all(8),
                        gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
                          crossAxisCount: 2,
                          crossAxisSpacing: 8,
                          mainAxisSpacing: 8,
                          childAspectRatio: 0.8,
                        ),
                        itemCount: _products.length + (_isLoading ? 1 : 0),
                        itemBuilder: (context, index) {
                          if (index == _products.length) {
                            return const Center(child: CircularProgressIndicator());
                          }
                          return _buildProductItem(_products[index]);
                        },
                      )
                    : ListView.builder(
                        controller: _scrollController,
                        itemCount: _products.length + (_isLoading ? 1 : 0),
                        itemBuilder: (context, index) {
                          if (index == _products.length) {
                            return const Padding(
                              padding: EdgeInsets.symmetric(vertical: 20),
                              child: Center(child: CircularProgressIndicator()),
                            );
                          }
                          return _buildProductItem(_products[index]);
                        },
                      ),
      ),
    );
  }
}