鸿蒙 ArkTS 入门实战：状态装饰器、弹窗、路由全解析

乙676

17人浏览 · 2026-07-01 15:06:35

乙676 · 2026-07-01 15:06:35 发布

前言

在鸿蒙应用开发中，@State状态管理、AlertDialog弹窗、Router页面路由是实现交互与多页面跳转的三大核心基础。本文将结合你之前学习的代码，用通俗易懂的方式，把这三个知识点串联起来，附完整示例与踩坑指南，适合新手直接上手写进博客。

一、`@State`：组件状态管理的 “核心开关”

1. 基础概念

@State是 ArkTS 中最基础的状态装饰器，用于声明组件内部的响应式变量。当被@State修饰的变量发生变化时，UI 会自动更新，无需手动刷新。

核心规则：

只能在组件内部声明，不能在全局或普通函数中使用
变量值改变时，会触发组件重新渲染
常用于存储用户输入（如账号、密码）、开关状态、列表数据等

2. 代码示例（登录页用户输入）

@Entry
@Component
struct RegisterPage {
  // 用@State声明响应式变量，存储用户输入的账号密码
  @State username: string = "";
  @State pwd: string = "";

  build() {
    Column() {
      // 用户名输入框，绑定@State变量
      TextInput({ placeholder: "请输入用户名" })
        .width("80%")
        .onChange((value: string) => {
          this.username = value; // 输入变化时自动更新状态
        })

      // 密码输入框，绑定@State变量
      TextInput({ placeholder: "请输入密码" })
        .width("80%")
        .type(InputType.Password)
        .onChange((value: string) => {
          this.pwd = value;
        })
    }
  }
}

3. 关键使用场景

表单输入绑定：如账号、密码、手机号等输入框
按钮状态切换：如登录按钮 “禁用 / 启用”、开关组件
列表数据更新：如点击按钮添加 / 删除列表项

二、AlertDialog：用户交互的 “提示窗口”

1. 基础概念

AlertDialog是鸿蒙提供的系统级警告弹窗，用于向用户展示提示信息、确认操作或获取反馈。它会中断当前流程，强制用户交互，适合注册成功、操作失败、删除确认等场景。

2. 核心 API 与常用配置

// 基础用法：无按钮提示弹窗
AlertDialog.show({
  title: "注册账号成功", // 弹窗标题（必填）
  message: "请到登录页登录", // 弹窗正文（必填）
  confirm: { // 确认按钮配置
    text: "确定",
    onClick: () => {
      console.log("用户点击了确定按钮");
    }
  }
});

完整配置项说明：

表格

配置项	作用	示例
`title`	弹窗标题	`"注册成功"`
`message`	弹窗内容	`"请前往登录页"`
`confirm`	确认按钮	`{text: "确定", onClick: ()=>{}}`
`cancel`	取消按钮	`{text: "取消", onClick: ()=>{}}`
`alignment`	弹窗位置	`DialogAlignment.Center`（默认居中）

3. 实战场景：注册成功弹窗 + 跳转登录页

Button("注册账号")
  .width("80%")
  .onClick(() => {
    // 1. 先打印用户输入，调试用
    console.log("输入用户名：", this.username, "输入密码：", this.pwd);

    // 2. 弹出注册成功提示
    AlertDialog.show({
      title: "注册账号成功",
      message: "请到登录页登录",
      confirm: {
        text: "确定",
        onClick: () => {
          // 3. 用户点击确定后，跳转到登录页并传递账号密码
          router.pushUrl({
            url: "pages/LoginPage",
            params: {
              username: this.username,
              pwd: this.pwd
            }
          });
        }
      }
    });
  })

4. 注意事项

弹窗默认居中显示，可通过alignment调整位置
路由跳转前必须关闭弹窗，否则会在新页面继续显示
复杂交互场景可使用CustomDialog自定义弹窗

三、Router：页面跳转与数据传递的 “桥梁”

1. 基础概念

@ohos.router模块是鸿蒙实现多页面跳转的核心 API，支持页面间跳转、返回、数据传递，是构建多页面应用的基础。

2. 核心 API 详解

（1）`router.pushUrl()`：压入式跳转（可返回）

将目标页面压入路由栈，用户可通过返回键回到上一页，适合 “注册→登录”“列表→详情” 这类场景。

// 注册页跳转到登录页，并传递参数
router.pushUrl({
  url: "pages/LoginPage", // 目标页面路径（需在main_pages.json中配置）
  params: { // 传递的参数，支持键值对
    username: this.username,
    pwd: this.pwd
  }
});

（2）`router.replaceUrl()`：替换式跳转（不可返回）

用目标页面替换当前页面，路由栈中不再保留原页面，适合登录成功后跳转到首页，用户无法再返回登录页。

router.replaceUrl({
  url: "pages/HomePage"
});

（3）`router.getParams()`：接收页面传递的参数

