ArkUI List 拖动排序最佳实践

在 ArkUI 中实现列表拖动排序，主要依赖 List 组件的 onMove 回调。结合 @Local 的响应式更新，几行代码就能实现功能。

数据层

@Local imageUris: Array<string> = [];

渲染层

List() {
  ForEach(this.imageUris, (uri: string, index: number) => {
    ListItem() {
      Stack() {
        Image(uri)
          .width('100%')
          .height(150)
          .objectFit(ImageFit.Cover)
          .borderRadius(10)

        Stack()
          .width('100%')
          .height(150)
      }
    }
    .margin(10)
    .borderRadius(10)
    .backgroundColor('#FFFFFFFF')
  }, (uri: string) => uri)
    .onMove((from: number, to: number) => {
      let tmp = this.imageUris.splice(from, 1);
      this.imageUris.splice(to, 0, tmp[0]);
    })
}

onMove 回调

onMove 是整个拖动排序的核心。当手指长按某个 ListItem 并拖动到新位置时，系统会触发这个回调，并传入两个索引：被拖动项的原位置 from，和目标位置 to。

这里的实现利用了数组的 splice 方法两步走：

1. splice(from, 1) — 从原位置切出被拖动的元素
2. splice(to, 0, ...) — 将其插入到目标位置

由于数组引用没有变化（splice 是 in-place 操作），@Local 的响应式驱动需要依赖 ArkUI 的代理对象机制。在 ForEach 中使用稳定的 key 配合 splice 操作，框架能正确追踪数组变化并触发最小粒度的 UI 更新。

如果需要保留排序结果到持久化存储，比如 UserInfo 或数据库，可以在 onMove 回调末尾追加对应的保存逻辑。

图片选择

配合系统 PhotoViewPicker，最多选 20 张：

async selectImages(): Promise<void> {
  const photoPicker = new photoAccessHelper.PhotoViewPicker();
  const photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 20;

  const photoSelectResult = await photoPicker.select(photoSelectOptions);
  if (photoSelectResult?.photoUris?.length > 0) {
    this.imageUris = [...this.imageUris, ...photoSelectResult.photoUris];
  }
}

组件层级

List (onMove 接收拖动事件)
├── ListItem (长按触发拖动)
│   └── Stack (布局容器)
│       ├── Image (图片展示)
│       └── Stack (透明覆盖层，透传手势)
└── ListItem ...

注意事项

• 透明覆盖层 — 当 ListItem 内只包含 Image 时，Image 组件会优先处理手势，导致 onMove 无法触发。在 Image 上方添加一个透明 Stack 铺满父容器尺寸，将手势透传给 ListItem。Stack 默认裁剪超出内容，圆角设置不受影响。
• ForEach 需要稳定的 key — 使用 (uri: string) => uri 作为唯一标识，避免排序时列表项渲染错乱。

鸿蒙开发干货——手把手教你玩转HDS沉浸光感效果

大家好，我是青蓝逐码的云杰。

最近有不少用户在交流时间到，应用底部 Tab 栏那种高级的“发光”和“沉浸”质感是怎么做出来的？

在鸿蒙应用开发中，细腻的光影和材质表现确实是提升 UI 质感、打造沉浸式体验的关键一环。无论是底部 Tab 栏的毛玻璃光感，还是顶部导航栏的高级光效，掌握系统级材质能力都能让你的应用瞬间“高大上”。本文将带你解锁鸿蒙开发中 HDS（HarmonyOS Design System）沉浸光感材质 的全流程技巧，附完整代码示例和降级适配指南，让你的应用轻松玩转高级光影效果。

一、沉浸光感是什么？

从 HarmonyOS 6.1.0(23) 版本开始，@kit.UIDesignKit 为 HDS 组件引入了强大的 systemMaterialEffect（系统材质效果）能力。其中最吸引人的就是沉浸光感（IMMERSIVE）。

与传统的纯色或简单的毛玻璃不同，沉浸光感会在组件内部模拟真实的物理光照模型。当你点击或与之交互时，会产生细腻的“光晕”和“反射”反馈，极大地增强了控件的立体感和触控反馈的真实度。

先来看看最终的实现效果：

目前，这套能力主要应用于两大核心组件：

1. HdsNavigation：可为标题栏（TitleBar）设置沉浸光感。
2. HdsTabs：可为底部的悬浮页签（TabBar）设置沉浸光感。

二、实战演练：为底部悬浮页签添加沉浸光感

接下来，我们以底部的 HdsTabs 为例，一步步实现沉浸光感效果。

