开头

设置页看起来简单，但它包含很多基础交互：开关、勾选、滑动调节、确认弹窗。把这些控件练熟，后面做个人中心、偏好设置、隐私设置都会顺手。

这一篇我们做一个“阅读设置页”：开启深色模式、勾选自动保存、调节字号，点击按钮弹出确认框。

本篇目标

• 会用 Toggle 表示开关状态。
• 会用 Checkbox 表示是否选择。
• 会用 Slider 调节数值。
• 会用 AlertDialog 做确认弹窗。

示例代码

@Entry
@Component
struct ReaderSettingsPage {
  @State darkMode: boolean = false;
  @State autoSave: boolean = true;
  @State fontSize: number = 18;
  @State message: string = '当前设置还没有保存';

  private saveSettings() {
    AlertDialog.show({
      title: '保存设置',
      message: `深色模式：${this.darkMode ? '开启' : '关闭'}\n自动保存：${this.autoSave ? '开启' : '关闭'}\n字号：${this.fontSize}`,
      primaryButton: {
        value: '确定',
        action: () => {
          this.message = '设置已保存';
        }
      },
      secondaryButton: {
        value: '取消',
        action: () => {
          this.message = '取消保存';
        }
      }
    });
  }

  build() {
    Column({ space: 18 }) {
      Text('阅读设置')
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .width('100%')

      Row() {
        Text('深色模式')
          .fontSize(16)
          .layoutWeight(1)

        Toggle({ type: ToggleType.Switch, isOn: this.darkMode })
          .onChange((isOn: boolean) => {
            this.darkMode = isOn;
          })
      }
      .width('100%')
      .height(48)

      Row() {
        Text('自动保存草稿')
          .fontSize(16)
          .layoutWeight(1)

        Checkbox()
          .select(this.autoSave)
          .onChange((value: boolean) => {
            this.autoSave = value;
          })
      }
      .width('100%')
      .height(48)

      Column({ space: 8 }) {
        Row() {
          Text('文章字号')
            .fontSize(16)
            .layoutWeight(1)

          Text(`${Math.round(this.fontSize)}`)
            .fontSize(16)
            .fontColor('#666666')
        }
        .width('100%')

        Slider({
          value: this.fontSize,
          min: 14,
          max: 28,
          step: 1
        })
          .onChange((value: number) => {
            this.fontSize = value;
          })
      }
      .width('100%')

      Text('预览文字：这是一段阅读效果预览。')
        .fontSize(this.fontSize)
        .fontColor(this.darkMode ? '#F5F5F5' : '#222222')
        .backgroundColor(this.darkMode ? '#222222' : '#F7F7F7')
        .borderRadius(8)
        .padding(12)
        .width('100%')

      Text(this.message)
        .fontSize(14)
        .fontColor('#666666')
        .width('100%')

      Button('保存设置')
        .width('100%')
        .height(48)
        .onClick(() => {
          this.saveSettings();
        })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

小白看懂代码

Toggle 适合表示“开/关”。比如深色模式、消息通知、是否允许定位。

Checkbox 适合表示“选中/未选中”。如果页面里有多个独立选项，用它很合适。

Slider 适合调节数值。字号、音量、亮度、进度，都可以用类似方式实现。

AlertDialog.show() 会弹出对话框。这里点击“保存设置”后，把当前状态拼成提示内容，再由用户确认。

选择控件怎么判断用哪个

如果只有两个状态，而且更像“功能开关”，用 Toggle。

如果是表单中的勾选项，用 Checkbox。

如果是多个选项中只能选一个，可以继续学习 Radio。

如果是从一段范围里选数值，用 Slider。

新手常见错误

第一种错误：控件显示值和状态没有绑定。

比如开关写死：

Toggle({ type: ToggleType.Switch, isOn: false })

这样你后续不好根据状态控制界面。更好的方式是绑定状态：

Toggle({ type: ToggleType.Switch, isOn: this.darkMode })

第二种错误：滑块返回的是数字，但展示时不处理小数。

如果你设置了 step: 1，一般展示时可以用：

Math.round(this.fontSize)

第三种错误：弹窗里写太多逻辑。

弹窗更适合做确认，真正复杂的保存逻辑应该放到单独方法里。

本篇小结

设置页是练习基础控件的好地方。Toggle 管开关，Checkbox 管勾选，Slider 管范围数值，AlertDialog 管确认反馈。等这些交互熟悉后，你就能做出很多真实应用页面。

附录：项目设置与构建问题记录

一、项目设置

本篇配套一个独立 ArkTS 示例 App，用于运行页面和截图：

建议用 DevEco Studio 打开项目后运行 entry 模块。项目定位是截图练习 Demo，不依赖后端服务，也不需要额外权限。

建议新建或检查工程时保持以下设置：

• Project type：Application。
• Template：Empty Ability。
• Language：ArkTS。
• Model：Stage。
• Device：Phone，可按需要兼容 Tablet、2in1。
• Runtime OS：HarmonyOS。
  
  

二、SDK 版本

本文主题面向 HarmonyOS ArkTS API 24+。本次示例工程根目录 build-profile.json5 使用如下配置：

{
  "compatibleSdkVersion": "6.1.1(24)",
  "targetSdkVersion": "6.1.1(24)",
  "runtimeOS": "HarmonyOS"
}

如果本机 DevEco Studio SDK Manager 中安装的版本不同，请按本机实际 API 24+ SDK 调整 compatibleSdkVersion 和 targetSdkVersion。

三、项目目录说明

核心目录如下：

HarmonyOS_ArkTS_API24_ControlsScreenshotApp/
├── AppScope/
│   ├── app.json5
│   └── resources/
├── entry/
│   ├── src/main/ets/entryability/EntryAbility.ets
│   ├── src/main/ets/pages/
│   ├── src/main/resources/base/profile/main_pages.json
│   ├── build-profile.json5
│   └── oh-package.json5
├── build-profile.json5
├── hvigorfile.ts
└── oh-package.json5

页面文件都在：

entry/src/main/ets/pages/

路由注册文件在：

entry/src/main/resources/base/profile/main_pages.json

五、创建项目过程

1. 打开 DevEco Studio。
2. 点击 Create Project。
3. 选择 Application。
4. 模板选择 Empty Ability。
5. 开发语言选择 ArkTS。
6. 模型选择 Stage。
7. 设置项目名称，例如 ArkTSControlsDemo。
8. 选择保存路径，建议路径只包含英文、数字、下划线或连字符。
9. 选择 API 24+ 对应 SDK。
10. 点击 Finish，等待工程创建完成。
11. 打开 entry/src/main/ets/pages/Index.ets。
12. 运行默认工程，确认模拟器或真机能打开。
13. 再逐个添加本文中的页面代码并截图。

六、本次编译安装遇到的问题与解决办法

1. 中文路径导致 Hvigor 拒绝构建

问题现象：

Invalid project path. Current path does not match: D:\私人资料\CSDN\HarmonyOS_ArkTS_API24_ControlsScreenshotApp

原因：Hvigor 对工程路径有限制，路径只能包含英文字母、数字、连字符、下划线、英文句点、英文括号、空格或 @。

处理办法：把项目复制到 ASCII 路径后构建：

D:\\HarmonyOS_ArkTS_API24_ControlsScreenshotApp

2. DEVECO_SDK_HOME 环境变量无效

问题现象：

Invalid value of 'DEVECO_SDK_HOME' in the system environment path.

处理办法：在当前命令会话中临时指定 DevEco SDK 根目录：

$env:DEVECO_SDK_HOME='D:\Program Files\Huawei\DevEco Studio Beta\sdk'

3. hvigor-config.json5 缺少 dependencies

问题现象：

Schema validate failed ... missingProperty: 'dependencies'

处理办法：补齐 hvigor/hvigor-config.json5：

{
  "modelVersion": "5.0.0",
  "dependencies": {
  }
}

4. 打包阶段找不到 Java

问题现象：

spawn java ENOENT

处理办法：使用 DevEco Studio 自带 JBR，并停止旧的 Hvigor daemon 后重新构建：

$env:JAVA_HOME='D:\Program Files\Huawei\DevEco Studio Beta\jbr'
$env:Path="D:\Program Files\Huawei\DevEco Studio Beta\jbr\bin;$env:Path"
hvigorw --stop-daemon

5. 构建成功但有弃用警告

构建时出现过 router.pushUrl、router.back、AlertDialog.show 的弃用警告，但不影响本次截图 Demo 编译和安装。正式项目建议后续按当前 API 推荐方式替换。

七、本次安装启动记录

构建命令：

hvigorw --mode module -p module=entry@default -p product=default assembleHap

安装命令：

hdc install entry-default-unsigned.hap

启动命令：

hdc shell aa start -a EntryAbility -b com.csdn.arkts.controls.screenshot

验证结果：

• HAP 构建成功。
• 模拟器目标：127.0.0.1:5555。
• 安装结果：install bundle successfully。
• 启动结果：start ability successfully。