更新记录

1.0.0（2026-08-29）

初始化

Changelog

All notable changes to xtf-linkui will be documented in this file.

[0.0.1] - 2025-06-06

Added

主题系统

• 主题 Token 基础体系（tokens.scss、variables.scss）
• light / dark / neo / glass / brand 五套内置主题
• ThemeManager 运行时主题管理器，支持持久化存储
• CSS 变量映射：基础 token → 语义 token → 组件 token
• 运行时主题切换（应用启动时读取，运行时动态切换）
• xtf-config-provider 全局配置组件，支持 theme / themeVars / locale / size / zIndex / duration / safeArea / ripple 配置项

国际化

• 中英文语言包（zh-CN.js / en-US.js）
• use-locale Hook，支持全局语言注入与组件读取
• ConfigProvider 支持语言注入

P0 核心组件

• xtf-text — 排版组件（支持 10 级字号、8 种颜色、渐变/发光/下划线/删除线/省略等）
• xtf-button — 按钮组件（7 种样式变体、7 种主题色、5 种尺寸、3 种形状、加载态、波纹反馈）
• xtf-input — 输入框组件（5 种样式变体、前后缀图标、清除、密码切换、错误/成功/警告态、字数统计、textarea + auto-height）
• xtf-card — 卡片组件（6 种变体、header/body/footer 插槽、可点击态）
• xtf-tag — 标签组件（solid/light/outlined、default/round/mark/dot、可关闭、可选中）
• xtf-avatar — 头像组件（图片/文字/占位、状态点、外环、角标）
• xtf-badge — 徽标组件（dot/数字/文本、最大显示值、位置控制、零值隐藏）
• xtf-popup — 弹出层组件（6 方向、遮罩、圆角、遮罩关闭、层级控制、滚动锁定）
• xtf-dialog — 对话框组件（alert/confirm/自定义内容、异步关闭）
• xtf-toast — 轻提示（success/error/warning/info/loading、队列模式、命令式调用）
• xtf-loading — 加载组件（inline/overlay、动画样式、文字提示、全局 show/hide）

P1 重要组件

布局与导航： xtf-navbar、xtf-tabs、xtf-grid、xtf-divider 表单与选择： xtf-picker、xtf-switch、xtf-radio、xtf-checkbox、xtf-rate、xtf-slider 展示与反馈： xtf-collapse、xtf-steps、xtf-empty、xtf-image、xtf-action-sheet、xtf-skeleton

P2 进阶组件

弹层与通知： xtf-notify、xtf-drawer 导航与内容流： xtf-swiper、xtf-tabs-swiper、xtf-back-top、xtf-breadcrumb 交互增强： xtf-pull-refresh、xtf-watermark 数据展示： xtf-table、xtf-statistic、xtf-timeline 高级组件： xtf-calendar、xtf-upload、xtf-countdown、xtf-marquee、xtf-floating-bubble、xtf-signature

扩展组件

xtf-collapse-animation、xtf-button-group、xtf-cell、xtf-cell-group、xtf-circle、xtf-count-to、xtf-datetime-picker、xtf-dropdown-menu、xtf-form、xtf-infinite-scroll、xtf-index-bar、xtf-lazyload、xtf-list、xtf-number-keyboard、xtf-overlay、xtf-pagination、xtf-password-input、xtf-progress、xtf-result、xtf-search、xtf-select、xtf-share-sheet、xtf-sticky、xtf-swipable-cell、xtf-tabbar、xtf-tree、xtf-virtual-list

工具层

• utils/index.js — debounce、throttle、raf/cancelRaf、createIntersectionObserver、getBoundingClientRect、formatNumber、clamp、snapToStep、isEmpty
• utils/deep-merge.js — cloneDeep、deepMerge、hasOwnValues
• utils/bem.js — BEM 类名生成（createBEM / bem）
• utils/z-index-manager.js — z-index 层级管理
• utils/platform.js — 平台判断（H5/小程序/App）
• utils/validate.js — 表单校验（手机号/邮箱/身份证/数字/URL 等）

Hooks

• use-theme — 主题 Hook
• use-locale — 国际化 Hook
• use-model — v-model 双向绑定 Hook
• use-popup — 弹层 z-index 管理 Hook

命令式 API

• Toast 管理器（libs/toast/toast-manager.js）
• Dialog 管理器（libs/dialog/dialog-manager.js）
• Loading 管理器（libs/loading/loading-manager.js）
• Notify 管理器（libs/notify/notify-manager.js）
• ActionSheet 管理器（libs/action-sheet/action-sheet-manager.js）
• Picker 管理器（libs/picker/picker-manager.js）

Demo 与文档

• 59 个组件 Demo 页面
• 组件级 API 文档（docs/components/）
• 主题定制说明文档
• 国际化说明文档

图标系统

