导航行为

用于实现应用内外的页面跳转。

跳转页面

在应用内部进行页面切换或返回上一页，支持参数传递。

常用场景

• 点击商品列表项，跳转到商品详情页并传递商品 id。
• 小程序提交表单后，清空页面栈并打开成功提示页。
• 触发返回按钮，返回上一个页面并刷新数据。

参数配置

小程序端

Web 端

在编辑器外拼接页面路径和入参

在微信订阅消息的 page 字段、小程序码或其他编辑器外的场景中，需要手动填写页面路径并拼接入参。页面路径格式为 <包名>/<页面 ID>/<页面 ID>，主包为 pages，分包依次为 pages1、pages2 等。

• 整包传递（推荐）：使用 ?params=<URL 编码后的 JSON>。例如，将 { "id": 123, "name": "汽车" } 转为 JSON 文本并进行 URL 编码后，拼接到 params=；目标页面会解析并还原参数类型。
• 逐个拼接：使用 ?id=123&name=汽车。数字和布尔形式的文本可能被识别为对应类型；需要确保值保持文本时，使用整包传递。

运行结果与输出

无。

运行机制

• 微信小程序端：全部采用小程序原生接口，原理见小程序页面路由 。小程序存在页面栈概念，除交互表现外，页面生命周期也与 Web 端不同。各跳转方式对应的生命周期触发差异，详见小程序生命周期说明。
• Web 端：本质为单页应用，所有跳转基于单页应用的虚拟路由机制管理。
  • 返回旧页面：调用浏览器原生后退接口（等同 history.go(-1)），在历史记录栈执行出栈，物理表现等同于点击浏览器左上角「←（后退）」按钮。
  • 打开新页面（当前标签页）：调用 history.pushState，在当前标签页历史栈顶压入一条新 URL 记录，页面跳转并点亮浏览器「←」按钮，允许物理后退。
  • 打开新页面（新标签页）：调用原生 window.open，原标签页历史栈保持静止，浏览器生成一个拥有全新空历史栈的独立标签页，无法通过后退按钮回到原标签页。

边界情况

• 小程序页面栈限制：受微信小程序底层限制，小程序页面栈的最大深度为 10 层（Web 端无限制）。如果连续使用「推入新页面」导致页面栈达到 10 层，继续推入新页面将会失败（表现为点击无响应）。建议结合具体的业务场景灵活使用其他「跳转方式」来管理页面栈：
  • 替换当前页面：如果跳转后不需要用户再返回当前所在页面，可以使用此方式。它会把当前页面替换为目标页面，不会增加页面栈的总层数。
  • 清空页面栈并打开页面：适用于一个完整流程结束的场景。例如用户完成支付或提交表单后跳转到“成功提示页”，此时清空页面栈可以防止用户按返回键回到已提交的流程，同时也能释放页面栈。
  • 切换导航页面：适用于回到带有底部 Tab 导航栏的页面（如“首页”、“个人中心”）。如文档中的例子所述，这样也会清空中间的提交流程页面栈。
  • 返回旧页面：在列表到详情再到编辑的场景下，操作完成后通过“返回旧页面”回到上级并开启“刷新页面”加载最新数据，这是标准的页面出栈操作，能有效控制栈深度。
• Web 端后退时，浏览器历史记录会恢复上一步完整 URL（含路径参数 /123 与查询参数 ?id=123），页面自动重新解析参数；但因 DOM 树已卸载，页面所有数据源、页面变量、组件状态都会重置。
• 若目标页面设置了路径参数，但跳转时传入了空值，则页面不会跳转，浏览器控制台会抛出错误，但是行为序列继续执行。
• 在目标页面定义查询参数时，无论是否传值，都可以正常跳转。（目标页面定义查询参数时，可配置“为空时，网址中不展示该参数”，用于控制查询参数值为空时，网址中是否展示该参数。）

用法举例

1. 商品列表点击跳转到商品详情页（推入页面 + 传递商品 id）（小程序端 / Web 端）

• 需求： 用户在「商品列表页」点击某个商品卡片，页面平滑推入「商品详情页」，并把该商品唯一 id 传过去，详情页据此自动渲染对应商品信息，形成「列表 → 详情」的浏览闭环。

