目录

分栏模式

分栏模式是元服务为适配大屏设备(折叠屏、平板、PC等)提供的一种布局能力。它将元服务窗口划分为左右两个并排的独立展示区域,支持用户在单一屏幕上同时浏览和操作两个页面,提升信息密度与操作效率。

核心点:将窗口分为两半,各自展示独立页面。左栏为主导部分,右栏为从属部分。

支持版本:ASCF运行时版本2.0.6及以上且API 20及以上

核心概念

概念 说明
左栏 主导栏位,始终展示首页或Tab页面,是用户的主要导航入口。
右栏 从属栏位,展示当前路由栈顶页面或占位图,承载详情/次级内容。
栈顶 当前路由栈最上层的页面,分栏下展示在右栏。
栈底 路由栈最底层的页面,首页或Tab页,分栏下展示在左栏。
占位图 当右栏无任何页面展示时,在栏位正中央展示的默认图片。
栏位 分栏模式下并排的独立展示区域(左栏/右栏)。
锚定模式 元服务采用的导航模式:左栏永远固定为根页面(首页/Tab),右栏随路径推进变化。适用于"全局导航 + 详情"场景(如购物、消息列表)。

分栏结构示意图

支持的设备与窗口比例

分栏模式由窗口宽高自动触发,开发者无需手动切换。当窗口宽高发生变化时,ASCF框架会对页面进行缩放以保证用户的体验。

定义窗口宽度比例:1x = 高度 * 0.72。

窗口比例与效果

窗口宽度比例 页面效果
0.75x ~ 1x 页面缩小适配
1x ~ 1.2x 页面放大适配
1.2x ~ 2.3x 双栏模式
2.3x以上 双栏模式 + 两边留黑

典型使用场景

分栏模式适用于"主导航 + 详情"或"列表 + 详情"类页面结构,核心价值在于减少用户在两个页面间来回跳转的操作成本。

[h2]列表-详情

最典型的分栏场景。左栏展示列表(商品列表、消息会话列表、文章列表),右栏展示选中项的详情。

适用页面栈路径:列表页 → 详情页,分栏下左栏固定列表,右栏随点击切换详情。

[h2]主从面板

适用于设置类、管理后台类页面。左栏为主菜单/分类导航,右栏为对应设置项的配置面板。

[h2]多级导航

适用于文件管理、分类筛选等多层级场景。左栏为根级目录,右栏为当前层级的展开内容。

元服务采用锚定模式,左栏始终固定为根页面。对于需要"左栏也随路径推进"的级联场景(如A→B→C时左栏变为B),当前版本不支持,可关注后续多栏模式规划。

快速开始

[h2]启用分栏

在app.json中添加frameset配置项即可启用分栏能力:

{
  "frameset": true
}
配置项 默认值 作用
frameset false 启用分栏能力

启用后,当用户调整元服务窗口宽度超过阈值(折叠屏展开、平板显示)时,自动切换为左右分栏。

[h2]配置占位图

当右栏无任何页面展示时(如元服务刚启动、仅有一个首页),右栏会展示默认占位图。开发者可自定义占位图:

将自定义图片放置在元服务的frameset/placeholder.png路径下即可替换默认占位图。

提示:配置占位图需要注意元服务包体限制,避免设置过大图片导致超出包体积限制。

[h2]分栏效果预览

启用分栏后,用户通过调整元服务窗口宽度(横竖屏切换、折叠屏切换、窗口分屏)触发分栏效果。

分栏模式适配

对于已使用沉浸式适配(自定义导航栏、全屏布局等)的元服务,在分栏模式下需要针对性调整。分栏会改变窗口尺寸和menubar位置,原本针对单窗口设计的沉浸式页面可能出现坐标错位、按钮偏移等问题。

[h2]接口

分栏模式下,修改当前页面显示效果的接口总是作用于调用接口所在栏位的页面。

[h2]获取窗口信息

分栏模式下has.getSystemInfo()、has.getSystemInfoSync()、has.getWindowInfo()将会返回当前栏位页面可使用的窗口宽/高(windowWidth、windowHeight)。

接口 默认情况 分栏策略
has.getSystemInfo / getSystemInfoSync / getWindowInfo 获取当前页面可使用窗口宽/高 区分调用位置,返回调用所在栏的可使用窗口宽/高
// 左栏页面调用 → 返回左栏宽高
// 右栏页面调用 → 返回右栏宽高
const systemInfo = has.getSystemInfoSync()
console.info(systemInfo.windowWidth)  // 当前栏宽度,而非整个窗口宽度
console.info(systemInfo.windowHeight) // 当前栏高度

