HarmonyOS API 26 Navigation 导航栏位置：navBarPosition、左右布局与折叠屏适配

Navigation 在手机竖屏里通常把导航栏放在起始侧，但进入平板横屏、2in1 窗口或折叠屏展开态后，固定使用同一侧可能造成阅读路径绕行、折痕遮挡、主内容空间失衡。真正需要治理的不是一次 navBarPosition 赋值，而是如何让位置选择跟随窗口、阅读方向、折痕和用户偏好稳定变化。

本文把导航栏位置拆成应用侧可测试策略，再由平台适配层映射到真实 Navigation 能力。示例不会虚构 HarmonyOS 构建、系统布局解析或折叠屏真机结果。

一、位置是环境派生状态

导航栏位置影响页面结构，但不属于业务路由身份。相同的列表页在手机、平板和折叠屏上可以采用不同位置，路由参数仍应保持一致。把位置写进 NavPathStack 会让页面恢复依赖旧设备环境，因此应由当前窗口重新计算。

ts 复制代码

export type NavBarSide = 'start' | 'end'
export interface NavBarPositionInput {
  apiVersion: number
  layoutDirection: 'ltr' | 'rtl'
  compactWidth: boolean
  foldCreaseNearStart: boolean
  userPrefersEnd: boolean
}

start 与 end 表达逻辑方向，比直接写 left、right 更适合处理 RTL 阅读顺序。

二、决策流程与优先级

版本能力和紧凑窗口先处理；折痕避让高于个人偏好；用户明确偏好高于默认阅读方向。优先级固定后，多个事件同时到达也不会产生随机结果。

ts 复制代码

export function decideNavBarPosition(i: NavBarPositionInput) {
  if (i.apiVersion < 26) return { side: 'start', reason: 'API_UNSUPPORTED' }
  if (i.compactWidth) return { side: 'start', reason: 'COMPACT_WIDTH' }
  if (i.foldCreaseNearStart) return { side: 'end', reason: 'FOLD_CREASE_AVOIDANCE' }
  if (i.userPrefersEnd) return { side: 'end', reason: 'USER_PREFERENCE' }
  if (i.layoutDirection === 'rtl') return { side: 'end', reason: 'RTL_READING_ORDER' }
  return { side: 'start', reason: 'DEFAULT' }
}

原因码用于诊断和测试，不直接展示给用户，也不记录业务内容。

三、分层结构避免页面散落判断

页面只采集窗口和交互状态，策略函数负责决策，平台适配层负责把逻辑方向映射到 Navigation。这样 API 变化、设备断点和页面业务互不污染。

ts 复制代码

interface NavBarPositionAdapter {
  apply(side: NavBarSide): void
}

class NavBarPositionController {
  private lastSide?: NavBarSide
  update(input: NavBarPositionInput, adapter: NavBarPositionAdapter): void {
    const next = decideNavBarPosition(input)
    if (next.side === this.lastSide) return
    this.lastSide = next.side
    adapter.apply(next.side)
  }
}

控制器只在结果变化时写入组件状态，窗口连续缩放时不会重复刷新。

四、紧凑窗口不要强行左右分栏

手机竖屏、小窗和折叠屏外屏的可用宽度有限，导航栏与内容并排会挤压正文。此时示例统一回到 start，真实工程还应配合 Navigation 模式选择，让导航栏按产品既有交互呈现。

ts 复制代码

function isCompact(widthVp: number): boolean {
  return widthVp < 600
}

600vp 仅是策略示例。工程应复用已有断点，并覆盖字体放大、分屏和系统安全区后的真实可用宽度。

五、折痕避让不是简单左右翻转

折叠屏展开后，物理折痕可能靠近逻辑起始侧。若导航栏包含高频操作，折痕会降低可达性，因此策略允许把导航栏移到另一侧。但位置切换前必须确认内容区、分割线、拖拽区域和返回路径都能同步变化。

ts 复制代码

interface FoldSnapshot {
  expanded: boolean
  creaseX: number
  windowWidth: number
}

function creaseNearStart(s: FoldSnapshot): boolean {
  return s.expanded && s.creaseX < s.windowWidth * 0.45
}

示例只表达判断思路，不代表系统折痕 API 或阈值。项目应通过官方窗口与折叠屏能力获得实际参数。

六、RTL阅读方向使用逻辑位置

国际化不能只翻译文字。RTL 环境中，导航栏、返回图标、列表层级和内容起始方向需要形成一致阅读顺序。使用 start/end 后，策略可以在适配层统一转换，减少页面手写左右判断。

ts 复制代码

function physicalSide(side: NavBarSide, rtl: boolean): 'left' | 'right' {
  if (!rtl) return side === 'start' ? 'left' : 'right'
  return side === 'start' ? 'right' : 'left'
}

真实 Navigation 是否已经处理逻辑方向，应以目标 SDK 文档和实际联调为准，避免应用重复镜像。

七、用户偏好需要明确边界

允许用户选择导航栏位置时，应把偏好当作轻量设置保存，而不是保存最终物理坐标。设备变窄或折痕冲突时，安全布局可以暂时覆盖偏好；窗口恢复后再重新应用。

ts 复制代码

interface NavPreference { preferEnd: boolean }

偏好持久化应通过服务层完成，页面不直接调用 Preferences。清除数据后回到默认逻辑方向。

