Onsen UI和Framework7都是老牌的混合应用UI框架，两者都提供了接近原生应用的组件体验，也都支持React。不过在长期的项目维护中，不少团队发现Framework7在组件丰富度、文档完整性和社区活跃度上更有优势，于是产生了迁移的需求。迁移并不是简单地替换标签名，两套框架在组件API、路由体系和样式定制方式上都有差异，需要有一套清晰的对应关系和迁移策略。本文将从组件映射、路由改造、样式定制和构建配置四个方面，完整讲解迁移过程中要做的事情。
一、组件体系对比与映射关系
Onsen UI的React组件以<Page>、<Toolbar>、<List>为核心，命名上更贴近原生概念。Framework7的React组件则以<f7-page>这样的前缀风格为主，实际上Framework7 React版本直接使用<Page>等大写组件名，但属性命名遵循Framework7自身的约定，比如页面生命周期钩子从Onsen UI的renderToolbar变成了Framework7的pageContent相关事件。
迁移的第一步是建立组件映射表。常见的对应关系包括：Onsen UI的<Page>对应Framework7的<Page>，<Toolbar>对应<Navbar>，<List>和<ListItem>对应<List>和<ListItem>，<Dialog>对应<Dialog>但属性差异较大，<Navigator>则被路由体系整体取代，这一点后面会详细说。
需要注意的坑是事件回调的参数结构。Onsen UI的按钮点击回调直接是原生事件对象，而Framework7很多组件回调的第一个参数是组件实例，第二个才是事件对象。迁移时要逐个检查回调里的取值逻辑，否则会出现点击无反应或者报undefined的情况。
二、路由机制的彻底改造
这是迁移工作量最大的部分。Onsen UI使用自己的Navigator进行页面栈管理，代码里常见这样的写法：
import { Navigator } from 'react-onsenui';
function App() {
return (
<Navigator
initialRoute={{ component: HomePage, props: {} }}
renderPage={(route, navigator) => (
<route.component navigator={navigator} {...route.props} />
)}
/>
);
}Framework7则内置了完整路由，配置方式和主流前端路由更接近。页面栈由路由历史自动管理，不再需要手动push组件：
import Framework7 from 'framework7/framework7-lite.esm.js';
import f7react from 'framework7-react';
const routes = [
{ path: '/', component: HomePage },
{ path: '/detail/:id', component: DetailPage },
];
function App() {
return (
<App params={{ routes }}>
<View url="/" />
</App>
);
}改造建议是先把所有navigator.pushPage调用替换成f7.views.current.router.navigate，把popPage替换成router.back。页面间的参数传递从props改为路由参数或query，如果原来有复杂对象传递，可以引入一个简单的全局store来承接。另外Framework7支持通过componentUrl异步加载页面组件，对大项目做按需加载很友好，迁移时可以顺便做代码分割。
还有一个容易被忽略的差异：Onsen UI的页面切换动画是iOS和Material两套，Framework7同样有这个概念，但它叫iOS和MD主题，通过theme参数指定。如果你的应用原来根据平台动态切换主题，要把Onsen的平台检测逻辑换成Framework7的Framework7.device相关API，或者直接依赖它的自动检测。
三、样式定制方式的迁移
Onsen UI的样式定制主要靠覆盖它提供的CSS类名，加上少量的ons.platform相关属性。Framework7走的是CSS变量和LESS/SASS定制的路线，灵活度更高。迁移时要做三件事。
第一件事是引入样式源码定制。如果项目用了SASS，推荐引入Framework7的SCSS源文件后修改变量：
// 修改主色调和圆角 $themeColor: #ff6b00; $f7NavbarHeight: 56px; @import 'framework7/framework7-bundle'; @import 'framework7/css/components/vars';
第二件事是清理Onsen UI遗留的样式覆盖。很多项目里积累了针对.toolbar-button、.list-item这类Onsen类名的覆盖样式，这些类名在Framework7中不存在，留着会污染全局。建议全局搜索ons相关类名前缀，逐一删除或改写成Framework7的对应类名。
第三件事是处理图标。Onsen UI默认使用Ionicons，Framework7默认使用自己的Framework7 Icons。图标库不通用，需要建立图标名称对照表批量替换，或者干脆在Framework7里配置继续使用Ionicons，后者改动量更小：
<App
params={{
icon: 'mdi',
routes,
}}
>四、构建配置与依赖清理
依赖层面的迁移比较直接。先移除react-onsenui和onsenui两个包，再安装framework7和framework7-react。如果用的是Vite或Webpack，基本不需要额外配置，Framework7的ES模块版本可以正常被tree-shaking处理。
需要注意的是Framework7有完整版和lite版的区别。lite版去掉了router之外的一些重模块，体积更小，如果你的应用不需要用到它的某些高级组件，可以选用framework7-lite.esm.js入口，包体积能减少不少。同时记得在构建配置里确认babel插件是否处理了JSX中Framework7组件的引入方式，官方推荐使用自动导入插件来减少手动import的样板代码。
最后是渐进式迁移策略。如果项目页面太多，一次性迁移风险高，可以利用Framework7支持多个View的特性，先把一整个业务模块切过去，新旧框架通过自定义事件或状态管理库通信，跑稳定后再切下一个模块。虽然两套UI库同时运行会增加包体积，但作为过渡方案是值得的。迁移完成后，重点回归测试页面切换动画、物理返回键行为和iOS安全区适配这三个最容易出问题的点，确保用户体验没有退化。
ReactOnsen UIFramework7修改时间：2026-09-16 14:40:43