flutter：文档注释与生成接口文档

是什么

shared_preferences 是 Flutter 里最常用的 轻量级本地存储插件。

它的主要功能是：

• 在 本地持久化保存少量数据（key-value 形式），类似于移动端原生的 NSUserDefaults（iOS）和 SharedPreferences（Android）。
• 存储的数据会一直保留（除非卸载应用或手动清除）。
• 适合保存 配置项、布尔开关、登录状态、主题模式、语言偏好、简单缓存 等。

它的主要特点有：

• 基于 键值对存储（类似字典/Map）。
• 支持的类型有限：int、double、bool、String、List<String>。
• 异步 API（因为底层可能涉及 IO）。
• 跨平台（iOS / Android / Web / macOS / Linux / Windows）。

使用步骤

1. 添加依赖

   flutter pub add shared_preferences
   

2. 导入

   import 'package:shared_preferences/shared_preferences.dart';
   

3. 写入数据

   final prefs = await SharedPreferences.getInstance();
   await prefs.setString('username', 'Alice');
   await prefs.setInt('age', 25);
   await prefs.setBool('isLogin', true);
   

4. 读取数据

   final prefs = await SharedPreferences.getInstance();
   final username = prefs.getString('username') ?? 'Guest';
   final age = prefs.getInt('age') ?? 0;
   final isLogin = prefs.getBool('isLogin') ?? false;
   

5. 获得所有的key

   // Set<String> getKeys() => Set<String>.from(_preferenceCache.keys);
   List<String> allKeys = prefs.getKeys().toList();
   

6. 判断数据是否存在

    bool isLoginExists = prefs.containsKey('isLogin');
   

7. 删除数据

   await prefs.remove('username');
   

8. 清空所有数据

   await prefs.clear();
   

案例：登录状态保存

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SharedPreferences with Expiry',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const LoginPage(),
    );
  }
}

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

  @override
  State<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  bool _isLogin = false;
  static const _loginKey = 'isLogin';
  static const _expiryKey = 'login_expiry';
  static const _ttlSeconds = 30; // 登录状态 30 秒过期

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

  Future<void> _loadLoginStatus() async {
    // 获取 SharedPreferences 实例
    final prefs = await SharedPreferences.getInstance();
    // 获得过期时间
    final expiryTime = prefs.getInt(_expiryKey);
    // 检查是否过期: ①expiryTime不为空；②当前时间大于过期时间
    if (expiryTime != null &&
        DateTime.now().millisecondsSinceEpoch > expiryTime) {
      // 已过期 -> 清理本地数据
      await prefs.remove(_loginKey);
      await prefs.remove(_expiryKey);
      // 把登录状态设置为 false
      setState(() => _isLogin = false);
      // 结束
      return;
    }
    // 未过期 -> 读取登录状态
    setState(() {
      // 读取登录状态，_isLogin 默认为 false
      _isLogin = prefs.getBool(_loginKey) ?? false;
    });
  }

  Future<void> _toggleLogin() async {
    // 获取 SharedPreferences 实例
    final prefs = await SharedPreferences.getInstance();

    if (_isLogin) {
      // 退出登录
      await prefs.remove(_loginKey);
      await prefs.remove(_expiryKey);
      setState(() => _isLogin = false);
    } else {
      // 登录，并设置过期时间
      final expiryTime =
          DateTime.now().millisecondsSinceEpoch + _ttlSeconds * 1000;
      await prefs.setBool(_loginKey, true);
      await prefs.setInt(_expiryKey, expiryTime);
      setState(() => _isLogin = true);
    }
  }

  _refresh() {
    _loadLoginStatus();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("Login with Expiry")),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(_isLogin ? "已登录 ✅ (30秒有效)" : "未登录 ❌"),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _toggleLogin,
              child: Text(_isLogin ? "退出登录" : "登录"),
            ),
            ElevatedButton(onPressed: _refresh, child: Text('刷新')),
          ],
        ),
      ),
    );
  }
}