• 配置流程：

  1. 前置准备：
     • 创建「商品列表页」与「商品详情页」；
     • 在「商品列表页」中配置展示商品信息的列表组件，命名为「商品列表」；
     • 在「商品详情页」页面配置中创建页面入参 product_id（长整数类型）。
  2. 选择组件：在「商品列表页」画布上，选中列表组件内部的「商品卡片」组件。
  3. 添加行为：在右侧配置面板切换到 「行为」 标签页，在 「点击时」 下添加行为。
  4. 配置行为基础参数：
     • 在行为下拉框中，搜索并选中 「跳转页面」；
     • 方式 设为 打开新页面，跳转方式 设为 推入新页面（Web 端设为 当前标签页），目标页面 选「商品详情页」。
  5. 绑定参数传递：
     • 配置面板下方自动显露出目标页面所需参数 product_id；
     • 点击其右侧 「+」加号按钮（数据绑定按钮），在数据源中依次展开并选择：列表项 -> 商品列表 -> 当前项 -> 选中 id。

• 运行结果： 点击商品卡片，页面平滑推入商品详情页，并依据传入的 id 自动渲染该商品详情；点击顶部返回按钮可无缝回到原列表页。

2. 多步骤表单填写（推入页面 + 传递表单数据）（小程序端 / Web 端）

• 需求： 用户在注册/提单第一步页面输入手机号后，点击「下一步」按钮，页面平滑推入表单第二步页面，并把手机号传过去，第二步页面自动显示该手机号。

• 配置流程：

  1. 前置准备：
     • 创建「表单第一步页面」与「表单第二步页面」；
     • 在「表单第一步页面」配置一个输入框组件，命名为「手机号输入框」；
     • 在「表单第二步页面」页面配置中创建页面入参 temp_phone（类型选文本）。
  2. 选择组件：在「表单第一步页面」画布上，选中「下一步」按钮组件。
  3. 添加行为：在右侧配置面板切换到 「行为」 标签页，在 「点击时」 下添加行为。
  4. 配置行为基础参数：
     • 搜索并选中 「跳转页面」；
     • 方式 设为 打开新页面，跳转方式 设为 推入新页面（Web 端设为 当前标签页），目标页面 选「表单第二步页面」。
  5. 绑定参数传递：
     • 配置面板下方显露出参数项 temp_phone；
     • 点击其右侧 「+」加号按钮，在数据源中依次展开并选择：组件 -> 手机号输入框 -> 选中 组件输出。

• 运行结果： 用户点击「下一步」，自动进入表单第二步页面，且页面上直接渲染出第一步填写的手机号。

3. 流程完成重定向到首页（切换导航页面）（仅小程序端）

• 需求： 用户提交完订单或完成答题后，点击「完成」按钮直接回到带底部导航栏的首页。此时整个中间的提交流程页面栈需被清空，防止用户通过物理返回键重新回到已提交的订单填写页。

• 配置流程：

  1. 前置准备：创建带底部导航栏配置的「首页」与订单填写的「提交结果页」。
  2. 选择组件：选中「提交结果页」上的「返回首页」按钮。
  3. 添加行为：在右侧面板的 「行为」 标签页下，在 「点击时」 事件中添加行为。
  4. 配置行为基础参数：
     • 搜索并选中 「跳转页面」；
     • 方式 设为 打开新页面，跳转方式 设为 切换导航页面，目标页面 选「首页」。

• 运行结果： 点击按钮后页面清空页面栈并直接返回「首页」，左上角不再有返回按钮，手机上按物理返回键将直接退出小程序，保障交易与业务流程的闭环状态。

4. 保存并返回列表（返回旧页面 + 刷新数据）（仅小程序端）

• 需求： 用户在商品编辑页修改了价格，点击「保存」按钮后页面自动返回到商品列表页，且列表页自动刷新展示更新后的价格。