1. 基础配置与准备

首先，确保你的工程引入了 UIDesignKit 相关的模块。我们需要 HdsTabs、HdsTabsController 以及 hdsMaterial。

import { hdsMaterial, HdsTabs, HdsTabsController } from "@kit.UIDesignKit";
import { SymbolGlyphModifier } from "@kit.ArkUI";

同时，我们定义好 Tab 栏的菜单配置（使用系统 Symbol 图标，支持多色渲染）：

interface MenuItem {
  symbolGlyph: SymbolGlyphModifier;
  symbolGlyph1: SymbolGlyphModifier;
  label: string;
}

const MENU_CONFIG: MenuItem[] = [
  {
    symbolGlyph: new SymbolGlyphModifier($r("sys.symbol.clock"))
      .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
      .fontColor([
        $r("sys.color.ohos_id_color_bottom_tab_icon_off"),
        $r("sys.color.ohos_id_color_bottom_tab_icon_auxcolor_off02"),
      ]),
    symbolGlyph1: new SymbolGlyphModifier($r("sys.symbol.clock_fill"))
      .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
      .fontColor([
        $r("app.color.primary_blue"),
        $r("sys.color.ohos_id_color_primary_contrary"),
      ]),
    label: "待取",
  },
  // ... 其他 Tab 项配置
];

2. 核心方案一：使用系统自适应沉浸光感（官方推荐）

在绝大多数场景下，我们推荐使用 ADAPTIVE（自适应）模式。系统会根据当前设备的算力和性能状态，自动为你选择最佳的光效表现，保证流畅度的同时达到最优的视觉效果。

@Entry
@Component
struct Index {
  private hdsTabsController: HdsTabsController = new HdsTabsController();

  build() {
    HdsTabs({ controller: this.hdsTabsController }) {
      ForEach(MENU_CONFIG, (item: MenuItem, index: number) => {
        TabContent() {
          // 这里放你的页面内容，比如 PackagesPage()
        }
        .tabBar(new BottomTabBarStyle({
          normal: item.symbolGlyph,
          selected: item.symbolGlyph1
        }, item.label).labelStyle({
          selectedColor: $r('app.color.primary_blue') // 设置文字高亮色
        }))
      })
    }
    .barOverlap(true) // 允许内容延伸到 Tab 栏底部
    .barPosition(BarPosition.End)
    // 核心配置：开启悬浮样式并设置自适应材质
    .barFloatingStyle({
      barBottomMargin: 28,
      systemMaterialEffect: {
        materialType: hdsMaterial.MaterialType.ADAPTIVE,
        materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE
      }
    })
  }
}

在这段代码中，最核心的就是 barFloatingStyle 里的 systemMaterialEffect 属性。我们将类型和级别都交给了系统 ADAPTIVE 去决策。

3. 核心方案二：强制自定义沉浸光感效果与降级处理

如果你对视觉有极高的要求，希望在支持的设备上强制开启最顶级的沉浸光效（例如点击时出现明显的“白光”反馈），你可以手动指定材质类型和级别。

避坑指南：并不是所有设备都支持高级的沉浸光感（IMMERSIVE）。如果强行在低端设备上开启，可能会导致严重的卡顿和发热。因此，必须先通过 API 查询设备能力，再进行优雅降级。

import { hdsMaterial, HdsTabs, HdsTabsController } from '@kit.UIDesignKit';

@Entry
@Component
struct Index {
  private hdsTabsController: HdsTabsController = new HdsTabsController();
  // 默认我们想用最精致的效果
  @State customMaterialLevel: hdsMaterial.MaterialLevel = hdsMaterial.MaterialLevel.EXQUISITE;
  @State customMaterialType: hdsMaterial.MaterialType = hdsMaterial.MaterialType.IMMERSIVE;

  aboutToAppear(): void {
    // 1. 查询当前设备支持的系统材质类型
    let materialTypes: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();

    // 2. 检查是否支持 IMMERSIVE (沉浸光感)
    if (materialTypes.indexOf(hdsMaterial.MaterialType.IMMERSIVE) < 0) {
      // 3. 如果不支持，进行降级处理，使用基础的背景模糊平滑效果
      this.customMaterialType = hdsMaterial.MaterialType.BACKGROUND_BLUR;
      this.customMaterialLevel = hdsMaterial.MaterialLevel.SMOOTH;
    }
  }

