__THEME_BOOT__ __BRAND_HEAD__ 快速开始 — Kole UI Mobile __HEADER__
__SIDEBAR__

快速开始

本节介绍如何在工程里用上 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/…）：

__END_ROWS__
端引入说明

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 不用改。
__COPY_SCRIPT__