移动端导航快速开始

快速开始

本节介绍如何在工程里用上 Kole UI 移动端组件:先引令牌,再按你的技术栈取用对应端的实现。移动端与 PC 端物理隔离(目录 / 类名 / 令牌前缀 / 测试都分开),只有颜色、字体、圆角、阴影令牌同源。

1 · 三步接入

  1. 引令牌:移动端令牌层已把 PC 令牌(颜色 / 字体 / 圆角 / 阴影)与移动端令牌(--kole-m-*:触控尺寸、安全区、移动端字号)合成一份 tokens.css,引入一次即可。
  2. 引组件样式:全量用聚合文件,或按需只引某个组件的 CSS。
  3. 按端取实现:同一组件六端同源,类名与结构一致,取你技术栈那一份即可(见下方按端示例)。
接入(纯 HTML / 任意工程)
<!-- ① 令牌(PC 令牌 + 移动端 --kole-m-* 合成单文件) -->
<link rel="stylesheet" href="kole-ui/mobile/tokens.css">

<!-- ② 组件样式(全量或按需二选一) -->
<link rel="stylesheet" href="kole-ui/mobile/components/index.css">
<!-- <link rel="stylesheet" href="kole-ui/mobile/components/navbar.css"> -->

<!-- ③ 结构照抄任一端的实现(本例 = H5 原生) -->
<header class="kole-m-navbar kole-m-navbar--center" role="banner">
  <button class="kole-m-navbar__back" type="button" aria-label="返回">‹</button>
  <h2 class="kole-m-navbar__title">订单详情</h2>
  <div class="kole-m-navbar__actions">
    <button class="kole-m-navbar__action" type="button">分享</button>
  </div>
</header>

2 · 按端引入

包内路径(kole-ui 的 exports 已声明;从仓库直接用则换成 dist/mobile/… 或 frameworks-mobile/…):

端引入说明
纯样式(CSS)kole-ui/mobile/components/<slug>.css拿走样式表,结构自己写(照 <Prefix>.html 的类名)
H5 原生(无框架)frameworks-mobile/<Prefix>.html零依赖演示页源码:内联脚本即完整交互,可直接改成业务页
Reactkole-ui/mobile/react(聚合)· kole-ui/mobile/react/<Prefix>.jsx(单个)函数组件 + hooks,需宿主具备 JSX 编译能力
Vue 2kole-ui/mobile/vue2(聚合)· kole-ui/mobile/vue2/<Prefix>.vue(单个)需要 Vue 2 SFC 编译能力(vue-loader 15+ / vue-template-compiler)
Vue 3kole-ui/mobile/vue3(聚合)· kole-ui/mobile/vue3/<Prefix>.vue(单个)需 Vue 3 SFC 编译能力;样式在 SFC 内
uni-app(App / 小程序 / H5)kole-ui/mobile/uniapp/<Prefix>.vueuni 基础组件 + rpx + touch 事件;令牌在宿主工程全局引一次

3 · 各端最小示例

React
import { KoleMNavBar, KoleMTabBar, KoleMActionSheet } from 'kole-ui/mobile/react';
import 'kole-ui/mobile/components/index.css';

export default function Page() {
  const [visible, setVisible] = React.useState(false);
  const [tab, setTab] = React.useState('home');
  return (
    <>
      <KoleMNavBar title="订单详情" titleAlign="center" onBack={() => history.back()}
        actions={<button className="kole-m-navbar__action" type="button">分享</button>} />
      <main style={{ padding: 16 }}>页面内容</main>
      <KoleMActionSheet visible={visible} title="订单操作"
        actions={[{ key: 'done', label: '标记为已完成' },
                  { key: 'del', label: '删除订单', tone: 'danger' }]}
        onClose={() => setVisible(false)} onSelect={(k) => console.log(k)} />
      <KoleMTabBar value={tab} onChange={setTab}
        items={[{ key: 'home', label: '首页' }, { key: 'order', label: '订单', badge: 12 },
                { key: 'mine', label: '我的' }]} />
    </>
  );
}
Vue 3
<script setup>
import { ref } from 'vue';
import KoleMNavBar from 'kole-ui/mobile/vue3/NavBar.vue';
import KoleMSwipeCell from 'kole-ui/mobile/vue3/SwipeCell.vue';
import 'kole-ui/mobile/components/index.css';

