storage - PythonIDE Docs

轻量级键值存储（基于 UserDefaults）：保存设置项、开关、计数和小型 JSON 配置。

边界：适合小数据偏好，不是文件数据库，也不是敏感数据存储。token / 密码用 keychain；大列表、离线缓存用 database。MiniApp 内键名会自动按应用目录隔离，不同 MiniApp 不会互相覆盖。

#模块概览

项	说明
导入	`import storage`
适合做什么	主题、排序、筛选条件、开关、小型 JSON 配置
调用时机	在 `on_change`、按钮回调或启动时读写；不要在 `body()` 里反复写入
推荐顺序	启动时 `get`（带默认值）→ 用户操作后 `set` → 需要时 `remove` / `all_keys`
键名规范	用 `settings.theme` 这类命名空间，避免不同脚本冲突

#快速开始

下面脚本写入并读取字符串、布尔、整数和 JSON：

python

import storage

storage.set("settings.theme", "dark")
storage.set_bool("settings.notifications", True)
storage.set_int("app.launch_count", storage.get_int("app.launch_count", 0) + 1)
storage.set_json("profile", {"name": "Ada", "level": 3})

print("主题:", storage.get("settings.theme", "system"))
print("通知:", storage.get_bool("settings.notifications", False))
print("启动次数:", storage.get_int("app.launch_count", 0))
print("资料:", storage.get_json("profile", {}))

#AppUI 示例

设置项与 State 同步：用户改动时写入 storage，启动时从 storage 恢复。

python

import appui
import storage

THEME_OPTIONS = ["跟随系统", "浅色", "深色"]

state = appui.State(
    theme=storage.get("settings.theme", "跟随系统"),
    notifications=storage.get_bool("settings.notifications", True),
    message="设置会自动保存",
)


def set_theme(value):
    state.theme = value
    storage.set("settings.theme", value)
    state.message = f"主题已保存: {value}"


def set_notifications(value):
    state.notifications = value
    storage.set_bool("settings.notifications", value)
    state.message = "通知开关已保存" if value else "通知已关闭"


def reset_settings():
    for key in storage.all_keys(prefix="settings."):
        storage.remove(key)
    state.batch_update(
        theme="跟随系统",
        notifications=True,
        message="已重置 settings.* 下的所有键",
    )


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("偏好", [
                appui.Picker(
                    "主题",
                    selection=state.theme,
                    options=THEME_OPTIONS,
                    on_change=set_theme,
                ).picker_style("segmented"),
                appui.Toggle(
                    "允许通知",
                    is_on=state.notifications,
                    on_change=set_notifications,
                ),
            ]),
            appui.Section("维护", [
                appui.Button("重置设置", action=reset_settings, role="destructive"),
                appui.Text(state.message).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("设置")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`get(key, default)` / `set(key, value)`	字符串读写
`get_bool` / `set_bool`	布尔读写
`get_int` / `set_int`	整数读写
`get_float` / `set_float`	浮点数读写
`get_json` / `set_json`	JSON 对象读写
`has_key(key)`	判断键是否存在
`remove(key)`	删除一个键
`all_keys(prefix="")`	列出键，可按前缀筛选

#基础读写

python

import storage

storage.set("settings.theme", "dark")
theme = storage.get("settings.theme", "system")

storage.set_bool("settings.done", True)
done = storage.get_bool("settings.done", False)

storage.set_int("counter", 3)
storage.set_float("volume", 0.8)

API	返回	说明
`get(key, default=None)`	`str` 或 `default`	键不存在时返回 `default`
`set(key, value)`	`None`	写入字符串或可转字符串的值
`get_int` / `set_int`	`int` / `None`	计数、索引、步进值
`get_float` / `set_float`	`float` / `None`	比例、阈值、音量
`get_bool` / `set_bool`	`bool` / `None`	开关状态

注意：读取时总是传 default，让首次运行和清空后仍能正常工作。

#JSON

get_json(key, default=None) / set_json(key, value) — 存取 JSON 可序列化对象。

python

storage.set_json("filters", {"status": "open", "sort": "date"})
filters = storage.get_json("filters", {})

保持 JSON 小而稳定；大列表、图片、日志请改用 database 或文件。

#键管理

has_key(key) — 判断键是否存在（兼容旧版未隔离的键名）。

remove(key) — 删除键；会同时尝试删除当前命名空间和旧格式键。

all_keys(prefix="") — 列出键，传前缀可清理一组设置：

python

for key in storage.all_keys(prefix="settings."):
    storage.remove(key)

MiniApp 内 all_keys 返回的是去掉应用前缀后的逻辑键名，便于脚本按 settings.* 管理。

#常见错误

错误写法	后果	修正
把 token 放进 `storage`	敏感数据不安全	使用 keychain
多个脚本共用 `theme` 短键	键名互相覆盖	使用 `settings.theme` 命名空间
读取不传 `default`	首次运行显示 `None`	`storage.get("key", default)`
大列表 / 图片塞进 JSON	慢、占空间	改用 database 或文件

#相关文档

文档	用途
keychain	安全存储 token / 密码
database	可查询列表与离线缓存
device	读取设备与环境信息
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。