• 配置流程：

  1. 前置准备：创建「商品列表页」与「商品编辑页」。
  2. 选择组件：在「商品编辑页」画布上，选中「保存」或「确定」按钮（若在表单提交的行为序列中，则作为行为序列的最后一个动作）。
  3. 添加行为：在行为面板的 「点击时」 事件中添加 「跳转页面」。
  4. 配置行为基础参数：
     • 方式 设为 返回旧页面；
     • 刷新页面 勾选为 是（开启刷新数据源）。

• 运行结果： 点击保存后编辑页关闭，应用自动后退回原列表页，同时列表页数据源被重新触发加载，展示出最新价格，无需用户手动下拉刷新。

5. 在新标签页打开应用内帮助中心（仅 Web 端）

• 需求： 用户在操作后台时点击顶部「查看帮助」按钮，浏览器在新标签页打开应用内的帮助中心页面，而原操作页面和输入状态保持不变。

• 配置流程：

  1. 前置准备：创建带帮助按钮的「系统管理后台页」。
  2. 选择组件：选中画布顶部的「查看帮助」按钮组件。
  3. 添加行为：在行为面板的 「点击时」 事件中添加 「跳转页面」。
  4. 配置行为基础参数：
     • 方式 设为 打开新页面，跳转方式 设为 新标签页，目标页面 选择或绑定要打开的帮助详情页。

• 运行结果： 点击按钮，浏览器保留原后台页不变，并在旁边生成一个新标签页展示帮助文档；用户看完关掉新标签页后，原后台操作表单和输入状态没有任何丢失。

打开外部链接

在应用中打开外部网页链接，或唤起系统级协议（拨号、邮件等）。

常用场景

• 点击帮助文档按钮，在浏览器新标签页中打开外部帮助中心。
• 触发广告横幅点击，在当前窗口跳转到外部合作方的活动页面。
• 点击「电话联系」唤起系统拨号盘。

参数配置

运行结果与输出

无。

运行机制

• 系统先获取配置的链接地址，并对格式进行安全预处理：若链接不含 // 且不以协议白名单（mailto、tel、sms、skype）开头，会自动在前方拼接 //，强制格式化为标准外部资源链接。
• 开启「在新标签页中打开」：底层调用 window.open(url, '_blank', 'noopener')，在全新独立标签页加载外部网页，原标签页状态和历史记录不受影响。
• 关闭「在新标签页中打开」：底层执行 window.location.href = url，在当前标签页内直接覆盖原有的 Zion 应用并跳转。

边界情况

• 无论开启或关闭新标签页，由于原页面被新标签页隔离或被销毁，原页面上的任何生命周期触发器都不会被触发。

特殊说明

当打开外部链接是按钮或文本组件「点击时」的唯一行为（没有其他行为，也没有成功/失败后续行为）时，不会走上文的 JavaScript 机制，而是被编译为原生 HTML 锚点标签：<a href="{链接}" target="{_blank | _self}" rel="noreferrer">；开启「在新标签页中打开」时 target 为 _blank，关闭时为 _self。

• 优势：为什么采用这种快捷渲染

  • SEO / 可抓取： 真实的 <a href> 是搜索引擎爬虫能够发现并跟踪的链接；纯 JavaScript 点击事件对爬虫不可见。
  • 原生链接交互： 中键点击、Ctrl/Cmd + 点击可在后台标签页打开链接，浏览器右键菜单（「在新标签页中打开」「复制链接地址」「在新窗口中打开」）也能按用户预期工作。
  • 无障碍访问： 元素可通过键盘聚焦，并被屏幕阅读器识别为链接；鼠标悬停时，浏览器状态栏会显示目标 URL。
  • 安全与隐私： rel="noreferrer" 可阻止新打开的页面访问 window.opener，并避免来源（referrer）地址泄露。
  • 无需 JavaScript 介入： 跳转是浏览器的原生行为，无需调用应用的行为引擎即可生效。

• 影响 1：不做 // 补全：链接按原样使用。因此像 example.com 这样的裸域名会被当作相对路径，基于当前应用域名解析（导致链接失效），而不会自动补全为 //example.com。在按钮/文本组件上请始终填写完整链接（如 https://example.com）。

• 影响 2：原生链接行为：由于是真实的 <a> 锚点，引用策略为 noreferrer，点击由浏览器（而非应用）接管处理。

