快速上手

xtf-linkui 是基于 uni-app 的多端 UI 组件库，支持 H5、微信小程序、App 三大端。本文档基于组件库源码（uni_modules/xtf-linkui）的真实实现编写。

---

安装

将 xtf-linkui 目录复制到项目的 uni_modules/ 目录下：

cp -r xtf-linkui your-project/uni_modules/

得益于 uni-app 的 easycom 自动识别机制，xtf- 前缀组件无需手动 import 或注册，在模板中直接使用即可。

---

全局配置（推荐）

1. 引入全局主题样式

在 App.vue 中引入主题样式，保证 CSS 变量与组件样式可用：

<style lang="scss">
  @import "@/uni_modules/xtf-linkui/theme/index.scss";
</style>

2. 初始化主题管理器

在 App.vue 的 onLaunch 中初始化主题系统（会读取本地缓存的主题状态）：

<script>
import { themeManager } from '@/uni_modules/xtf-linkui'

export default {
  onLaunch() {
    themeManager.initTheme()
  }
}
</script>

3. 用 xtf-config-provider 包裹应用

xtf-config-provider 负责向所有后代组件注入主题、语言、尺寸、安全区等全局配置：

<template>
  <xtf-config-provider theme="light" locale="zh-CN" component-size="md">
    <router-view />
  </xtf-config-provider>
</template>

xtf-config-provider 支持的核心能力：

属性	类型	说明
theme	String	主题名：'light' / 'dark' / 'neo' / 'china-red'
theme-vars	Object	局部覆盖主题变量（colors / componentTokens）
locale	String	语言：'zh-CN' / 'en-US'
component-size	String	统一尺寸预设：'xs' / 'sm' / 'md' / 'lg' / 'xl'，后代组件优先读取
z-index	String | Number	弹层基准层级
duration	String | Number	全局动画时长（毫秒）
safe-area	Boolean	是否适配安全区
ripple	Boolean	是否开启涟漪效果
direction	String	布局方向：'ltr' / 'rtl' / 'auto'
disabled	Boolean	全局禁用态

---

使用组件

easycom 机制下直接书写 xtf- 前缀标签即可：

<template>
  <xtf-card radius="xl" padding="lg">
    <xtf-text level="title" text="欢迎使用 xtf-linkui" />
    <xtf-button theme="primary" label="开始使用" @click="handleTap" />
  </xtf-card>
</template>

<script>
export default {
  methods: {
    handleTap() {
      uni.showToast({ title: '点击了按钮', icon: 'none' })
    }
  }
}
</script>

---

主题系统概览

组件库内置 4 套主题（见 libs/theme/themes.js）：

主题	标识	说明
浅色	light	默认主题，明亮清晰（紫罗兰主色）
暗色	dark	暗黑模式，夜间舒适
新拟态	neo	软拟物风格，柔和阴影
中国红	china-red	品牌红色主题

主题通过 themeManager 统一管理，包含三层 token：

• 基础 token：间距 spacing、圆角 radius、阴影 shadow、字体 typography、动效 motion
• 语义色 colors：主色、状态色、背景层级、文字层级、边框、遮罩等
• 组件 token componentTokens：各组件（button / card / popup / toast / tabs 等）的精细化视觉变量

三者会被扁平化成 --xtf-* CSS 变量注入。例如：

• colors.primary → --xtf-color-primary
• componentTokens.card.bg → --xtf-card-bg
• componentTokens.toast.lightBg → --xtf-toast-light-bg

详细的主题定制方法见 主题定制。

---

国际化概览

组件库内置中英文语言包（libs/locale/），通过 xtf-config-provider 的 locale 属性切换，也可通过 registerLocale 注册自定义语言包。详见 国际化。

---

命令式 API 概览

部分反馈类组件提供命令式调用（Manager），无需在模板中挂载宿主组件：

能力	导出	常用方法
Toast 轻提示	toastManager	success() / error() / warning() / loading() / clear()
Dialog 对话框	dialogManager	alert() / confirm() / prompt() / select() / actions()
Loading 加载	loadingManager	show() / hide()
Notify 通知栏	notifyManager	success() / error()
ActionSheet 动作面板	actionSheetManager	show()
Picker 选择器	pickerManager	show()

示例：

import { toastManager, dialogManager, loadingManager } from '@/uni_modules/xtf-linkui'

toastManager.success('操作成功')

const confirmed = await dialogManager.confirm({
  title: '确认删除？',
  message: '此操作不可撤销'
})

loadingManager.show({ text: '加载中...' })
// ... 业务逻辑
loadingManager.hide()

完整的命令式 API 说明见 组件使用约定。

---

组件总览

组件库覆盖基础、表单、反馈、导航、展示、高级六大类，完整列表见 组件总览。

---

支持平台

iOS	Android	H5	微信小程序
✅	✅	✅	✅

说明：package.json 中 uni_modules.platforms.client 声明了 H5、App、MP-WEIXIN 三个平台。组件库不依赖外部 CDN 或远程字体，所有资源本地化。