• Remixicon 本地字体方案
• xtf-icon 组件（name/size/color/spin/pulse/dot/badge/点击态）
• 常用 Material 风格图标名兼容

平台兼容性

uni-app(3.97)

xtf-linkui

xtf-linkui 是一个基于 uni-app 的多端 UI 组件库，覆盖基础、表单、反馈、导航、展示与高级六大类场景，支持 H5、微信小程序、App 三端。

📖 在线文档：https://env-00jy6fwh6avu-static.normal.cloudstatic.cn/docs/

文档内含每个组件的完整 API 说明、真实可运行示例、事件/插槽用法与主题定制指南。

特性

• 多类组件 — 覆盖基础、表单、反馈、导航、数据展示、高级场景，总计 100+ 组件
• 内置主题 — light / dark / neo / china-red 四套主题，支持运行时切换
• CSS 变量体系 — 基础 token → 语义 token → 组件 token 三层映射
• 国际化 — 中英文双语支持，可通过 xtf-config-provider 全局注入，支持注册自定义语言包
• 命令式 API — Toast、Dialog、Loading、Notify、ActionSheet、Picker 支持函数式调用（Manager 模式）
• 按需编译 — 基于 uni_modules 的 easycom 自动识别，无需手动注册
• 主题定制 — 支持全局注册完整主题或局部覆盖 CSS 变量
• 官方能力映射 — 已补齐官方 uni-app 表单、展示、滚动、导航、拖拽、画布等核心组件能力的 xtf 场景映射

快速开始

1. 引入全局主题样式

在 App.vue 中：

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

2. 初始化主题管理器

在 App.vue 的 onLaunch 中：

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

export default {
  onLaunch() {
    themeManager.initTheme()
  }
}

3. 使用组件

得益于 uni_modules 的 easycom 机制，组件无需手动引入即可直接使用：

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

组件列表

组件文档地址前缀：https://env-00jy6fwh6avu-static.normal.cloudstatic.cn/docs/components/

基础组件

表单组件

反馈组件

导航组件

展示组件

高级组件

官方组件能力映射

xtf-linkui 不直接复制官方 demo，而是将官方组件能力映射到已有业务化组件：

内置主题

切换主题

// 全局切换
import { themeManager } from '@/uni_modules/xtf-linkui'
themeManager.setTheme('dark')

// 局部覆盖（通过 ConfigProvider）
<xtf-config-provider theme="dark">
  <view>这里是暗色区域</view>
</xtf-config-provider>

自定义主题

注册完整主题

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

themeManager.registerTheme('my-brand', {
  colors: {
    primary: '#6366f1',
    // ... 其他颜色 token
  },
  // ... 其他 token
})

themeManager.setTheme('my-brand')

局部覆盖 CSS 变量

<xtf-config-provider :theme-vars="{ '--xtf-color-primary': '#6366f1' }">
  <view>这里 primary 色变为自定义值</view>
</xtf-config-provider>

命令式 API

命令式 API 采用 Manager 模式（发布-订阅），需在页面挂载对应宿主组件（service 模式）后调用：

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

// Toast
toastManager.success('操作成功')
toastManager.error('操作失败')

// Dialog
dialogManager.confirm({
  title: '确认删除？',
  message: '此操作不可撤销'
})
dialogManager.alert({ title: '提示', message: '操作完成' })

// Loading
loadingManager.show({ text: '加载中...' })
loadingManager.hide()

// Notify
notifyManager.success({ title: '保存成功', message: '数据已保存' })

目录结构

uni_modules/xtf-linkui/
├── components/         # 组件目录
├── libs/
│   ├── config/         # 默认配置
│   ├── hooks/          # use-theme / use-locale / use-model / use-popup
│   ├── locale/         # 中英文语言包
│   ├── theme/          # ThemeManager + 主题配置
│   ├── utils/          # 工具函数（debounce/throttle/BEM/z-index/platform/validate）
│   ├── toast/          # Toast 命令式管理器
│   ├── dialog/         # Dialog 命令式管理器
│   ├── loading/        # Loading 命令式管理器
│   ├── notify/         # Notify 命令式管理器
│   ├── action-sheet/   # ActionSheet 命令式管理器
│   └── picker/         # Picker 命令式管理器
├── theme/              # SCSS 主题样式文件
├── static/iconfont/    # Remixicon 图标字体
├── package.json
├── readme.md
├── changelog.md
└── license.md

技术要求

• uni-app 2.x / 3.x
• 支持平台：H5、微信小程序、App
• 不依赖外部 CDN 或远程字体

设计约定

• 所有组件使用 xtf-* 前缀，通过 easycom 自动识别
• 样式使用 CSS 变量（--xtf-*），支持主题系统统一切换
• 工具函数放在 libs/utils/，Hooks 放在 libs/hooks/
• 命令式 API 放在 libs/<name>/ 独立管理