备菜清单一划选中了隐藏项HarmonyOS 7 List 滑动多选的稳定 ID、编辑态与手势裁决实战晚饭前要一次选中“洗菜、切配、焯水”三项手指从第一行划到第三行界面却把已经筛掉的“采购香菜”也勾上了删除第二项以后原来选中的第三项又跑到了第四项。若继续用数组下标记录选择结果列表一旦过滤、排序、插入或复用视觉上的勾选和业务数据就会分家。HarmonyOS 7 对应的 API 26 为 List 增加编辑模式与手指滑动多选enableEditMode 控制编辑态onEditModeChange接收系统返回、侧滑返回或双指手势带来的状态变化editModeOptions配置默认选择样式与双指进入能力ListItem仍通过selectable、selected和onSelect承接每一项的可选性与结果同步。本文交付一套可直接迁入“中式美食”的选择模型稳定ID集合、可选资格快照、数据变化后的交集收敛、编辑态单一入口以及自定义复选框与行内操作冲突时的手势裁决。当前机器只有API 24 SDK且没有连接HDC设备下面的API 26接入代码依据当前官方文档整理本文运行的宿主断言只验证选择模型不声称完成了API 26编译、List手势识别或真机触控验证。故障根因系统选中的是列表项业务保存的却是旧下标最常见的实现是把selectedIndexes作为唯一事实源LocalselectedIndexes:number[][];privateupdateByIndex(index:number,selected:boolean):void{if(selected){this.selectedIndexes[...this.selectedIndexes,index];}else{this.selectedIndexesthis.selectedIndexes.filter(valuevalue!index);}}只要数据顺序不变这段代码看起来没有问题。真实页面却经常同时发生三种变化用户切换“只看未完成”当前可见数组被过滤。云同步插入一项更紧急的任务旧下标整体后移。完成批量操作后删除多项ListItem被LazyForEach回收并复用。此时下标只能描述某一帧的位置不能描述任务身份。选择集合必须保存item.id渲染时由ID推导selected提交时再用ID回查当前数据。官方指南也明确建议使用不会随位置变化的唯一标识记录选择结果。API 26接口先分清四层责任层API或数据只负责什么不应该承担什么ListenableEditMode是否处于编辑模式保存具体业务对象ListonEditModeChange接收系统触发的编辑态变化猜测是哪一个手势触发ListeditModeOptions默认样式、双指进入策略替代业务权限判断ListItemselectable / selected / onSelect单项资格、当前选中态和变化回调用下标充当稳定身份enableEditMode与onEditModeChange要形成闭环页面把业务状态传给enableEditMode系统又可能通过返回、侧滑返回或双指滑动改变编辑态。若只设置属性、不处理回调系统退出了编辑态顶部工具栏还可能显示“已选3项”若只在回调里改局部变量下一次重建又会被旧业务状态覆盖。LocalprivateeditMode:booleanfalse;privatesetEditMode(enabled:boolean):void{this.editModeenabled;if(!enabled){this.selectedIds[];}}List({space:8}){// ListItem...}.enableEditMode(this.editMode).onEditModeChange((enabled:boolean){this.setEditMode(enabled);}).editModeOptions({useDefaultMultiSelectStyle:true,enableTwoFingerMultiSelect:true})是否在退出编辑态时清空选择结果不是框架固定答案。批量删除通常应清空临时离开页面后恢复编辑则可能需要保留。关键是把规则写进唯一的setEditMode入口而不是让返回键、工具栏、双指手势各自改一份状态。selectable是资格门禁不只是视觉置灰已归档、受权限保护或后台处理中项目不能参与批量操作。仅把文字改成灰色不够ListItem仍可能接收滑动选择。应同时设置selectable并在onSelect进入业务集合前再校验一次防止资格在手势过程中变化。案例一筛选和云同步同时发生选择结果仍绑定任务ID先定义最小数据模型。这里用字符串ID模拟持久化主键生产环境可以来自本地数据库或服务端但同一任务生命周期内必须稳定。interfacePrepTask{id:string;title:string;stage:todo|doing|done;locked:boolean;}functionisSelectable(task:PrepTask):boolean{return!task.lockedtask.stage!doing;}functionreconcileSelection(selectedIds:string[],currentItems:PrepTask[]):string[]{constallowednewSet(currentItems.filter(isSelectable).map(itemitem.id));returnselectedIds.filter(idallowed.has(id));}页面使用selectedIds而不是selectedIndexes。每次数据源完成筛选、同步或删除后先与当前可选ID求交集这样隐藏项、已经删除项和新锁定项都会从选择集合收敛出去。EntryComponentV2struct PrepChecklistPage{LocalprivateeditMode:booleanfalse;LocalprivateselectedIds:string[][];LocalprivateonlyTodo:booleanfalse;Localprivatetasks:PrepTask[][{id:wash-lettuce,title:清洗生菜,stage:todo,locked:false},{id:slice-beef,title:切牛肉片,stage:todo,locked:false},{id:boil-soup,title:炖汤计时中,stage:doing,locked:true},{id:plate-dish,title:装盘,stage:done,locked:false}];privategetvisibleTasks():PrepTask[]{returnthis.onlyTodo?this.tasks.filter(itemitem.stagetodo):this.tasks;}privateisSelected(id:string):boolean{returnthis.selectedIds.includes(id);}privateupdateSelected(id:string,selected:boolean):void{consttaskthis.tasks.find(itemitem.idid);if(!task||!isSelectable(task)){this.selectedIdsthis.selectedIds.filter(valuevalue!id);return;}constnextnewSet(this.selectedIds);selected?next.add(id):next.delete(id);this.selectedIds[...next];}privatereplaceTasks(next:PrepTask[]):void{this.tasksnext;this.selectedIdsreconcileSelection(this.selectedIds,next);}build(){Column({space:12}){Row({space:8}){Button(this.editMode?完成选择:批量处理).onClick(()this.setEditMode(!this.editMode))Toggle({type:ToggleType.Switch,isOn:this.onlyTodo}).onChange((value:boolean){this.onlyTodovalue;this.selectedIdsreconcileSelection(this.selectedIds,this.visibleTasks);})Text(已选 this.selectedIds.length 项)}List({space:8}){RepeatPrepTask(this.visibleTasks).each((repeatItem){ListItem(){Row({space:12}){Text(repeatItem.item.title).layoutWeight(1)if(repeatItem.item.locked){Text(处理中).fontColor(#8A8A8A)}}.padding(14).width(100%)}.selectable(isSelectable(repeatItem.item)).selected(this.isSelected(repeatItem.item.id)).onSelect((selected:boolean){this.updateSelected(repeatItem.item.id,selected);})}).key(itemitem.id)}.enableEditMode(this.editMode).onEditModeChange((enabled:boolean){this.setEditMode(enabled);}).editModeOptions({useDefaultMultiSelectStyle:true,enableTwoFingerMultiSelect:true})}.padding(16).width(100%).height(100%)}privatesetEditMode(enabled:boolean):void{this.editModeenabled;if(!enabled){this.selectedIds[];}}}数据变化要按事务顺序收口云同步返回新数组时不能先让UI渲染新顺序、下一帧再清理旧选择。推荐在一个方法中完成替换数据 - 重新计算可选ID - 生成新选择数组。若数据源使用LazyForEach还要按官方要求通过DataChangeListener通知组件刷新否则模型正确屏幕上的复用项仍可能停留在旧状态。案例一的验收矩阵操作期望选择集合期望界面划过前两项wash-lettuce、slice-beef两行选中打开“只看未完成”两个ID仍存在对应任务仍选中同步把slice-beef改为doing只保留wash-lettuce切牛肉片不可选在首位插入新任务旧选择ID不变不发生下标漂移删除wash-lettuce空集合计数回到0案例二自定义复选框与行内滑动操作冲突划哪一段才算多选购物清单的每一行还需要“左滑调整数量”或点击进入详情。若关闭系统默认复选框自行在左侧画选择圆点却没有裁决手势用户从数量按钮起手也可能触发连续多选反过来业务手势抢占整个ListItem多选轨迹又完全进不来。这个案例采用明确的交互分区编辑态下左侧48vp为连续选择通道中间内容区仍可滚动右侧数量按钮只处理点击。选择集合仍由ListItem的selected/onSelect驱动自定义图标只负责显示不能维护第二份布尔值。BuilderfunctionShoppingRow(item:ShoppingItem,editMode:boolean,selected:boolean){Row({space:10}){if(editMode){SymbolGlyph(selected?$r(sys.symbol.checkmark_circle_fill):$r(sys.symbol.circle)).fontSize(24).width(48)}Column({space:4}){Text(item.name).fontSize(18)Text(item.amountitem.unit).fontSize(14).fontColor(#666666)}.alignItems(HorizontalAlign.Start).layoutWeight(1)Button().enabled(!editMode)}.height(64).padding({left:editMode?0:12,right:12})}List关闭默认样式以后通过onGestureRecognizerJudgeBegin决定业务手势是否继续参与。官方示例使用手势tag与本地触点位置区分滑动多选通道项目中的48vp只是本文的交互规格不是框架固定值最终应结合触控热区、字体缩放和设备形态做真机验收。List({space:6}){RepeatShoppingItem(this.items).each((repeatItem){ListItem(){ShoppingRow(repeatItem.item,this.editMode,this.isSelected(repeatItem.item.id))}.selectable(!repeatItem.item.purchased).selected(this.isSelected(repeatItem.item.id)).onSelect((selected:boolean){this.updateSelected(repeatItem.item.id,selected);})}).key(itemitem.id)}.enableEditMode(this.editMode).onEditModeChange((enabled:boolean)this.setEditMode(enabled)).editModeOptions({useDefaultMultiSelectStyle:false,enableTwoFingerMultiSelect:false}).onGestureRecognizerJudgeBegin((event:BaseGestureEvent,current:GestureRecognizer,recognizers:ArrayGestureRecognizer){constfirstFingerevent.fingerList[0];if(!firstFinger){returnGestureJudgeResult.CONTINUE;}constinSelectionLanethis.editModefirstFinger.localX48;if(current.getTag()!SWIPESELECTinSelectionLane){returnGestureJudgeResult.REJECT;}returnGestureJudgeResult.CONTINUE;})这里关闭enableTwoFingerMultiSelect是因为购物清单右侧有加减数量交互双指自动进入编辑态容易与原有手势心智冲突。另一个没有行内操作的文件清单完全可以保留默认true。配置应由场景决定不应为了“功能更多”统一开启。手势裁决至少验证四种起点起点编辑态期望左侧选择通道是连续选择/取消选择菜名内容区是列表滚动不误改选择数量按钮否执行加减不进入编辑态已购且不可选行是轨迹经过也不进入集合不要只在静态截图中确认复选框。连续滑选是轨迹行为至少要录制“从可选项滑过不可选项再进入可选项”的操作并核对onSelect回调序列、最终ID集合和屏幕标记三者一致。可复用的选择归约器先在宿主侧测清业务规则API 26 UI暂时无法在当前API 24环境中编译但稳定ID、资格变化和退出策略属于可移植逻辑可以先用纯TypeScript断言锁住。typeSelectionEvent|{type:select;id:string}|{type:unselect;id:string}|{type:replace-items;allowedIds:string[]}|{type:exit-edit;keep:boolean};functionreduceSelection(current:string[],event:SelectionEvent):string[]{constnextnewSet(current);if(event.typeselect)next.add(event.id);if(event.typeunselect)next.delete(event.id);if(event.typereplace-items){constallowednewSet(event.allowedIds);return[...next].filter(idallowed.has(id));}if(event.typeexit-edit!event.keep)return[];return[...next];}应覆盖的最小断言包括重复select不产生重复ID、删除前置项不改变后续选中身份、资格变更会剔除ID、筛选隐藏项不会误提交、退出编辑态按策略清空、未知ID不能进入最终命令。接入步骤与日志设计为业务对象确定稳定ID并确认同步、分页和本地缓存不会重新生成身份。把editMode和selectedIds收口到页面或专用ViewModel禁止行组件维护第二份选择状态。List绑定enableEditMode、onEditModeChange和editModeOptions。每个ListItem绑定selectable、selected和onSelect资格判断在回调入口再次执行。数据替换后立即做selection与allowedIds的交集收敛。自定义样式时定义手势通道记录触点区域、手势tag和裁决结果。批量命令提交前按ID回查当前对象再做一次权限与状态校验。调试日志不要打印完整菜谱或账号数据只记录可定位字段interfaceSelectionTrace{action:enter|select|unselect|reconcile|exit;itemIdHash?:string;selectedCount:number;visibleCount:number;reason:toolbar|system|two-finger|data-change;}若日志显示selectedCount正确而屏幕错误优先查LazyForEach/Repeat的key与刷新通知若屏幕正确而提交对象错误优先查下标映射和提交前回查若轨迹经过不可选项仍收到onSelect检查selectable是否随数据变化及时刷新。发布前检查表选择集合保存稳定ID不保存数组下标或ListItem实例。List的enableEditMode与onEditModeChange形成双向闭环。返回、侧滑返回、双指进入和工具栏入口都经过同一个状态方法。ListItem同时设置selectable、selected和onSelect。数据筛选、排序、删除、同步后立即收敛选择集合。LazyForEach数据变化通过正确通知刷新Repeat使用稳定key。自定义选择样式没有维护第二份布尔状态。行内滑动、滚动、点击和连续多选的手势区域经过裁决测试。批量操作提交前重新校验对象存在性、权限与当前状态。证据中区分宿主模型断言、API 26编译、预览器和真机触控结果。证据边界与参考资料本文依据当前华为官方List开发指南、List与ListItem API参考、HarmonyOS 7升级适配资料和2026年7月开发者月刊整理。官方资料证明API、起始版本、回调与配置语义文中的宿主断言只能证明稳定ID与选择归约逻辑。当前环境未完成API 26编译、系统返回手势、双指进入编辑态、连续触控轨迹或真机多设备验证接入时应在目标SDK与设备上补齐这些证据。创建列表List开发指南List API参考ListItem API参考HarmonyOS 7升级适配指导2026年7月开发者月刊