# @capgo/capacitor-native-navigation 中文文档 规范地址：https://npmcn.com/package/%40capgo/capacitor-native-navigation/ 版本：8\.16\.1 npm 元数据更新时间：2026-11-04T13:48:09.207Z 中文译文更新时间：2026-11-09T02:53:48.288Z 软件包许可：MPL-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-native-navigation 原文对照：https://npmcn.com/package/%40capgo/capacitor-native-navigation/?lang=original 项目主页：https://capgo.app/docs/plugins/native-navigation/ 源码仓库：https://github.com/Cap-go/capacitor-native-navigation ## 关键信息（来自 npm 元数据） - 包体积（解压后）：9.4 MB，86 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22\.0\.0 - 运行依赖：0 个 - peer 依赖：@capacitor/core \>=8\.0\.0 - 首次发布：2026-05-10T19:31:35.683Z - 最新版本发布：2026-11-04T13:48:08.863Z - 近 30 天下载量：72012（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：66（近 12 个月 66 个） ## 中文简介 本地导航、标签栏、安全区处理和WebView快照转换的电容插件. ## 安装 ```sh npm install @capgo/capacitor-native-navigation ``` 也可以使用：`pnpm add @capgo/capacitor-native-navigation`、`yarn add @capgo/capacitor-native-navigation`、`bun add @capgo/capacitor-native-navigation` ## README # @ capgo/ 电容- 本地导航 [![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-native-navigation)](https://capgo.app/?ref=plugin_native_navigation) **队长**:在几分钟内向您的Capacitor用户推进修正,在没有Mac的情况下构建签名的iOS和Android应用程序,以及 卷回一击. ## [\*免费开始\*](https://capgo.app/register/?ref=plugin_native_navigation) 14天无限自由审判. 不需要信用卡 > 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_native_navigation) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-native-navigation` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加入@capgo/capor-native-navigation到我的Capacitor app并把它接上。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_native_navigation) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_native_navigation) 原生导航栏,标签栏,安全区域处理,以及Capacitor应用的WebView快照转换. 您的网页框架保持路由和页面渲染, 而此插件则拥有平台表面: 大标题下的搜索字段, 与起始、 中心或结尾一致的标签栏, 以及后排的侧边栏杆 . **iOS 27和iPhone Duo. 互联网档案馆的存檔,存档日期2013-12-02.** 在iPhone Duo上,iOS将状态栏和系统制表栏移动到折叠外显示和景观上开放式显示上的一个垂直栏杆上. 开口肖像保持了水平条. Navbar 图标按钮加入该栏,标题保持水平. 后相或近相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 搜索可以是解开的按钮,突出动作保持被封,以及共享一个 `group` 变成一个扩张的控制。 曲线中心栏会留在底部. `configure({ verticalBarBehavior: 'disabled' })` 为不应使用铁路的屏幕保留横向栏. ## 演示 | 应用 | 磁盘流 | SVG 图标 | 样式 | | --- | --- | --- | --- | | ![Demo of capacitor-native-navigation in action](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/demo.webp) | ![Animated native navigation tap flow showing tab selection, push transition, and native back](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/demo-navigation.webp) | ![Animated native SVG icon demo showing inline SVG icons, native tint, labels, and tab selection](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/demo-svg-icons.webp) | ![Animated native navigation options demo showing dynamic colors, selected labels, custom indicators, badges, system Liquid Glass, and zoom transitions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/demo-options.webp) | | iOS 液态玻璃 | 机器人模糊 | Android 水龙头流 | 曲线标签栏 | | --- | --- | --- | --- | | ![iOS native Liquid Glass navbar and tabbar screenshot](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/native-liquid-glass-ios.webp) | ![Android native navbar and floating tabbar over page content blurred with CSS backdrop-filter, in the Mimesis app](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/android-mimesis-blur.webp) | ![Android recording of the Mimesis app: a large navbar title collapsing on scroll, a push transition with native back, and switching between three tabs](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/android-mimesis-flow.webp) | ![Android native curved tabbar with raised center camera action and side margin](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/native-screenshots/android-curved-tabbar.png) | Android的捕捉来自 [缩写](https://github.com/Cap-go/mimesis) 在Android 16上:一个在卷轴上倒塌的大型导航栏标题,一个半透明本地制式标签栏和一个覆盖 CSS 的透明导航栏 `backdrop-filter` 模糊不清。 模糊不清. ### iPhone 杜奥 被折叠了,在地貌中打开了,系统标签栏变成了一条垂直的铁路. 张开的肖像画保持水平栏. Split View将每个窗口的栏杆放入外缘. 铁路停留在相机的物理边缘上,因此语义边缘在地貌上走出后行走,可以在Split View和右到左的布局上走出后行走. 曲线中心栏会留在下方,而其摇篮会保持一圈环绕窗口拓宽时的按钮. 从导航栏的图标按钮 加入铁路。 文本标题保持水平, 因此需要背控 `display: 'icon'` (或 `role: 'close'`在它坐到铁路上方之前. `dock: 'detached'` 自己画个按钮. `dock: 'prominent'` 把它从溢出处取出. `axis: 'vertical'` 在栏杆上设置像Done这样的文字按钮。 共享的项目 `group` 崩溃到第一个项目,系统会扩展其余部分. `search.placement: 'button'` 是iOS 26中和后期iPhone Duo铁路上的一个脱开的搜索按钮. 一个水平导航器,Android,和Web保持了堆叠的字段. `verticalBarCompression: 'preferItems'` 铁路耗尽时保留导航按钮。 分行保持水平并清除铁路. 曲线等自定义的胶囊会留在底部,而中心按钮会保持一圈. `configure({ verticalBarBehavior: 'disabled' })` 选择屏幕关闭并保留上下行。 选择 `verticalBarBehavior` 之后保留目前的选择. `safeAreaChanged` 报告 `verticalBarEdge`折叠 `reservedRegions`,以及最新的链条样本. `verticalBarChanged` 财务报告和审定财务报表 `hingeChanged` 火当这些变化. ```ts await NativeNavigation.configure({ verticalBarBehavior: 'automatic' }); await NativeNavigation.setNavbar({ title: 'Notes', verticalBarCompression: 'preferItems', backButton: { visible: true, title: 'Back', display: 'icon' }, rightItems: [ { id: 'done', title: 'Done', dock: 'prominent', axis: 'vertical' }, { id: 'reply', title: 'Reply', icon: { ios: { sfSymbol: 'arrowshape.turn.up.left' } }, group: 'message' }, { id: 'forward', title: 'Forward', icon: { ios: { sfSymbol: 'arrowshape.turn.up.right' } }, group: 'message' }, ], search: { placement: 'button', placeholder: 'Search' }, }); ``` ```css .page { padding-inline-start: var(--cap-native-navigation-left); padding-inline-end: var(--cap-native-navigation-right); } ``` `--cap-native-navigation-division-x` 财务报告和审定财务报表 `--cap-native-navigation-division-width` 标记折叠,以便网页布局可以围绕折叠分割。 该插件仍然使用一个WebView. 在一个没有栏杆的电话上,这些嵌入变量是 `0px`。 。 。 . 在iOS 27.1的iPhone Duo模拟器上被捕获. | 折叠后,中间 | 打开, 中央 | 系统打开 | 折叠系统 | | --- | --- | --- | --- | | ![iPhone Duo simulator, folded: curved tab bar and a circular camera button stay on the bottom](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-folded-center.webp) | ![iPhone Duo simulator, open in landscape: the camera button stays a circle on the bottom bar](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-open-center.webp) | ![iPhone Duo simulator, open in landscape: system tab bar and navbar compose button in the vertical rail](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-open-system.webp) | ![iPhone Duo simulator, folded: system tab bar and navbar compose button in the vertical rail](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-folded-system.webp) | ![iPhone Duo simulator, open in portrait: navbar and system tab bar stay horizontal](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-open-portrait.webp) 铁路中带有导航控制功能的开放地貌. 后图标坐落在状态项目下,Done是一个突出的文本按钮,回复并转发共享一组,而搜索则是一个脱开的按钮. 系统标签停留在铁路下方. ![iPhone Duo simulator, open in landscape: back icon, prominent Done, grouped reply and forward, and a detached search button in the vertical rail](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/iphone-duo-open-dock.webp) ### 导航行 导航栏下多层本地分行:上方为瞄准镜切换器,下方为分节芯片. 见 [导航行](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-navbar-segment-rows-multi-level-top-bar)。 。 。 . | iOS系统 | 机器人 | | --- | --- | | ![iOS recording: tapping Account sections, switching to Organization swaps the second row to eight scrolling chips, selecting Billing](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/navbar-segments-ios.webp) | ![Android recording: segmented Account / Organization row over scrolling section chips, switching scope and selecting Billing](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/navbar-segments-android.webp) | ### 拉来拉去 接地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取 页面滚动是否有效 `window` 或内根,例如 `#app`。 。 。 . | iOS系统 | 机器人 | | --- | --- | | ![iOS native pull to refresh below the navbar](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/pull-to-refresh-ios.webp) | ![Android SwipeRefreshLayout pull to refresh below the navbar](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/pull-to-refresh-android.webp) | ```ts await NativeNavigation.setPullToRefresh({ enabled: true }); NativeNavigation.addListener('pullToRefresh', async () => { await reloadData(); await NativeNavigation.endPullToRefresh(); }); ``` ## 特征 - 从 JavaScript 状态驱动本地上下导航标签 . - 在导航栏下显示本地搜索域 `setNavbar({ search })`。它随大标题和报告而崩溃 `navbarSearch`。 。 。 . - 将浮动标签栏与起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站、起站. - 使用系统拥有的iOS导航条,分页条,分页手势,和液晶玻璃渲染. - 释放本地意图事件,例如 `navbarBack`, (中文(简体) ), `navbarItemTap`, (中文(简体) ), `navbarSearch`,以及 `tabSelect`。 。 。 . - 启用本地条的可选Android液体玻璃式半透明表面( 与 CSS 连接) `backdrop-filter` 以示模糊. - 抓取 WebView 的快照, 用于本地感的推, 后, 根, 标签, 并缩放转换 . - 配置标签标签、所选图标、徽章、指示器、波纹、锡色和动态颜色. - 写入 CSS inset 变量,这样网页内容就可以不被隐藏地滚动到本地栏后. - 在iPhone Duo上,跟随系统垂直铁路:导航器项目加入,安全区域清除,屏幕可以选择退出. - 在导航栏(镜像切换器外加分区标签)下堆放多级本地分区行 `setNavbar({ segments })`。 。 。 . - 直接进入原生的牵引至再生(iOS上的系统自旋器和随机性, `SwipeRefreshLayout` 在Android上), 与 `setPullToRefresh()`。 。 。 . - 隐藏导航栏和标签栏,同时打开一个网络模式、工作表或弹出符。 动画制表栏隐藏保留了iOS制表控制器和WebView. - 与React,Vue,Angular,Svelte,Solid,香草JS合作,以及任何暴露了必须通航的路由器. ## 选择表面 | 表面 | 用它来 | | --- | --- | | 导航栏搜索 | 在大标题下过滤页面, 如设置或库中. | | 分行 | 切换当前屏幕上的范围和部分. | | 浮动栏, 中间 | 默认的电话标签栏 . | | 浮动栏,开始或结束 | 一个短的酒吧坐在一边. | | 边栏 | 与iPad,iPhone Duo,和Android上一条有轨电车相同的标签. | | 曲线 | 一个底条 上面有个中心动作 其能住于下而为下. | ## 如何适应 - 您的路由器仍然拥有路由状态和页面渲染功能. - 该应用仍然使用一款全屏WebView. - 图标必须是SVG字符串,SF符号等可序列描述符,或者本地资源名. ## 模具、床单和弹珠 本地栏杆被绘制在WebView上方. 页面上的模式、工作表、对话框或弹出式(`ion-modal`, (中文(简体) ), `ion-popover`, (中文(简体) ), ``,菜单)使WebView内部,所以它停留在导航栏和标签栏下. 隐藏覆盖将遇到的每个栏目, 然后在覆盖关闭时再次发送相同的选项 。 在可以堆叠时数起打开的上方. 内在的解雇必须让酒吧藏起来 而外层的覆被还在上面. ```typescript let overlayCount = 0; let navbar = { title: 'Home', backButton: { visible: false }, }; let tabbar = { selectedId: 'home', tabs: [ { id: 'home', title: 'Home' }, { id: 'settings', title: 'Settings' }, ], }; async function suspendNativeChrome() { overlayCount += 1; if (overlayCount > 1) { return; } await NativeNavigation.setNavbar({ ...navbar, hidden: true }); await NativeNavigation.setTabbar({ ...tabbar, hidden: true, animated: true }); } async function resumeNativeChrome() { overlayCount = Math.max(0, overlayCount - 1); if (overlayCount > 0) { return; } await NativeNavigation.setNavbar({ ...navbar, hidden: false }); await NativeNavigation.setTabbar({ ...tabbar, hidden: false, animated: true }); } ``` 保留 `navbar` 财务报告和审定财务报表 `tabbar` 作为当前路径的选项,并更新到您已经拨打的同一位置 `setNavbar` 财务报告和审定财务报表 `setTabbar`调用 `suspendNativeChrome()` 在提交表前(`ionModalWillPresent`, (中文(简体) ), `ionPopoverWillPresent`,或者前面的行 `dialog.showModal()`) (中文(简体) ). 打电话 `resumeNativeChrome()` 在它消失之后`ionModalDidDismiss`, (中文(简体) ), `ionPopoverDidDismiss`对话框 `close` 活动). `setTabbar({ hidden: false })` 无 `tabs` 清除了酒吧。 传播您最后的选项并更改 `hidden`。 。 。 . 过 `animated: true` 在标签栏切换上 : - **iOS 26+系统 液态玻璃**,当 `shape` 没有 `curve` 财务报告和审定财务报表 `minimizeBehavior` 没有 `onScrollDown`。插件调用 `UITabBarController.setTabBarHidden(_:animated:)`。标签控制器保留挂载,WebView保留在其中。 UIKit淡出酒吧. `animated: false` 将WebView移回桥上 桥在模式自己的动画中运行. - **更早的iOS,曲线条,和最小相接相接胶囊.** 酒吧会淡出200多米 继续挂起. - **Android (英语).** 酒吧及其背景滑出并淡出超过200米,再离开布局. 让他们反弹 一会儿 `setTabbar` 在已可见的栏上,不会重放滑入. 导航屏的隐藏在iOS和Android上. `animated` 打开 `setNavbar` 适用于栏可见时的标题和按钮更改. 在调用解决时设置更新, 而 Tabbar 动画仍在运行中 : - 隐藏的导航栏集 `--cap-native-navigation-top` 财务报告和审定财务报表 `--cap-native-navbar-height` 改为 `0`。滚动链接的导航栏更改等下一个 `setNavbar` 显示酒吧. - 隐藏的 Android 标签栏集 `--cap-native-navigation-bottom` 财务报告和审定财务报表 `--cap-native-tabbar-height` 改为 `0`,所以上线可以使用栏所要离开的空间. - 在iOS 26+系统标签栏上, `--cap-native-tabbar-height` 已经 `0`:WebView在分页内托管,在栏下不扩展. 动画隐藏保存 `--cap-native-system-tabbar-height` 标称栏高(栏外加家用指示器垫)。 一个非活化的隐藏也降低了这个值,因为标签控制器不见了. 远离酒吧的爆米花可以放他们出来 隐藏标题下菜单的导航栏,以及覆盖屏幕下方的工作表的标签栏. `configure({ enabled: false })` 把铬主机关掉 使用 `hidden` 为一个覆盖。 在网络上没有本地栏;同样的调用仍然更新 CSS 内置变量. 在此 WebView 中保留模式 。 封面为页面状态,由路由器负责. ## 兼容性 `@capgo/capacitor-native-navigation` 目标Capacitor 8和Node.js 22+. iOS 27被支持,包括iPhone Duo. ## 安装 您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 : ```bash npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins ``` 然后使用下列提示: ```text Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-navigation` plugin in my project. ``` 如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令: ```bash npm install @capgo/capacitor-native-navigation npx cap sync ``` ## 最小使用量 ```typescript import { NativeNavigation } from '@capgo/capacitor-native-navigation'; await NativeNavigation.configure({ contentInsetMode: 'css', animationDuration: 360, }); await NativeNavigation.setNavbar({ title: 'Home', subtitle: 'Native chrome', transparent: true, scrollBehavior: 'both', scrollThreshold: 8, backButton: { visible: false }, rightItems: [ { id: 'compose', title: 'Compose', icon: { svg: '', }, }, ], }); await NativeNavigation.setTabbar({ selectedId: 'home', labelVisibilityMode: 'labeled', icons: true, colors: { dynamic: true, }, tabs: [ { id: 'home', title: 'Home', icon: { svg: '', }, }, { id: 'settings', title: 'Settings', icon: { svg: '', }, }, ], }); await NativeNavigation.addListener('tabSelect', ({ id }) => { router.navigate(`/${id}`); }); ``` ## 原生标签样式 ```typescript await NativeNavigation.setTabbar({ selectedId: 'home', labelVisibilityMode: 'selected', indicatorColor: '#0A84FF', rippleColor: '#330A84FF', badgeBackgroundColor: '#FF3B30', badgeTextColor: '#FFFFFF', colors: { dynamic: true, tint: '#0A84FF', inactiveTint: '#8E8E93', }, tabs: [ { id: 'home', title: 'Home', icon: { ios: { sfSymbol: 'house' }, android: { resource: 'ic_home' } }, selectedIcon: { ios: { sfSymbol: 'house.fill' }, android: { resource: 'ic_home_filled' } }, }, ], }); ``` ## Android 液体玻璃公司 在Android 12+上,浮动标签栏使用 `liquidGlass` 当 `setTabbar` 省略 `glass` (通过) `glass: { effect: 'none' }` 给一个平坦的填充。 Android绘制出一个半透明无活模糊的锡:将WebView从原生代码中渲染出来以模糊其闪出页面或吞入放出. 对于模糊,设置一个元素 `backdrop-filter: blur(...)` 在条下方的页面中(浮动标签栏高64px,从侧面取出24px,最宽处为430px,10px上方为系统导航栏). 调色板 `colors.background` 阿尔法和 `glass.surfaceAlpha` (默认) `0.62`一起来 当系统字体大小增加时,标签栏随标签行高而增长并报告 `tabbarHeight` / 底层插件与本地栏保持对齐 . ```typescript await NativeNavigation.configure({ glass: { effect: 'liquidGlass', blurRadius: 18, surfaceAlpha: 0.62, }, }); await NativeNavigation.setTabbar({ selectedId: 'home', tabs, colors: { background: '#F8FFFFFF', }, }); ``` ## 过渡流动 ```typescript const transition = await NativeNavigation.beginTransition({ direction: 'forward' }); router.navigate('/detail'); await router.ready?.(); await NativeNavigation.setNavbar({ title: 'Detail', backButton: { visible: true, title: 'Back' }, }); await NativeNavigation.finishTransition({ id: transition.id, direction: 'forward', }); ``` ## 使用@ capgo/ 电容器- 过渡 使用 `@capgo/capacitor-native-navigation` 用于本地导航、塔巴、安全区设置和本地意图事件。 使用 `@capgo/capacitor-transitions` 为WebView的页面堆放 在原生铬下. ```bash npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions npx cap sync ``` 应用程序启动时初始化两个软件包 : ```typescript import { NativeNavigation } from '@capgo/capacitor-native-navigation'; import '@capgo/capacitor-transitions'; import { initTransitions, setupRouterOutlet, setDirection } from '@capgo/capacitor-transitions/react'; initTransitions({ platform: 'auto' }); const outlet = document.querySelector('cap-router-outlet'); if (outlet) { setupRouterOutlet(outlet, { platform: 'auto', swipeGesture: 'auto' }); } await NativeNavigation.configure({ contentInsetMode: 'css', }); ``` 使过渡输出集中在页面上。 当原生铬拥有这些表面时,不要制作网眉或页脚: ```html
Inbox content
 ``` ```css .page { min-height: 100dvh; padding-top: var(--cap-native-navigation-top); padding-bottom: var(--cap-native-navigation-bottom); } ``` 从相同的路由器动作驱动两个软件包 : ```typescript async function openMessage(id: string) { setDirection('forward'); await router.push(`/messages/${id}`); await NativeNavigation.setNavbar({ title: 'Message', backButton: { visible: true, title: 'Inbox' }, }); } await NativeNavigation.addListener('navbarBack', () => { setDirection('back'); router.back(); }); await NativeNavigation.addListener('tabSelect', ({ id }) => { setDirection('root'); router.push(`/${id}`); }); ``` 每个导航选择一个动画层. 对于正常的路线推,让我们 `@capgo/capacitor-transitions` 激活 WebView 页面并更新本地条 `setNavbar` 编号 : `setTabbar`。用于共享元素或缩放路径 `beginZoomTransition` 编号 : `finishZoomTransition` 从此插件中跳过该导航的网页过渡 . ## 滚动驱动导航栏 每个屏幕上显示 `setNavbar({ scrollBehavior: 'both' })`。默认保留 `none`,因此现有的应用保持静态铬. 原生 iOS 和 Android 听滚动 `window`, (中文(简体) ), `#app`,并带有 `data-cap-native-navigation-scroll`启用 `reportNavbarScroll()` 仅用于自定义滚动根. 例应用路由 **滚动页眉演示** (家用平板)显示长列表 `scrollBehavior: 'both'`. . . . . 向上滚动,在名单到达顶部之前把它带回. | 安静 | 隐藏,然后揭示 | | --- | --- | | ![iPhone 17 simulator: navbar stays visible over the top of a long list](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/media/scroll-header.webp) | ![iPhone 17 simulator: the navbar is hidden after the list scrolls down](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/media/scroll-header-demo.webp) | ## 导航栏搜索 过 `search` 改为 `setNavbar` 在栏下和任何分行上划出一个原生地。 该行为iOS上52pt和Android上52dp,而该高被包含在上位入位. iOS使用一个 `UISearchBar`。Android使用文本字段。 网页预览画出页面上方相同的字段. `hidesWhenCollapsed` 默认为 `true` 当导航器是大标题时。 一旦标题倒塌,行高会变成0,而顶部的入位会随之收缩. 在网络预览中,当滚动行为崩溃了栏时,字段会与导航栏一起隐藏. 大标题倒塌本身是本土的. ```typescript import { NativeNavigation } from '@capgo/capacitor-native-navigation'; let query = ''; const renderNavbar = () => NativeNavigation.setNavbar({ title: 'Settings', large: true, search: { placeholder: 'Search', text: query, hidesWhenCollapsed: true, }, }); await NativeNavigation.addListener('navbarSearch', async ({ text, reason }) => { query = reason === 'cancel' ? '' : text; await renderNavbar(); }); await renderNavbar(); ``` 发送最新消息 `text` 下一个 `setNavbar` 因此,现场保持同步。 领域重点突出,但没有变化 `text` 独自一人 在iOS和Android上,省略 `search` 删除字段。 网络执行保留上一个 `search` 调用省略时的对象, 因此通过 `search: { hidden: true }` 在那里也清理干净. 实例 **设置** 选项卡使用此字段过滤一个集成列表,其外观控制在光、暗和系统方案之间切换演示。 这个 **导航** 游乐场有一个 **搜索字段** 切换. iPhone 17模拟器, iOS 27.0. ![Settings search under the large title, light appearance](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/navbar-search-light.webp) ![Settings search under the large title, dark appearance](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/navbar-search-dark.webp) ## 标签栏位置和对齐 `style.alignment` 在水平边距内放置浮动栏: `start`, (中文(简体) ), `center` (默认),或 `end`。 。 。 . `start` 财务报告和审定财务报表 `end` 跟着 `layoutDirection`。曲线栏和侧边栏杆忽略了对齐. `style.placement` 选择铬 : - `auto` 让iOS 18 和新的决定。 压缩 iPhone 留在底部. iPad和iPhone Duo可以使用后导侧边栏. - `bottom` 保持一个底条. - `sidebar` 要求有轨电车。 在iOS 18上,以及更新的,即侧边栏模式下的系统标签栏,包括iOS 18至25上. iPad肖像显示该模式为带有侧边栏按钮的上标签栏. 当 UIKit 不提供侧边栏时,紧凑的 iPhone 可以留在下方 。 Android绘制了84dp的铁路,从后行边缘插入了12dp,从通航道下方开始. 导航栏保持全宽. 网页预览报告的是相同的左或右设置 . `curve` 总是留在底部. `sidebar` 忽略 `minimizeBehavior` 并拖动到选择. ```typescript await NativeNavigation.setTabbar({ tabs, selectedId: 'home', style: { shape: 'floating', alignment: 'end', placement: 'bottom', }, }); await NativeNavigation.setTabbar({ tabs, selectedId: 'home', style: { shape: 'floating', placement: 'sidebar', }, }); ``` 实例 **标签栏** 游乐场和 **设置** 选项卡同时显示对齐和位置。 纸页内容 `--cap-native-navigation-left` 财务报告和审定财务报表 `--cap-native-navigation-right` 所以铁路不能覆盖它. iPad Pro 11英寸模拟器 iOS 27.0. 对齐移动浮动胶囊;iOS 26系统标签栏不移动. 侧边栏设置使用UIKit上方的标签栏和侧边栏按钮. ![iPad: floating tab bar aligned to the start](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/tabbar-alignment-start.webp) ![iPad: sidebar placement shows the system top tab bar and sidebar button](https://npmcn.com/package/%40capgo/capacitor-native-navigation/docs/tabbar-sidebar.webp) ## Navbar 段行( 多级别上行) 过 `segments` 改为 `setNavbar` 在栏下堆放原生部分的行,例如上方的瞄准镜切换器和下方的分区标签。 行从上到下地画出,每行会给导航栏和所报道的套接字增加44pt(iOS)或48dp(Android). iOS 用途 `UISegmentedControl` / 玻璃药丸,Android使用材料分出按钮和过滤芯片. ```typescript import { NativeNavigation } from '@capgo/capacitor-native-navigation'; const sections = { account: ['General', 'Notifications', 'Password', 'Two-factor'], organization: ['General', 'Members', 'Plans', 'Usage', 'Credits', 'Billing', 'Security', 'Webhooks'], }; const selection = { scope: 'account', section: 'general' }; const renderNavbar = () => NativeNavigation.setNavbar({ title: 'Settings', segments: [ { id: 'scope', selectedId: selection.scope, items: [ { id: 'account', title: 'Account' }, { id: 'organization', title: 'Organization' }, ], }, { id: 'section', style: 'scroll', // horizontally scrolling chips; `auto` picks `segmented` for up to 4 items selectedId: selection.section, items: sections[selection.scope].map((title) => ({ id: title.toLowerCase(), title })), }, ], }); await NativeNavigation.addListener('navbarSegmentSelect', async ({ groupId, id }) => { if (groupId === 'scope') { selection.scope = id; selection.section = 'general'; // the second level depends on the first one } else { selection.section = id; } await renderNavbar(); }); await renderNavbar(); ``` 用户点击时选择本地移动, 但每次 `setNavbar` 调用应用 `selectedId` 再来一次 将选中的ID保存在您所在的状态, 并每隔一段时间传递 `setNavbar` 调用; 要拒绝选择, 请发送上一个 `selectedId`。接受的项目 `icon`, (中文(简体) ), `accessibilityLabel` 财务报告和审定财务报表 `enabled` 就像导航按钮 过 `segments: []` 删除行. 例应用 **导航** 游乐场有一个 **分行** 切换与这个精确的设置. ## 缩放过渡 ```typescript import { beginZoomTransition, finishZoomTransition } from '@capgo/capacitor-native-navigation'; const card = document.querySelector('[data-photo-card]'); if (card) { const transition = await beginZoomTransition(card, { cornerRadius: 18 }); router.navigate('/photo/42'); await router.ready?.(); await finishZoomTransition(undefined, { id: transition.id, cornerRadius: 18, }); } ``` ## CSS 设置 与 `contentInsetMode: 'css'`,插件在 `document.documentElement`数字 : ```css .app-scroll { height: 100dvh; overflow: auto; padding-top: calc(var(--cap-native-navigation-top) + 24px); padding-left: var(--cap-native-navigation-left); padding-right: var(--cap-native-navigation-right); scroll-padding-bottom: calc(var(--cap-native-navigation-bottom) + 24px); } .page { min-height: 100dvh; padding-bottom: calc(var(--cap-native-navigation-bottom) + 24px); } ``` 可用变量 : - `--cap-native-navigation-top` - `--cap-native-navigation-right` - `--cap-native-navigation-bottom` - `--cap-native-navigation-left` - `--cap-native-navbar-height` - `--cap-native-tabbar-height` - `--cap-native-system-tabbar-height` (名义标签栏高;当 `--cap-native-tabbar-height` 实值 `0` 用于主机系统栏). 在iPhone Duo铁路上,这是铁路厚度,重叠是 `--cap-native-navigation-left` 或者说 `--cap-native-navigation-right`。 。 。 . - `--cap-native-navigation-vertical-bar-edge` (单位:千美元)`leading`, (中文(简体) ), `trailing`,或为空) - `--cap-native-navigation-division-x` 财务报告和审定财务报表 `--cap-native-navigation-division-width` (折叠,或 `0px`(中文(简体) ) ## Web 组件 软件包可以为框架不可知声明设置注册可选自定义元素 : ```typescript import { defineNativeNavigationElements } from '@capgo/capacitor-native-navigation'; defineNativeNavigationElements(); ``` ```html ``` ## 图标描述符 ```typescript const icon = { svg: '', width: 24, height: 24, template: true, src: 'shared_asset_name', ios: { svg: '', sfSymbol: 'house.fill', image: 'BundledAssetName', }, android: { svg: '', resource: 'ic_menu_view', image: 'bundled_drawable_name', }, }; ``` Inline SVG 支持Lucide 和 Feather等常见集使用的以图标为焦点的子集: `path`, (中文(简体) ), `line`, (中文(简体) ), `polyline`, (中文(简体) ), `polygon`, (中文(简体) ), `circle`,以及 `rect`。 SVG 默认作为模板图像提供,所以本地的锡克颜色可以在不捆绑平台资产的情况下重新显示. ## 平台说明 - iOS 使用 UIKit `UINavigationBar`, (中文(简体) ), `UISearchBar`, (中文(简体) ), `UITabBar`,以及 `UITabBarController` 因此系统拥有标签交互,液晶渲染,侧边栏放置于iOS 18+,以及安全区域行为. - Android 使用 Appcompat 软件 `Toolbar`,该工具栏下的文本字段,以及本地标签表面。 侧杆布置是一条有后遗症的铁路. 导航栏保持全宽. - Web 镜像 内置变量,搜索字段,侧边栏设置,浮边对齐,以及用于本地开发的事件. ## 示例应用 这个 `example-app/` 文件夹是连接到 `file:..`。 。 。 . ```bash cd example-app npm install npm run build npx cap add ios npx cap add android npx cap sync ``` ## API 密码 - [`configure(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-configure) - [`setNavbar(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-setnavbar) - [`reportNavbarScroll(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-reportnavbarscroll) - [`setPullToRefresh(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-setpulltorefresh) - [`endPullToRefresh()`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-endpulltorefresh) - [`setTabbar(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-settabbar) - [`beginTransition(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-begintransition) - [`finishTransition(...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-finishtransition) - [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-getpluginversion) - [`addListener('navbarBack', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenernavbarback-) - [`addListener('navbarItemTap', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenernavbaritemtap-) - [`addListener('navbarSearch', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenernavbarsearch-) - [`addListener('navbarSegmentSelect', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenernavbarsegmentselect-) - [`addListener('tabSelect', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenertabselect-) - [`addListener('safeAreaChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenersafeareachanged-) - [`addListener('verticalBarChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenerverticalbarchanged-) - [`addListener('hingeChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenerhingechanged-) - [`addListener('transitionStart', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenertransitionstart-) - [`addListener('transitionEnd', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenertransitionend-) - [`addListener('pullToRefresh', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-addlistenerpulltorefresh-) - [接口](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-interfaces) - [类型异名](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-type-aliases) 框架-不可知 本土导航 铬 API. ### 配置(...) ```typescript configure(options?: NativeNavigationConfigureOptions | undefined) => Promise ``` 配置原生铬主机和内容内置行为. | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationConfigureOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationconfigureoptions)` | **回返情况:** `Promise<[NativeNavigationInsetsResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationinsetsresult)>` * * * ### 设置Navbar(...) ```typescript setNavbar(options: NativeNavigationNavbarOptions) => Promise ``` 渲染或更新本土导航. | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationNavbarOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationnavbaroptions)` | **回返情况:** `Promise<[NativeNavigationInsetsResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationinsetsresult)>` * * * ### 报告 NavbarScroll(...) ```typescript reportNavbarScroll(options: NativeNavigationNavbarScrollEvent) => Promise ``` 报告滚动样本 `scrollBehavior`。仅用于滚动根 尚未通过 `setNavbar` (单位:千美元)`window`, (中文(简体) ), `#app`,或 `[data-cap-native-navigation-scroll]`). iOS,Android,和网络倒置 启用滚动时自动安装这些听众. | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationNavbarScrollEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationnavbarscrollevent)` | * * * ### 设置 PullTrefresh (...) ```typescript setPullToRefresh(options: NativeNavigationPullToRefreshOptions) => Promise ``` 启用或禁用本地拉到新鲜的手势 。 听着 `pullToRefresh`,然后调用 `endPullToRefresh()` 隐藏 旋转器。 网络上没有. | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationPullToRefreshOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationpulltorefreshoptions)` | **自:** 8.11.0 (中文(简体) ) * * * ### 结束PullTrefresh () ```typescript endPullToRefresh() => Promise ``` 刷新完成后停止原生回旋器. **自:** 8.11.0 (中文(简体) ) * * * ### 设置 Tab 栏(...) ```typescript setTabbar(options: NativeNavigationTabbarOptions) => Promise ``` 渲染或更新本地标签栏 . | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationTabbarOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtabbaroptions)` | **回返情况:** `Promise<[NativeNavigationInsetsResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationinsetsresult)>` * * * ### 开始转换(...) ```typescript beginTransition(options?: NativeNavigationBeginTransitionOptions | undefined) => Promise ``` 抓取当前 WebView 并准备本地转换 . | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationBeginTransitionOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationbegintransitionoptions)` | **回返情况:** `Promise<[NativeNavigationTransitionResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtransitionresult)>` * * * ### 完成过渡(...) ```typescript finishTransition(options?: NativeNavigationFinishTransitionOptions | undefined) => Promise ``` 从抓取的"WebView快照"到当前"WebView"直播的动画. | 参数 | 类型 | | --- | --- | | **`options`** | `[NativeNavigationFinishTransitionOptions](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationfinishtransitionoptions)` | **回返情况:** `Promise<[NativeNavigationTransitionResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtransitionresult)>` * * * ### 获取 PluginVersion () ```typescript getPluginVersion() => Promise ``` 返回平台执行版本标记 . **回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginversionresult)>` * * * ### 添加聆听器( “ 导航备份 ” ).. ```typescript addListener(eventName: 'navbarBack', listenerFunc: (event: NativeNavigationBackEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'navbarBack'` | | **`listenerFunc`** | `(event: [NativeNavigationBackEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationbackevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 导航项目Tap ” ,...) ```typescript addListener(eventName: 'navbarItemTap', listenerFunc: (event: NativeNavigationBarItemTapEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'navbarItemTap'` | | **`listenerFunc`** | `(event: [NativeNavigationBarItemTapEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationbaritemtapevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加 listener('navbarSearch', ) , (...) ```typescript addListener(eventName: 'navbarSearch', listenerFunc: (event: NativeNavigationNavbarSearchEvent) => void) => Promise ``` 当导航器搜索字段改变时被发射. | 参数 | 类型 | | --- | --- | | **`eventName`** | `'navbarSearch'` | | **`listenerFunc`** | `(event: [NativeNavigationNavbarSearchEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationnavbarsearchevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` **自:** 8.14.0 (中文(简体) ) * * * ### 添加倾听器( “ 导航组件选择 ” ,...) ```typescript addListener(eventName: 'navbarSegmentSelect', listenerFunc: (event: NativeNavigationNavbarSegmentSelectEvent) => void) => Promise ``` 当用户在 navbar 段行中选择项目时被解除 . | 参数 | 类型 | | --- | --- | | **`eventName`** | `'navbarSegmentSelect'` | | **`listenerFunc`** | `(event: [NativeNavigationNavbarSegmentSelectEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationnavbarsegmentselectevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` **自:** 8.13.0 (韩语) * * * ### 添加收听器( 无法选择),.. ```typescript addListener(eventName: 'tabSelect', listenerFunc: (event: NativeNavigationTabSelectEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'tabSelect'` | | **`listenerFunc`** | `(event: [NativeNavigationTabSelectEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtabselectevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加 listener( “ 安全区更改 ” ,...) ```typescript addListener(eventName: 'safeAreaChanged', listenerFunc: (event: NativeNavigationSafeAreaChangedEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'safeAreaChanged'` | | **`listenerFunc`** | `(event: [NativeNavigationSafeAreaChangedEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationsafeareachangedevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 垂直Bar Changed ” ,...) ```typescript addListener(eventName: 'verticalBarChanged', listenerFunc: (event: NativeNavigationVerticalBarChangedEvent) => void) => Promise ``` 当iPhone Duo垂直铁路出现、消失或改变时被发射 边缘. `safeAreaChanged` 在每个插件更新时带相同的边缘. | 参数 | 类型 | | --- | --- | | **`eventName`** | `'verticalBarChanged'` | | **`listenerFunc`** | `(event: [NativeNavigationVerticalBarChangedEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationverticalbarchangedevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` **自:** 8.14.0 (中文(简体) ) * * * ### 添加倾听器( “ hinge Changed ” ,...) ```typescript addListener(eventName: 'hingeChanged', listenerFunc: (event: NativeNavigationHingeChangedEvent) => void) => Promise ``` 当 iPhone Duo 链条发生变化时, 或当 链条更新停止时, 解除 . 偏爱 `hinge.status` 结束 `hinge.angle` 当一个粗糙的姿势足够. | 参数 | 类型 | | --- | --- | | **`eventName`** | `'hingeChanged'` | | **`listenerFunc`** | `(event: [NativeNavigationHingeChangedEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationhingechangedevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` **自:** 8.14.0 (中文(简体) ) * * * ### 添加倾听器( “ 过渡开始 ” ).. ```typescript addListener(eventName: 'transitionStart', listenerFunc: (event: NativeNavigationTransitionEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'transitionStart'` | | **`listenerFunc`** | `(event: [NativeNavigationTransitionEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtransitionevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 过渡结束 ” ).. ```typescript addListener(eventName: 'transitionEnd', listenerFunc: (event: NativeNavigationTransitionEvent) => void) => Promise ``` | 参数 | 类型 | | --- | --- | | **`eventName`** | `'transitionEnd'` | | **`listenerFunc`** | `(event: [NativeNavigationTransitionEvent](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationtransitionevent)) => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ pill Torefresh' ,...) ```typescript addListener(eventName: 'pullToRefresh', listenerFunc: () => void) => Promise ``` 用户拉出刷新时被解除. 旋转器一直旋转到 `endPullToRefresh()` 名为. | 参数 | 类型 | | --- | --- | | **`eventName`** | `'pullToRefresh'` | | **`listenerFunc`** | `() => void` | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-pluginlistenerhandle)>` **自:** 8.11.0 (中文(简体) ) * * * ### 接口 #### 原生导航集 通过可能改变安全内容界限的方法返回. | Prop | 类型 | | --- | --- | | **`insets`** | `[NativeNavigationInsets](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationinsets)` | #### 原生导航集 被网络内容所曝光的套接字. | Prop | 类型 | 说明 | 自兹 | | --- | --- | --- | --- | | **`top`** | `number` | | | | **`right`** | `number` | | | | **`bottom`** | `number` | | | | **`left`** | `number` | | | | **`navbarHeight`** | `number` | | | | **`tabbarHeight`** | `number` | 当 WebView 尚未为本地标签栏保留空间时, 网络布局的下部重叠设置 。 在 iOS 26+ 上使用系统托管的标签栏保留此选项 `0` 所以内容不会被解除两次. | | | **`systemTabbarHeight`** | `number` | 名义上的本地标签栏高度( 栏外加在 iOS 上贴上的家庭指示器) , 即使 `tabbarHeight` 实值 `0`。在标签栏软藏时保留可用 `setTabbar({ hidden: true, animated: true })`。 。 。 . | | | **`verticalBarEdge`** | `[NativeNavigationVerticalBarEdge](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationverticalbaredge) | null` | 纵向铁路的语义边缘,或 `null` 当栏是横向的。 在铁路上, `left` 或者说 `right` 带起铁道厚度 `tabbarHeight` 留下来 `0` 当WebView已经身后. `systemTabbarHeight` 是厚度而不是底条. | 8.14.0 (中文(简体) ) | | **`reservedRegions`** | `NativeNavigationReservedRegion[]` | 由 iOS 所报告,在根视图的分点上被折叠和封存矩形. 当设备没有保留区域时空出 . | 8.14.0 (中文(简体) ) | | **`hinge`** | `[NativeNavigationHinge](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationhinge) | null` | 最新链条样本. `null` 当设备没有链条时。 角度更新在 `hingeChanged` 而不是在每一个滴滴上通过这个快照. | 8.14.0 (中文(简体) ) | #### 原生保留区 一个区域iOS保留在窗口内部,如折叠或被封入. | Prop | 类型 | | --- | --- | | **`kind`** | `'division' | 'occlusion'` | | **`x`** | `number` | | **`y`** | `number` | | **`width`** | `number` | | **`height`** | `number` | | **`active`** | `boolean` | #### 本地导航Hinge iPhone Duo连接样本. `angle` 这是弧度. | Prop | 类型 | | --- | --- | | **`angle`** | `number` | | **`status`** | `'unknown' | 'closed' | 'partiallyOpen' | 'fullyOpen'` | #### 本地导航配置选项 全局插件配置 . | Prop | 类型 | 说明 | 自兹 | | --- | --- | --- | --- | | **`enabled`** | `boolean` | 启用或禁用原生铬主机. | | | **`platformStyle`** | `[NativeNavigationPlatformStyle](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationplatformstyle)` | 本地风格偏好. `auto` 使用当前平台. | | | **`contentInsetMode`** | `[NativeNavigationContentInsetMode](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationcontentinsetmode)` | 何时 `css`,插件在 `document.documentElement`。 。 。 . | | | **`animationDuration`** | `number` | 默认本地转换持续时间以毫秒计 . | | | **`colors`** | `[NativeNavigationColors](https://npmcn.com/package/%40capgo/capacitor-native-navigation/#readme-nativenavigationcolors)` | 本地条的共享颜色提示 . | | ## 常见问题 ### @capgo/capacitor-native-navigation 是什么？ 本地导航、标签栏、安全区处理和WebView快照转换的电容插件\. ### 如何安装 @capgo/capacitor-native-navigation？ 在项目目录运行 npm install @capgo/capacitor-native-navigation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @capgo/capacitor-native-navigation 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @capgo/capacitor-native-navigation 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @capgo/capacitor-native-navigation 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @capgo/capacitor-native-navigation 可以商用吗？ @capgo/capacitor-native-navigation 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。 ### @capgo/capacitor-native-navigation 的下载量有多少？ 根据 npm 官方下载统计，@capgo/capacitor-native-navigation 在 2026/10/09 – 2026/11/07 这 30 天内被下载 72,012 次，日均约 2,400 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @capgo/capacitor-native-navigation 还在维护吗？ 最新版本 8\.16\.1 发布于 2026/11/04（4 天前）；至今共发布 66 个版本，其中过去 12 个月发布了 66 个；首次发布于 2026/05/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。