  build() {
    HdsTabs({ controller: this.hdsTabsController }) {
      // ... TabContent 配置与之前相同
    }
    .barFloatingStyle({
      barBottomMargin: 28,
      systemMaterialEffect: {
        materialType: this.customMaterialType, // 应用查询后的类型
        materialLevel: this.customMaterialLevel // 应用查询后的级别
      }
    })
  }
}

关于材质级别的选择：

• EXQUISITE (精致)：光影反馈最强烈、最细腻（比如点击时有明显点光源照射的高亮白光），但对性能要求最高。
• GENTLE (柔和)：光影反馈相对柔和内敛。
• SMOOTH (平滑)：性能开销最低，通常用于不支持复杂光照的降级场景。

三、总结

通过上述两种方案，我们可以非常轻松地为鸿蒙应用接入极具高级感的 HDS 沉浸光感材质。

• 追求稳定和省心：无脑选择 ADAPTIVE。
• 追求极致视觉体验：使用 IMMERSIVE + EXQUISITE，但切记一定要做设备能力查询和降级处理（hdsMaterial.getSystemMaterialTypes()），这是保证用户体验底线的关键。

同时，别忘了结合 deviceInfo.sdkApiVersion >= 23 来做好旧版本系统的兼容。

掌握了这些，你的应用 UI 质感绝对能上一个大台阶。赶紧去代码里试试吧！如果有任何疑问，欢迎在评论区交流。

系列导航：

• (1) 环境开荒
• (2) 驯服 SDK ← 你在这里
• (3) 项目搬家
• (4) 保命急救箱

我第一次让 FVM 管理鸿蒙版 Flutter SDK 时，前后踩了 4 个坑，花了大半天才跑通。事后复盘发现，每个坑都不难，只是没人提前告诉我"为什么要这样做"。这篇把整个过程拆成 5 关，每关讲清「为什么」和「怎么做」，争取让你 20 分钟一次通关。

前置条件：请先完成第一篇的全部内容——DevEco Studio 已安装，ohpm、node、hvigorw 在终端里都能正常调用。

---

🗺️ 通关路线图

关卡	任务	预计耗时
第1关	安装 FVM	2 min
第2关	克隆鸿蒙版 SDK	5 min（取决于网速）
第3关	修复版本"身份证"	3 min
第4关	指定鸿蒙 SDK 路径	1 min
第5关	全绿验证	2 min

---

🎯 第 1 关：安装 FVM

目标

让终端认识 fvm 命令。

为什么需要 FVM

一句话——让不同项目用不同版本的 Flutter，互不干扰。比如项目 A 用官方 3.24 跑 Android/iOS，项目 B 用鸿蒙版 3.35.8。FVM 就是 Flutter 的"版本档案柜"，每个抽屉放一个版本。

📋 操作

# macOS（在终端里执行，这是用 Homebrew 包管理器安装 FVM）
brew install fvm

# Windows（在 cmd 或 PowerShell 中执行，这是用 Chocolatey 包管理器安装 FVM）
choco install fvm

安装完后，配置 FVM 缓存路径。把以下两行写入 ~/.zshrc（上一篇介绍过，这是 Mac 终端的配置文件）：

# FVM 存放所有 Flutter 版本的目录
export FVM_CACHE_PATH=$HOME/fvm
# 让 FVM 的默认版本可以直接用 flutter 命令调用
export PATH="$HOME/fvm/default/bin:$PATH"

保存后执行下面这条命令，让刚才的配置立即生效（否则要关掉终端重新打开）：

source ~/.zshrc

✅ 验证

# 查看 FVM 版本号，确认安装成功
fvm --version

看到版本号（如 3.1.4）就过关了。

⚠️ 如果报 command not found：Mac 用户确认已安装 Homebrew（执行 brew --version 看有没有输出）；Windows 用户确认已安装 Chocolatey（执行 choco --version）。如果包管理器本身都没装，请先去官网安装。

---

🎯 第 2 关：克隆鸿蒙版 SDK

目标

把华为的鸿蒙版 Flutter 放进 FVM 管辖。

为什么不能直接 fvm install

正常装 Flutter 只需要 fvm install 3.24.0，FVM 会自动去 GitHub 下载。但鸿蒙版是华为团队在 AtomGit（国内代码托管平台）上单独维护的，FVM 的世界里它根本不存在。所以我们要"手动入库"——自己下载代码，放到 FVM 的档案柜里，假装它一直在那。

⚠️ 本关最大的坑：分支名和版本号是两回事！

