@winner-fed/plugin-mobile-layout

适配移动端开发时的布局，适用于 Vue3。

功能特性

• 🚀 开箱即用 - 零配置快速搭建移动端应用
• 📱 移动端优化 - 专为移动端设计的完整布局系统
• 🎨 主题切换 - 支持明暗主题模式
• 🧭 导航组件 - 完整的顶部导航栏和底部标签栏
• 🔄 路由缓存 - 集成 KeepAlive 支持页面缓存
• 📐 安全区域适配 - 支持刘海屏等安全区域适配
• 🎯 TypeScript 支持 - 完整的类型定义
• 📦 基于 Vant - 使用 Vant 4.x 作为 UI 组件库
• ⚡ 插件化架构 - 基于 WinJS 插件系统

安装

npm install @winner-fed/plugin-mobile-layout --save-dev
# 或者
yarn add @winner-fed/plugin-mobile-layout
# 或者
pnpm add @winner-fed/plugin-mobile-layout

在 WinJS 中启用

在 .winrc.ts 配置文件中添加插件：

export default {
  plugins: [
    '@winner-fed/plugin-mobile-layout',
  ],
  mobileLayout: {
    // 配置选项
  }
};

基本使用

1. 安装依赖

npm install vant@^4.6.5

2. 在 app.ts 中配置

import type {
  NavBarListItem,
  NavBarProps,
  TabBarItem,
  TabBarProps,
  TitleListItem,
} from 'winjs';
import Vant from 'vant';
import 'vant/lib/index.css';

export function onMounted({ app }) {
  app.use(Vant);
}

// 页面标题配置
const titleList: TitleListItem[] = [
  {
    pagePath: '/home',
    title: '首页',
  },
  {
    pagePath: '/user',
    title: '用户中心',
  },
];

// 顶部导航栏配置
const navList: NavBarListItem[] = [
  {
    pagePath: '/home',
    navBar: {
      leftContent: '返回',
    },
  },
  {
    pagePath: '/user',
    navBar: {
      hideNavBar: false,
    },
  },
];

const navBar: NavBarProps = {
  navList,
  fixed: true,
  mode: 'light',
  onLeftClick: (router: any) => {
    router.goBack();
  },
};

// 底部标签栏配置
const tabList: TabBarItem[] = [
  {
    pagePath: '/home',
    text: '首页',
    icon: 'home-o',
    selectedIcon: 'home-o',
    title: '首页',
  },
  {
    pagePath: '/user',
    text: '用户',
    icon: 'user-o',
    selectedIcon: 'user-o',
    title: '用户中心',
    badge: '3',
  },
];

const tabBar: TabBarProps = {
  color: '#7d7e80',
  selectedColor: '#1989fa',
  tabBarItem: tabList,
};

// 导出移动端布局配置
export const mobileLayout = {
  theme: 'light',
  documentTitle: 'My App',
  navBar,
  titleList,
  tabBar,
};

配置选项

MobileLayoutProps

interface MobileLayoutProps {
  theme?: 'dark' | 'light';        // 主题模式
  tabBar?: TabBarProps;            // 底部标签栏配置
  navBar?: NavBarProps;            // 顶部导航栏配置
  documentTitle?: string;          // 默认文档标题
  titleList?: TitleItems[];        // 页面标题列表
}

TabBarProps

interface TabBarProps {
  fixed?: boolean;                 // 是否固定在底部
  color?: string;                  // 未选中颜色
  selectedColor?: string;          // 选中颜色
  tabBarItem?: TabBarItem[];       // 标签项列表
  tabBeforeChange?: (navigator: any, name: number | string) => void | Promise<boolean>;
  tabChange?: (navigator: any, name: number | string) => void;
}

TabBarItem

interface TabBarItem {
  pagePath: string;                // 页面路径
  text?: string;                   // 标签文本
  iconPath?: string;               // 图标路径
  selectedIconPath?: string;       // 选中图标路径
  icon?: string;                   // 图标名称
  selectedIcon?: string;           // 选中图标名称
  dot?: boolean;                   // 是否显示小红点
  badge?: number | string;         // 徽标数字
  title?: string;                  // 页面标题
  onPress?: (navigator: any, data?: TabBarItem) => void | Promise<boolean>;
}

NavBarProps

interface NavBarProps {
  fixed?: boolean;                 // 是否固定在顶部
  mode?: 'dark' | 'light';         // 主题模式
  icon?: object | string;          // 左侧图标
  leftText?: string;               // 左侧文本
  leftContent?: any;               // 左侧自定义内容
  rightContent?: any;              // 右侧自定义内容
  onLeftClick?: (navigator: any) => void;  // 左侧点击事件
  hideNavBar?: boolean;            // 是否隐藏导航栏
  pageTitle?: string;              // 页面标题
  navList?: NavBarListItem[];      // 导航列表
}

高级用法

1. 自定义图标组件

import UserIcon from '@/components/UserIcon.vue';

const tabList: TabBarItem[] = [
  {
    pagePath: '/user',
    text: '用户',
    icon: UserIcon,           // 使用自定义组件
    selectedIcon: UserIcon,
    title: '用户中心',
  },
];

2. 动态更新导航栏

import { setPageNavBar } from 'winjs';

// 在组件中动态更新导航栏配置
setPageNavBar([
  {
    pagePath: '/current-page',
    navBar: {
      pageTitle: '新标题',
      rightContent: '保存',
    },
  },
]);

3. 标签栏自定义点击事件

const tabList: TabBarItem[] = [
  {
    pagePath: '/custom',
    text: '自定义',
    icon: 'setting-o',
    onPress: async (navigator, data) => {
      // 自定义点击逻辑
      const result = await showConfirmDialog();
      if (result) {
        navigator.push('/custom-page');
      }
      return false; // 阻止默认导航
    },
  },
];

4. 主题切换

export const mobileLayout = {
  theme: 'dark', // 使用深色主题
  // ... 其他配置
};

样式定制

插件会自动添加以下 CSS 变量和样式：

html {
  --win-safe-area-top: env(safe-area-inset-top);
  --winjs-safe-area-bottom: env(safe-area-inset-bottom);
  --winjs-safe-area-left: env(safe-area-inset-left);
  --winjs-safe-area-right: env(safe-area-inset-right);
}

body {
  position: fixed;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  width: 100%;
  height: 100%;
  overflow: hidden;
  touch-action: manipulation;
  overscroll-behavior-y: none;
}

与其他插件集成

配合 KeepAlive 使用

// .winrc.ts
export default {
  plugins: [
    '@winner-fed/plugin-mobile-layout',
    '@winner-fed/plugin-keepalive',
  ],
  keepalive: {
    // KeepAlive 配置
  },
};

配合 Vant 主题定制

// 在 app.ts 中自定义 Vant 主题
import { ConfigProvider } from 'vant';

export const mobileLayout = {
  theme: 'light',
  // ... 其他配置
};

// 可以通过 CSS 变量定制 Vant 主题
// global.less
:root {
  --van-primary-color: #1989fa;
  --van-success-color: #07c160;
  --van-danger-color: #ee0a24;
  --van-warning-color: #ff976a;
}

注意事项

1. Vant 版本: 请确保使用 Vant 4.x 版本
2. Vue 版本: 仅支持 Vue 3.x
3. 安全区域: 在真机上测试安全区域适配效果
4. 性能优化: 配合 KeepAlive 插件使用可以提升页面切换性能

许可证

MIT