const open = ref(false);
</script>

<template>
  <KoleMNavBar title="消息列表" @back="open = true" />

  <KoleMSwipeCell direction="left"
    :actions="[{ key: 'read', label: '已读' }, { key: 'del', label: '删除', tone: 'danger' }]"
    @action="onAction">
    <span class="kole-m-swipecell__title">订单 20260920-001</span>
    <span class="kole-m-swipecell__desc">2026-09-20 09:12 · 待处理</span>
  </KoleMSwipeCell>
</template>
Vue 2
<script>
import KoleMTabBar from 'kole-ui/mobile/vue2/TabBar.vue';
import KoleMPullRefresh from 'kole-ui/mobile/vue2/PullRefresh.vue';

export default {
  components: { KoleMTabBar, KoleMPullRefresh },
  data: function () {
    return {
      tab: 'home',
      refreshing: false,
      items: [{ key: 'home', label: '首页' }, { key: 'mine', label: '我的' }]
    };
  },
  methods: {
    onRefresh: function () {
      this.refreshing = true;
      setTimeout(function () { this.refreshing = false; }.bind(this), 800);
    }
  }
};
</script>
uni-app(App / 小程序 / H5 三目标)
<script setup>
import { ref } from 'vue';
import KoleMNavBar from 'kole-ui/mobile/uniapp/NavBar.vue';
import KoleMSwipeCell from 'kole-ui/mobile/uniapp/SwipeCell.vue';
</script>

<template>
  <KoleMNavBar title="订单" @back="uni.navigateBack()" />
  <KoleMSwipeCell direction="left" :actions="[{ key: 'del', label: '删除', tone: 'danger' }]">
    <text>订单 20260920-001</text>
  </KoleMSwipeCell>
</template>

<style>
/* 令牌在宿主工程全局引一次:@import "kole-ui/mobile/tokens.css"; */
</style>

<!-- 本端限制:小程序与 App 端没有 DOM、也没有 PointerEvent,
     故组件内部只用 @touchstart/@touchmove/@touchend 与 uni 基础组件(view / text)。 -->

4 · 与 PC 端的边界

  • 不要混用类名:移动端是 kole-m-,PC 端是 kole-(如 .kole-card)。两套样式表各引各的,交叉引用会拿到未定义的样式。
  • 不要手改组件 CSS 的尺寸单位:移动端用 px + 令牌(触摸目标 44px),uni-app 端用 rpx(750rpx = 视口宽度)。PC × uni-app 端反过来保持 px。
  • 明暗模式:由 html.kole-dark 控制,移动端不再重复定义颜色;令牌层里 color-scheme 已跟随主题。
  • 完整规则与门禁命令见 平台与端。

5 · 常见问题

现象原因 / 处理
组件渲染但没有样式没引令牌或组件样式。最小集合是 tokens.css + components/index.css(或单个组件 CSS)。
--kole-m-* 取不到值令牌层没加载。它在 PC 令牌文件之上加了一层,不要只引 PC 的 colors_and_type.css。
安全区没生效(刘海/底部横条)页面需要 viewport-fit=cover(演示页都带);令牌层用 @supports (padding-top: env(safe-area-inset-top)) 探测,不支持时安全区为 0。
滑动/下拉在手机上不触发组件内部用 Pointer Events(浏览器);uni-app 端用 touch 事件。若在自定义容器上截了事件,需要放行。
同一页多个 position: fixed 组件叠在一起这是浏览器的正常行为(都相对视口定位)。做演示/预览时给容器加 transform: translateZ(0) 建立包含块,组件 CSS 不用改。