在目标页面中，通过router.getParams()获取上一个页面传递的参数，通常在onPageShow生命周期中调用。

// LoginPage.ets
onPageShow(): void {
  // 1. 获取传递的参数，并指定类型为键值对字符串
  const params = router.getParams() as Record<string, string>;
  
  // 2. 从参数中取出账号密码，自动填充到输入框
  if (params) {
    this.username = params.username;
    this.pwd = params.pwd;
  }
}

3. 完整页面跳转流程（注册→登录）

注册页（RegisterPage）：用户输入账号密码，点击注册后弹出成功弹窗，点击确定跳转到登录页并传递参数
登录页（LoginPage）：页面显示时自动接收参数，填充到输入框，用户可直接点击登录

4. 关键注意事项

目标页面路径必须在main_pages.json中配置，否则跳转失败
传递的参数默认是Object类型，建议用as Record<string, string>强制类型转换，避免报错
路由跳转时，若弹窗未关闭，会随页面切换消失（API 15 + 支持页面级弹窗）

四、三大知识点联动实战：注册登录完整流程

下面是整合@State、AlertDialog、Router的注册登录页面完整代码，可直接复制到博客中：

1. 注册页（RegisterPage.ets）

import router from '@ohos.router';

@Entry
@Component
struct RegisterPage {
  // 状态变量：存储用户输入的账号密码
  @State username: string = "";
  @State pwd: string = "";

  build() {
    Column() {
      Text("注册账号")
        .fontSize(30)
        .fontWeight(FontWeight.Bolder)
        .margin({ bottom: 30 })

      // 用户名输入框
      TextInput({ placeholder: "请输入用户名" })
        .width("80%")
        .height(50)
        .borderRadius(12)
        .margin({ bottom: 20 })
        .onChange((value: string) => {
          this.username = value;
        })

      // 密码输入框
      TextInput({ placeholder: "请输入密码" })
        .width("80%")
        .height(50)
        .borderRadius(12)
        .type(InputType.Password)
        .margin({ bottom: 40 })
        .onChange((value: string) => {
          this.pwd = value;
        })

      // 注册按钮
      Button("注册账号")
        .width("80%")
        .height(50)
        .borderRadius(60)
        .onClick(() => {
          // 打印调试信息
          console.log("输入用户名：", this.username, "输入密码：", this.pwd);

          // 弹出注册成功弹窗
          AlertDialog.show({
            title: "注册账号成功",
            message: "请到登录页登录",
            confirm: {
              text: "确定",
              onClick: () => {
                // 跳转到登录页并传递参数
                router.pushUrl({
                  url: "pages/LoginPage",
                  params: {
                    username: this.username,
                    pwd: this.pwd
                  }
                });
              }
            }
          });
        })
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

2. 登录页（LoginPage.ets）

import router from '@ohos.router';

@Entry
@Component
struct LoginPage {
  // 状态变量：存储账号密码
  @State username: string = "";
  @State pwd: string = "";

  // 页面显示时，接收注册页传递的参数
  onPageShow(): void {
    const params = router.getParams() as Record<string, string>;
    if (params) {
      this.username = params.username;
      this.pwd = params.pwd;
    }
  }

  build() {
    Column() {
      Text("用户登录")
        .fontSize(30)
        .fontWeight(FontWeight.Bolder)
        .margin({ bottom: 30 })

      // 用户名输入框（自动填充注册页传递的账号）
      TextInput({ text: this.username, placeholder: "请输入用户名" })
        .width("80%")
        .height(50)
        .borderRadius(12)
        .margin({ bottom: 20 })
        .onChange((value: string) => {
          this.username = value;
        })

      // 密码输入框（自动填充注册页传递的密码）
      TextInput({ text: this.pwd, placeholder: "请输入密码" })
        .width("80%")
        .height(50)
        .borderRadius(12)
        .type(InputType.Password)
        .margin({ bottom: 40 })
        .onChange((value: string) => {
          this.pwd = value;
        })

      // 登录按钮
      Button("登录")
        .width("80%")
        .height(50)
        .borderRadius(60)
        .onClick(() => {
          console.log("登录账号：", this.username, "密码：", this.pwd);
          // 这里可添加登录逻辑，如跳转到首页
        })
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

五、常见踩坑指南

@State变量不更新？
- 检查变量是否被正确绑定到组件（如TextInput的onChange是否赋值）
- 确保变量声明在组件内部，而非全局
弹窗不显示？
- 检查是否在 UI 上下文外调用（如异步函数中未获取 UIContext）
- 确保title和message参数正确传入
路由跳转失败？
- 检查目标页面路径是否在main_pages.json中配置
- 确认params参数类型是否匹配，避免undefined错误
接收参数为undefined？
- 在onPageShow中调用router.getParams()，而非build()方法
- 用as Record<string, string>强制类型转换，避免类型不匹配