适配建议:页面布局应基于windowWidth/windowHeight动态计算,而非使用固定值。分栏下两栏宽度不同,硬编码尺寸会导致布局错乱。

[h2]沉浸式

分栏模式下,has.getMenuButtonBoundingClientRect()接口始终以窗口右上角menubar的相对位置处理避让,左右栏返回的结果相同。

适配要点:

  1. 不用区分左右栏,直接使用left或width做页面右上角的menubar避让。
  2. 窗口变更时(横竖屏切换、折叠屏切换、窗口分屏),需监听has.onWindowResize()事件,在事件回调中重新调用has.getSystemInfo()、has.getMenuButtonBoundingClientRect()接口获取最新的窗口信息(windowWidth/windowHeight)和右上角的menubar位置信息刷新布局。

[h2]页面生命周期

分栏模式下,页面onShow、onHide生命周期触发规则略有变化,以"页面所处路由栈位置"为准,因此在Tab页面触发onHide生命周期时,在用户视角上内容依然可见、可操作。

onShow:

当页面"变为栈顶"时触发。

onHide:

当页面"从栈顶变为非栈顶"时触发。

[h2]分享行为

  1. 分栏模式下,menubar的分享行为以栈顶页面为准。
    • 当前分享的页面以打开的栈顶页面为准(即右栏展示的页面)。
    • 面板分享按钮状态以当前打开的栈顶页面配置为准。
  2. 分栏模式下,通过转发按钮触发的分享行为以按钮所在的页面为准。

适配要点:若左栏和右栏页面的分享配置不同,分享面板显示的是右栏(栈顶)页面的配置。开发者无需为分栏额外处理分享逻辑,框架自动取栈顶页配置。

[h2]async/await

分栏模式下,在async方法内使用await,可能导致await后续代码无法正常执行。

适配要点(二选一):

  1. 升级ASCF Toolkit(CLI工具)到最新版本(预计11月底发布)。
  2. 将await替换为Promise的使用方式。

[h2]getCurrentPages()

单栏模式下,getCurrentPages()接口返回页面路由栈,按下面方式获取栈顶页面作为当前页面使用。

const pages = getCurrentPages();
const page = pages[pages.length - 1];

分栏模式下,左栏和右栏页面调用getCurrentPages()接口存在以下差异:

适配要点:

Taro.getCurrentInstance()

使用Taro框架开发的元服务,Taro.getCurrentInstance()接口未适配分栏模式,开发者在左栏页面调用getCurrentInstance()接口获取的是栈顶页面实例,而非左栏页面实例,会导致左栏页面对应功能不可用。

适配要点:检查左栏页面(Tab页、reLaunch打开的页面)是否有调用到getCurrentInstance()接口,有的话,升级到Taro框架最新版本。

常见问题

[h2]分栏切换是否销毁页面实例?

问题:单栏 ↔ 分栏切换时,页面会被销毁重建吗?

解答:不会。单栏 ↔ 分栏切换只改变展示方式,页面栈和页面实例保持不变。切换时:

因此页面内的数据状态(data、滚动位置等)在切换后保留,无需额外存储恢复。但建议在onWindowResize中重新获取窗口尺寸和menubar位置,因为栏位宽度已变化。

[h2]接口调用位置为什么影响效果?

问题:为什么getSystemInfo、showLoading等接口在左栏和右栏调用返回不同结果?

解答:分栏模式下,左右两栏是独立的展示区域,各自有不同的窗口尺寸和页面上下文。框架约定"修改当前页面显示效果"类的接口按调用位置作用于所在栏的页面:

这样设计是为了让左右两栏的页面能独立管理自身布局和状态,互不干扰。开发者在编写页面逻辑时,无需关心当前处于哪一栏,接口会自动作用于调用者所在的栏位。

[h2]右栏为什么显示占位图?

问题:为什么我的元服务分栏后右栏一直显示"暂无内容"占位图?

解答:右栏显示占位图有以下几种情况:

  1. 路由栈只有1层:仅有首页时,左栏显示首页,右栏无页面可展示,显示占位图。需要用户在左栏触发navigateTo跳转,新页面才会出现在右栏。
  2. 使用了switchTab / reLaunch:这两个接口会清空路由栈至只剩目标页面,右栏随之变为占位图。需要再次navigateTo才能在右栏打开新页面。
  3. 占位图未自定义:默认占位图为"暂无内容"。若要替换,将图片放置在frameset/placeholder.png。