仓库的分支叫 oh-3.35.7-dev，看到 3.35.7 你会以为版本就是 3.35.7。但实际上代码里的版本已经迭代到了 3.35.8-ohos-0.0.2。

类比：Git 分支叫 feature/login-v1，但代码早就改到 v3 了。分支名是创建时起的，不会跟着版本号自动更新。

千万别拿分支名当版本号用，团队必须统一用 3.35.8-ohos-0.0.2 这个真实版本号。

📋 操作

# --depth 1 只取最新代码，省空间（省去几个 GB 的历史记录）
git clone -b oh-3.35.7-dev --depth 1 
https://atomgit.com/openharmony-tpc/flutter_flutter.git 
~/fvm/versions/3.35.8-ohos-0.0.2

注意看：clone 命令里分支名是 oh-3.35.7-dev，但目标文件夹名是 3.35.8-ohos-0.0.2——这不是写错了，上面已经解释了为什么不一样。

💡 怎么确认真实版本号？ clone 完后执行 ~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter --version 看输出。如果加入已有团队，直接看项目的 .fvmrc 文件（命令：cat .fvmrc）。

✅ 验证

# 确认文件下载成功（ls = 列出目录内容）
ls ~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter

文件存在就过关。

⚠️ 如果报 No such file or directory：回去检查 clone 命令是否执行成功。常见原因是网络超时（AtomGit 在国内，通常不需要梯子，但公司内网可能有限制）。重新执行 clone 前，先删掉残留目录：rm -rf ~/fvm/versions/3.35.8-ohos-0.0.2，再重试。

---

🎯 第 3 关：修复版本"身份证"

目标

让 FVM 正确识别这个 SDK 的版本号。

为什么要做这步

clone 下来的 SDK 有两张"证件"：

1. version 文件——相当于身份证，一行文本写着版本号
2. bin/cache/flutter.version.json——相当于内部档案，JSON 格式的详细版本信息

问题是，这两张证件上都写着 0.0.0-unknown（因为鸿蒙团队是从开发分支构建的，没有打标准标签）。但我们的文件夹名叫 3.35.8-ohos-0.0.2。FVM 一查——名字对不上，直接翻脸。

⚠️ 不做这步的后果：FVM 会弹出 "Version mismatch" 并试图删掉你的 SDK 重装。如果看到了这个弹窗，千万不要选任何选项，按 Ctrl+C（Mac 也是 Ctrl 不是 Cmd）退出，回来做这步。

📋 操作

macOS / Linux：

cd ~/fvm/versions/3.35.8-ohos-0.0.2

# 第一步：改"身份证"
echo -n "3.35.8-ohos-0.0.2" > version

# 第二步：初始化 Flutter 引擎（首次运行会下载 Dart SDK，需要等 1-3 分钟）
bin/flutter --version

# 第三步：改"内部档案"（把所有 0.0.0-unknown 替换成正确的版本号）
sed -i '' 's/0.0.0-unknown/3.35.8-ohos-0.0.2/g' bin/cache/flutter.version.json

Windows PowerShell：

# 进入 SDK 所在目录
cd $env:USERPROFILE\fvm\versions\3.35.8-ohos-0.0.2

# 第一步：改"身份证"
"3.35.8-ohos-0.0.2" | Set-Content version -NoNewline

# 第二步：初始化引擎
bin\flutter --version

# 第三步：改"内部档案"（PowerShell 的查找替换写法）
(Get-Content bin\cache\flutter.version.json) -replace '0.0.0-unknown', '3.35.8-ohos-0.0.2' | Set-Content bin\cache\flutter.version.json

⚠️ 三步的顺序不能乱——第二步会生成 flutter.version.json 文件，第三步才有东西可改。如果你先执行了第三步，会报文件不存在。

✅ 验证

# 回到任意目录都可以执行（fvm list = 列出 FVM 管理的所有 Flutter 版本）
fvm list

看到 Version 列显示 3.35.8-ohos-0.0.2（不是空白、不是 Need setup、不是 0.0.0-unknown），这关就过了。

⚠️ 如果还是显示异常，逐一排查两张"证件"：

# 检查"身份证"内容
cat ~/fvm/versions/3.35.8-ohos-0.0.2/version
# 应该输出：3.35.8-ohos-0.0.2（没有多余空行）

# 检查"内部档案"有没有残留的 0.0.0-unknown
cat ~/fvm/versions/3.35.8-ohos-0.0.2/bin/cache/flutter.version.json
# 里面所有 version 字段应该都是 3.35.8-ohos-0.0.2

