← 返回设置页组件参考 · 全部使用指导

设置页使用指导

把「设置页」拖进屏幕，在「设置项」属性中点「编辑设置项」，逐行添加项目，也可以点「常用设置示例」载入七种项目再修改。 不需要拼接布局，也不需要自己写本地保存积木。安卓与鸿蒙使用相同接口；联机测试需要包含本组件的新版伴侣。

快速上手

将宽度设为填满、高度设为填满，按下面的表配置。编号是代码取值和处理事件的名称，发布后尽量保持稳定。

候选项和多选默认值在单行输入框中填写，多个选项用英文逗号 , 分隔，不换行。滑块分别填写最小值、最大值和步长。

「自动保存」默认开启，「存储名称」默认 Settings。用户修改后，下次打开会恢复保存的值。 保存设置与执行业务是两步：开关值保存了，还需要在初始化和设置改变事件中连接自己的提醒、主题或播放器逻辑。

下面用一个标签显示是否允许消息提醒；标签不会自动代表系统通知权限。

when Screen1.Initialize() {
  if 设置页1.GetValue("notify", false) {
    标签1.Text = "允许消息提醒"
  } else {
    标签1.Text = "消息提醒已关闭"
  }
}

when 设置页1.SettingChanged(键, 旧值, 新值) {
  if 键 == "notify" {
    if 新值 {
      标签1.Text = "允许消息提醒"
    } else {
      标签1.Text = "消息提醒已关闭"
    }
  }
}

when 设置页1.ActionClicked(键) {
  if 键 == "clear" {
    设置页1.SetSummary("clear", "请连接你自己的缓存清理逻辑")
  }
}

「清理缓存」是操作项，只派发事件；组件不会擅自删除文件。多个操作项可用编号区分。

修改值与恢复默认

• GetValue(编号, 备用值)：开关返回真/假，滑块返回数字，单选和输入返回文本，多选返回列表。编号不存在或没有值时返回备用值。
• SetValue(编号, 值)：代码设置也按「自动保存」属性保存，但不触发「设置改变」，适合初始化或联动。
• ResetDefaults()：弹出确认，确认后恢复当前列表的默认值；实际改变的项目逐项触发「设置改变」。隐藏、禁用的项目也会恢复。
• 不同屏幕设置相同「存储名称」和编号，可共享设置值。不同名称互相独立。
• 关闭「自动保存」后只保留当前组件内存中的值，需要持久化时在「设置改变」事件自行保存。切换存储名称会重新载入对应设置。

进阶：动态配置

用「设置全部设置项」传入字典列表。每个字典可包含下列字段：

可用「添加项」添加一个字典，用「移除项目」移除界面项目。移除后保存值保留，重新加入同编号即可恢复。 配置无效时触发「错误发生」，原列表保留。候选项更新后原值不再合法时，回到当前默认值。

「设置说明」「设置项目可见」「设置项目启用」可在运行中控制项目，例如关闭消息提醒时禁用提醒方式。 这些操作修改当前界面配置，不会保存配置定义；重新启动仍从设计器或初始化积木载入项目。

使用注意

• 修改标题、说明、顺序不会改变已保存的值；修改编号相当于新设置项。
• 候选项文本就是保存值，修改候选项文本后旧值可能失效；升级前应考虑迁移。
• 滑块值会夹紧到范围内，再按步长取整；最多允许 10000 个步长。
• 「默认」文字和背景颜色跟随应用主题；也可设置颜色和字号。
• 本机保存没有加密，适用于普通偏好，不要用来保存密码或访问令牌。伴侣内测试的多个项目可能共享数据，用不同存储名称区分。
• 多选默认值和候选项都在表格中每行填写一个文本。

案例：按钮恢复默认设置

已有表格配置和自动保存案例基础上，加一个恢复按钮和状态标签。点击后回到配置的默认值；再次进入屏幕核对保存状态。

when 按钮_恢复默认.Click() {
  设置页1.ResetDefaults()
  标签1.Text = join("当前主题：", 设置页1.GetValue("theme", "自动"))
}
when 设置页1.ErrorOccurred(操作, 消息) {
  标签1.Text = join(操作, "：", 消息)
}

theme 必须与表格中设置项的编号一致。恢复默认值与删除设置项不同；不要用修改显示标题代替稳定编号。

完整 .aia 源码与操作指导

下载 .aia 源码

设备控制应用的七种常见设置可直接修改，自动保存使用本案例独立名称；初始化不会覆盖用户已经保存的昵称、主题和音量。上方设置区可独立操作，下方控制区可滚动。

导入 SettingsListAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

设备设置页

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 设备控制应用的七种常见设置可直接修改，自动保存使用本案例独立名称；初始化不会覆盖用户已经保存的昵称、主题和音量。上方设置区可独立操作，下方控制区可滚动。 覆盖检查 45/45。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。