客户端存储 (Client Storage)

---

Flet 的客户端存储（Client Storage）API 允许在客户端的本地持久化存储中保存键值对（key-value）数据。Flet 的具体底层实现使用了 Flutter 官方的 shared_preferences 包。

根据运行 Flet 应用的平台不同，具体的存储实现机制也有所差异：

• Web —— 浏览器本地存储 (Local storage)。
• Desktop (桌面端) —— 本地 JSON 文件。
• iOS —— NSUserDefaults。
• Android —— SharedPreferences。

客户端存储由 SharedPreferences 服务提供。创建一个并在需要期间保留对它的引用 —— 一旦没有任何存活的 Python 引用指向某个服务，该服务就会被注销：

import flet as ft

def main(page: ft.Page):
    prefs = ft.SharedPreferences()

---

写入数据 (Writing data)

支持写入字符串、数字、布尔值及列表：

# 写入字符串
await prefs.set("key", "value")

# 写入数字和布尔值
await prefs.set("number.setting", 12345)
await prefs.set("bool_setting", True)

# 写入列表 (List)
await prefs.set("favorite_colors", ["red", "green", "blue"])

提示

每个使用 shared_preferences 插件的 Flutter 应用都有自己的一组偏好设置。由于相同的 Flet 客户端（本质是一个 Flutter 编译的应用）被用来运行多个 Flet 应用的 UI，所以在同一个系统用户下，一个 Flet 应用中存储的本地数值对于运行的另一个 Flet 应用是完全可见并可用的。

为了将一个应用的设置与另一个应用进行区分，建议在所有存储键名上使用独特的命名空间前缀，例如 {company}.{product}.。例如，在第一个应用中存储认证 Token 可以使用 acme.one_app.auth_token，而在第二个应用中使用 acme.second_app.auth_token。

警告

将敏感数据（如密码、Token 等密钥）写入客户端存储前，开发者有责任对其进行加密处理，以防被同一设备上的其他应用或应用用户本人轻易读取或篡改。

---

读取数据 (Reading data)

读取的数据会自动转回写入时的原始数据类型：

# 数据值会被自动转换回原始类型
value = await prefs.get("key")

colors = await prefs.get("favorite_colors")
# colors 的值依旧是 ["red", "green", "blue"]

---

检查键是否存在 (Check if a key exists)

await prefs.contains_key("key")  # 如果键存在则返回 True

---

获取所有键名 (Get all keys)

你可以传入前缀来过滤匹配的键名列表：

await prefs.get_keys("key-prefix.")

---

移除某项数据 (Remove a value)

await prefs.remove("key")

---

清空所有存储 (Clear the storage)

await prefs.clear()

警告

clear() 是一个非常危险的函数，它会清除该用户运行过的所有 Flet 应用的全部偏好数据。这也再次警示我们：不应该将不可丢失的重要应用数据仅存放在客户端本地存储中。