八、窗口变化要使用完整快照

宽度、折叠姿态和阅读方向可能连续变化。每个事件直接改 Navigation 容易出现旧结果倒灌。应先形成不可变快照，再统一计算。

ts 复制代码

interface LayoutSnapshot {
  revision: number
  widthVp: number
  rtl: boolean
  creaseNearStart: boolean
}

异步回调完成时比较 revision，只接收最新结果；同一侧结果再通过控制器去重。

九、切换位置时保护焦点与返回路径

导航栏从一侧切到另一侧可能导致组件重建。键盘焦点、屏幕阅读器焦点和当前选中项不应丢失。建议用稳定条目 ID 保存选中状态，并在布局稳定后恢复焦点。

ts 复制代码

interface NavSelection { selectedId: string; focusedId?: string }

不要用数组索引充当长期身份，因为动态菜单、权限过滤和国际化排序都可能改变索引。

十、深浅色与位置决策解耦

导航栏位置由布局环境决定，深浅色只影响背景、文字、图标和分割线。主题变化不应触发左右位置切换，否则用户会把视觉更新误认为导航结构变化。

ts 复制代码

interface NavVisualTokens {
  background: ResourceColor
  primaryText: ResourceColor
  divider: ResourceColor
}

同名颜色资源应同时提供浅色和深色版本，并验证状态栏、导航栏和内容背景衔接。

十一、32项主机侧策略测试

测试覆盖版本边界、LTR/RTL、用户偏好、折痕避让、紧凑窗口与组合优先级。

powershell 复制代码

node items/131-navigation-navbar-position/test-navbar-position-policy.mjs

预期为 RESULT 32/32。它只证明纯函数输出，不证明系统 navBarPosition 解析、ArkUI 布局或折叠屏真机表现。

十二、多设备验收矩阵

设备场景	重点检查	预期
手机竖屏	内容宽度、返回操作	紧凑布局可达
手机横屏	菜单拥挤、文本截断	操作区不重叠
平板横屏	导航与内容比例	阅读路径连续
折叠屏展开	折痕与触控区	高频操作避开折痕
2in1 窗口缩放	连续断点切换	无闪烁、无焦点丢失
RTL 环境	逻辑起始方向	图标和层级一致

每个场景还应覆盖深浅色、字体放大、键盘焦点和系统返回操作。

十三、常见问题排查

问题	原因	处理
窗口缩放时左右闪动	断点没有滞回	增加稳定区间并去重
折痕避开后内容错位	只改导航栏位置	同步检查内容约束与分割线
RTL 下返回方向错误	混用物理和逻辑方向	统一使用 start/end
恢复页面位置不对	保存了派生状态	按当前环境重新计算
偏好导致小窗拥挤	偏好优先级过高	紧凑窗口先回退
键盘焦点丢失	位置切换导致重建	按稳定 ID 恢复焦点

十四、验收清单

导航栏位置只有一个决策入口。
紧凑窗口、折痕、偏好与 RTL 优先级明确。
位置不写入业务路由参数。
连续窗口事件使用快照和修订号。
位置切换保持选中项、焦点与系统返回路径。
深浅色资源与位置策略解耦。
三张图均为 1600×900 PNG。
32 项主机策略测试通过。
折叠屏、平板和 2in1 真实结果单独验收。

十五、验证边界声明

本文完成的是官方资料核对、应用侧位置策略建模和主机纯函数测试。没有执行 HarmonyOS 工程构建、系统 navBarPosition 解析、ArkUI 页面联调、折叠屏模拟器或多设备真机验收，因此不把这些结果描述为已通过。

十六、总结

导航栏左右位置治理的核心是把版本、窗口、折痕、偏好和阅读方向收敛成可解释的决策链，再通过单一控制器映射到 Navigation。位置作为当前环境的派生状态，不污染业务路由；切换时保护焦点与阅读顺序，才能真正适配手机、平板、折叠屏和 2in1。

十七、AI辅助声明

本文在资料整理、示例结构和文字校对阶段使用了 AI 辅助。API 边界以华为官方文档为准；测试结果只代表本地主机侧策略，不代表 HarmonyOS 平台运行或真机验收结果。

十八、接入前检查清单

HarmonyOS AP正式接入前，工程侧要过一遍检查清单：SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停，带着不匹配的版本往上冲，排错成本会翻倍。

ts 复制代码

interface PrecheckItem { name: string; pass: boolean; note?: string }
const checklist: PrecheckItem[] = [
  { name: 'SDK/API版本匹配', pass: false },
  { name: '权限声明完整', pass: false },
  { name: '开关集中管理', pass: false },
  { name: '包体积增量<预算', pass: false },
]
const allPass = checklist.every(x => x.pass)

检查清单跑通的标志是：新建工程按清单接入一次成功，且不依赖任何口头经验。做不到，说明文档还缺关键步骤。

十九、常见坑与版本适配记录

HarmonyOS AP最常踩的坑集中在三处：示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表，注明坑点、影响版本、修复方式与验证方式。

ts 复制代码

interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] }
const pitfalls: Pitfall[] = []
function knownPit(api: string): Pitfall[] { return pitfalls.filter(p => p.sinceApi === api) }

适配表的价值在升级时兑现：每次目标版本变更，先对照表过一遍已知坑，能省下一整轮盲目排查。