• 何时仍走上文的 JavaScript 机制：非按钮/文本组件（如图片）、配置了多个点击行为、打开外部链接位于条件或循环行为内部、或该行为带有成功/失败后续行为。此时 // 补全与 window.open / window.location.href 调用按前文所述生效。

常见错误

• 链接被错误补全：填写的相对路径或非标准链接被自动拼接 //，导致跳转地址不符合预期。
• 链接地址为空：未填写或数据绑定结果为空，点击后无任何跳转。

用法举例

1. 跳转至第三方合作伙伴网站（仅 Web 端）

• 需求： 在系统主页展示合作伙伴的广告 Banner，用户点击后在新标签页中无缝打开外部合作站点的特定推广链接。

• 配置流程：

  1. 前置准备：创建「系统主页」并放置合作伙伴的「广告 Banner」(使用图片组件实现)。
  2. 选择组件：选中「广告 Banner」。
  3. 添加行为：在行为面板的**「点击时」** 事件下添加 「打开外部链接」。
  4. 配置行为基础参数：
     • 在新标签页中打开 勾选为 是（保障用户自己的系统不会被覆盖）；
     • 链接地址 填入 https://partner.example.com?utm_source=app。

• 运行结果： 用户点击 Banner 后，浏览器在新标签页打开该合作伙伴网站，对方可通过链接参数分析流量来源。

2. 联系客服电话（仅 Web 端）

• 需求： 用户在商品详情页或客服页面点击「电话联系」按钮，直接呼起系统拨号盘拨打特定客服热线。

• 配置流程：

  1. 前置准备：创建「客服帮助页」。
  2. 选择组件：在「客服帮助页」画布上，选中「电话联系」按钮组件。
  3. 添加行为：在右侧配置面板切换到 「行为」 标签页，在 「点击时」 下添加行为。
  4. 配置行为基础参数：
     • 搜索并选中 「打开外部链接」；
     • 在新标签页中打开 勾选为 否（拨打电话属系统调用，无需开新网页）；
     • 链接地址 直接填入 tel:4001234567。

• 运行结果： 用户在真机上点击按钮，应用直接呼出系统拨号界面并自动填好电话号码 400-123-4567。

3. 发送用户反馈邮件（仅 Web 端）

• 需求： 用户在后台页面点击「邮件反馈」按钮，直接唤起系统默认邮箱客户端，自动创建一封发给特定反馈邮箱的新邮件。

• 配置流程：

  1. 前置准备：创建「反馈页面」。
  2. 选择组件：选中画布上的「邮件反馈」按钮。
  3. 添加行为：在行为面板的**「点击时」** 事件下添加 「打开外部链接」。
  4. 配置行为基础参数：
     • 在新标签页中打开 勾选为 否；
     • 链接地址 填入 mailto:feedback@example.com（如需附带主题，可写成 mailto:feedback@example.com?subject=用户反馈）。

• 运行结果： 点击按钮后直接调起系统默认邮件软件，收件人已自动填入 feedback@example.com。

打开 WebView

在微信小程序内部使用 WebView 组件加载并展示外部网页。

常用场景

• 公众号文章：在小程序内展示微信公众号的图文内容。
• 官网页面：在小程序中展示完整的网站页面。

参数配置

运行结果与输出

无

运行机制

• 系统获取目标链接地址，调用微信原生页面跳转接口，将 WebView 组件与经过编码的链接地址传递过去，在小程序内部全屏加载。

边界情况

• 因微信平台安全规范，未通过资质或域名校验的链接会被微信侧直接拦截，行为本身不报错但网页无法渲染。

特殊说明

• 使用 WebView 必须满足以下前置资质与配置要求，否则网页将被微信强制拦截：
  • 主体资质限制：仅限企业主体认证的小程序可用，个人主体小程序不支持。
  • 关联公众号文章：如需展示微信公众号图文，必须预先在微信公众平台小程序后台将其与该公众号关联。
  • 自有外部网页：如需嵌入外部网页，必须完成以下闭环配置：
    1. 配置业务域名：登录微信公众平台小程序后台，在「管理 -> 开发管理 -> 业务域名」模块中添加目标网页域名。
    
    2. 上传校验文件：在配置业务域名时下载微信校验文件，并上传至目标网页服务器的根目录，以确保小程序有权访问。
    
    3. 启用私钥发布：在 Zion 平台发布小程序时，需启用「私钥发布模式」，具体请参照发布应用操作文档。