如果 version 文件内容不对，重新执行第一步；如果 JSON 里还有 0.0.0-unknown，重新执行第三步。

---

🎯 第 4 关：指定鸿蒙 SDK 路径

目标

让 Flutter 知道鸿蒙的 SDK（OpenHarmony SDK）装在哪。

为什么不用环境变量

我试过 HOS_SDK_HOME、OHOS_SDK_HOME 等环境变量，时灵时不灵。原因是不同方式打开的终端（VS Code 内置终端 vs 系统终端 vs CI 环境）加载配置文件的顺序不一样，变量可能没被读到。flutter config 会把路径写入 Flutter 自己的配置文件，不管从哪里启动都能读到，最稳。

📋 操作

# 把鸿蒙 SDK 的位置"写死"到 Flutter 的配置里（一次性操作）
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter config \
--ohos-sdk="/Applications/DevEco-Studio.app/Contents/sdk"

⚠️ Windows 用户路径改为：--ohos-sdk="C:\Program Files\Huawei\DevEco Studio\sdk"

请根据 DevEco Studio 实际安装路径调整。不确定装在哪？打开 DevEco Studio → Settings → SDK 页面可以看到路径。

终端输出 Setting "ohos-sdk" value to "..." 就成功了。

✅ 验证

不急，下一关一起验收。

---

🎯 第 5 关：全绿验证

目标

flutter doctor 中 HarmonyOS toolchain 一栏显示绿色对勾。

📋 操作

# 运行 Flutter 的环境诊断工具（-v 表示显示详细信息）
~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter doctor -v

✅ 验证

关注输出中的 HarmonyOS 那一栏：

[✓] HarmonyOS toolchain - develop for HarmonyOS devices
    • OpenHarmony Sdk at /Applications/DevEco-Studio.app/Contents/sdk,
      available api versions has [22:default]
    • Ohpm version 6.0.1
    • Node version v18.20.1
    • Hvigorw binary at .../hvigor/bin/hvigorw

看到 [✓] 加上 4 个子项都有值 = 通关！

💡 你可能会看到 Flutter 那栏有几个 ! 警告（channel 不标准、upstream 不是官方地址）。这是鸿蒙版的正常现象，完全不影响开发和打包，放心忽略。

⚠️ 如果 HarmonyOS 那栏还是红叉，按优先级排查：

1. SDK not found → 回第 4 关检查 config 路径是否正确
2. ohpm/hvigorw missing → 回第一篇检查环境变量
3. Version mismatch → 回第 3 关检查两张"证件"

---

🔧 附加关：FVM 的"碎碎念"

通关后你会发现，每次用 fvm flutter xxx 时 FVM 都会弹 "not a valid version" 的警告让你确认。这不是报错，只是 FVM 在说："这个版本号我在官方列表里查不到，你确定要用吗？"

三种应对方式：

1. 手动按 y——每次弹出输入 y 回车
2. 自动确认——命令前加 yes |：

yes | fvm flutter doctor

3. 绕过 FVM——直接用绝对路径调用，完全不弹警告：

~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter doctor

我推荐第三种，路径虽长但最省心。可以设个快捷方式（alias）缩短它：

# 把这行加到 ~/.zshrc 里（alias = 给一条长命令起个短名字）
alias hflutter="$HOME/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter"

保存后 source ~/.zshrc，之后直接 hflutter run、hflutter doctor 就行。

---

🏆 通关总结

项目	状态
FVM	✅ 已安装
鸿蒙版 Flutter SDK	✅ ~/fvm/versions/3.35.8-ohos-0.0.2
version 文件	✅ 已修复
flutter.version.json	✅ 已修复
flutter config --ohos-sdk	✅ 已配置
flutter doctor HarmonyOS	✅ 全绿

回顾核心逻辑：FVM 只管官方 Flutter，鸿蒙版要我们手动塞进去（第 2 关）；塞进去后"证件"信息对不上，需要手动修正（第 3 关）；最后告诉 Flutter 鸿蒙 SDK 在哪（第 4 关）。理解了这条线，以后鸿蒙版 SDK 升级换版本号，你也能照样搞定。

如果中途卡住，大概率是版本号写错了——检查文件夹名、version 文件内容、flutter.version.json 里的版本号，三者必须完全一致。

---

下一篇预告：SDK 准备好了，接下来要把你的老 Flutter 项目跑到鸿蒙上——听起来就是敲几行命令的事？没那么简单。→ 【Flutter×鸿蒙】通关手册（三）：debug 包也要签名，这点和 Android 差远了