常见错误

• 个人主体小程序使用：个人主体小程序不支持 WebView，网页无法打开。
• 业务域名未配置或校验未通过：未添加目标域名或校验文件未上传到根目录，链接被微信拦截。
• 公众号文章未关联：展示公众号图文前未在小程序后台关联对应公众号，内容无法加载。

用法举例

1. 小程序中嵌入产品详细说明文档（仅小程序端）

• 需求： 在企业运营小程序中，点击「使用说明」按钮，在小程序内部全屏无缝加载外部企业官网的使用说明文档页面，无需离开小程序去浏览器查看。

• 配置流程：

  1. 前置准备：
     • 创建「产品中心页」；
     • 在微信公众平台小程序后台配置好该外部企业官网业务域名（如 https://docs.example.com），并将校验文件上传至该服务器根目录下。
  2. 选择组件：在「产品中心页」画布上，选中「使用说明」按钮。
  3. 添加行为：在行为面板的 「点击时」 事件中添加行为。
  4. 配置行为基础参数：
     • 搜索并选中 「打开 WebView」；
     • 链接地址 填入 https://docs.example.com/product-guide。

• 运行结果： 点击按钮，小程序内部自动弹出全屏 WebView 窗口并加载该官网说明页面，用户看完可直接左滑或点击左上角返回按钮回到原小程序页面。

2. 小程序中展示公众号图文（仅小程序端）

• 需求： 在社区小程序的新闻板块，点击某条公众号图文推介，直接在小程序内全屏无缝展示微信公众号对应文章。

• 配置流程：

  1. 前置准备：创建「新闻资讯页」，并在微信小程序管理后台完成与该目标微信公众号的关联绑定。
  2. 选择组件：选中「新闻资讯页」上代表该推介项的按钮。
  3. 添加行为：在行为面板的 「点击时」 事件中添加 「打开 WebView」。
  4. 配置行为基础参数：
     • 链接地址 填入 https://mp.weixin.qq.com/s/xxxxx（贴入公众号文章完整链接）。

• 运行结果： 点击后直接全屏展示公众号文章，排版完全对齐官方图文表现。

打开另一个小程序

在微信小程序内部跳转到其他特定的小程序。

常用场景

• 跳转到商圈小程序领券。
• 跳转到同主体的其他业务小程序。

参数配置

运行结果与输出

• 结果：无
• 成功时：跳转成功时触发。
• 失败时：跳转失败（如用户取消、AppID 不存在或网络异常）时触发。建议在“失败时”分支添加“显示提示”行为，例如“未能打开小程序，请重试”。

运行机制

• 底层使用微信小程序官方跨端框架 API Taro.navigateToMiniProgram 执行跳转。
• 成功与失败的回调会分别映射到 Zion 行为配置中的“成功时”与“失败时”后续行为序列。

边界情况

• 防重复触发：连续点击可能重复拉起微信跳转确认弹窗。可在按钮行为中使用禁用或加载中状态，避免重复触发。

特殊说明

• 严禁自动跳转：受微信底层安全策略严格限制，跳转行为必须由真实的用户手势直接触发（如点击按钮、点击列表项）。绝对不能将其配置在“页面加载时”或通过定时器自动触发。否则微信将强制拦截，报错 navigateToMiniProgram:fail can only be invoked by user gesture。
• Web 端限制：该行为仅支持微信小程序端。在 Web 端触发时，系统会拦截并显示提示。
• 版本控制 (envVersion)：Zion 平台当前不支持配置目标小程序的版本（如开发版、体验版、正式版）。默认由微信官方接口决定其跳转规则。通常正式版小程序只能跳转到目标小程序的正式版。开发/体验版可以跳转到目标小程序的相应版本，具体受微信平台控制。

常见错误与运行时用户感知

在微信小程序端，若没有配置“失败时”的分支，一旦跳转过程中出现任何错误，ZVM 运行时会捕获错误并静默终止，这会导致用户看到以下异常现象：

• 动态绑定空值导致跳转失败：Zion 不对 appId 进行非空校验。若动态绑定的 appId 在运行时为空，API 调用直接失败。
  • 未配置“失败时”的分支时的用户现象：用户点击按钮后界面完全没有任何反应或提示，极易给用户造成按钮“卡死”或“失效”的假象。请务必在跳转前使用“条件判定”确保 appId 有效。
• 非用户手势触发被拦截：微信安全策略要求跳转必须由用户手势（如点击按钮）触发。若配置在“页面加载时”或定时器中自动拉起跳转，微信将强制拦截，报错 navigateToMiniProgram:fail can only be invoked by user gesture。
• 目标小程序未关联或 AppID 错误：填写的 AppID 不存在或格式不正确，导致微信底层拦截跳转，触发“失败时”分支。
  • 未配置“失败时”的分支时的用户现象：微信会弹出官方原生的报错提示框（如“该小程序由于未关联等原因无法打开”）。在用户点击确定或关闭该提示后，页面会停留在原地，没有任何后续动作或自定义提示。
• 用户手动取消：在微信弹出的跳转确认框中，用户点击了取消，触发“失败时”分支。
  • 未配置“失败时”的分支时的用户现象：微信原生确认弹窗消失，原页面没有任何变化或反馈提示，给用户带来操作无回响的悬空感。

用法举例

1. 跳转到第三方物流小程序查询快递（仅小程序端）

• 需求： 用户在订单详情页点击「查看物流」按钮，微信弹出跳转确认框。用户确认后跳转至第三方物流小程序，并自动展示该快递单号的物流轨迹。

• 配置流程：

  1. 前置准备：
     • 创建「订单详情页」，并配置好订单数据模型，包含字段 快递单号。
  2. 选择组件：在「订单详情页」画布上，选中「查看物流」按钮组件。
  3. 添加行为：在右侧配置面板切换到 「行为」 标签页，在 「点击时」 下添加行为。
  4. 配置行为基础参数：
     • 在行为下拉框中，搜索并选中 「打开另一个小程序」；
     • 小程序 AppID 填入第三方物流小程序的 AppID（如 wx1234567890abcdef）；
     • 页面路径 填入物流小程序的查询页面路径（如 pages/express/detail）。
  5. 绑定参数传递：
     • 在 扩展数据 中点击‘+新增’；
     • 左侧输入框填写物流小程序要求的参数名（如 trackingNumber）；
     • 右侧点击 「+」加号按钮（数据绑定按钮），在数据源中依次展开并选择：页面数据 -> 当前订单 -> 选中 快递单号。

• 运行结果： 用户点击「查看物流」按钮，微信弹出跳转确认框。用户确认后跳转至第三方物流小程序，并自动展示该快递单号的物流轨迹。

2. 跳转到商圈小程序领券（仅小程序端）

• 需求： 用户在商场导购小程序中点击「领取优惠券」按钮，跳转至商圈会员小程序。目标小程序读取到传递的 couponId 后自动弹出对应的领券弹窗。

• 配置流程：

  1. 前置准备：
     • 创建「活动详情页」，页面数据中包含 优惠券 ID。
  2. 选择组件：在「活动详情页」画布上，选中「领取优惠券」按钮组件。
  3. 添加行为：在右侧配置面板切换到 「行为」 标签页，在 「点击时」 下添加行为。
  4. 配置行为基础参数：
     • 在行为下拉框中，搜索并选中 「打开另一个小程序」；
     • 小程序 AppID 填入商圈会员小程序的 AppID；
     • 页面路径 填入领券页面路径。
  5. 绑定参数传递：
     • 在 扩展数据 中点击‘+新增’；
     • 左侧输入框填写 couponId；
     • 右侧点击 「+」加号按钮（数据绑定按钮），在数据源中依次展开并选择：页面数据 -> 当前活动 -> 选中 优惠券 ID。

• 运行结果： 用户点击「领取优惠券」按钮，跳转至商圈会员小程序。目标小程序读取到传递的 couponId 后自动弹出对应的领券弹窗。