更新记录

1.4.0（2026-11-10）

概述

本版本在 1.3.0 基础上大幅扩充组件与能力面：补齐评分、步骤条、浮球、指引、轮播、索引、浮动面板、安全验证、条形码等；强化二维码 / 返回顶部 / 日历 / 键盘；落地国际化与宽屏；全面标注组件参数注释与作者信息；优化真机蒸汽模式下的动效与样式兼容。

一、新增组件

二、组件增强

二维码 yk-qrcode

• 定位角 + 时序线 + 对齐图案 + 数据区伪编码
• 支持 version（21/25/29）、ecl 密度、rounded 圆角点
• 支持 theme="primary"、中心 Logo / 中心文字
• 操作区：复制 / 刷新 / 反色；长按复制
• 边框、提示文案、showActions 可配

返回顶部 yk-back-top

• 模式：light / primary / dark
• 支持 iconName（yk-icon）、图片图标、箭头兜底
• 可选滚动进度环与百分比
• 方形 / 圆形；自定义背景与颜色

日历 yk-calendar

• type="single" | "range" 单选 / 范围
• popup 弹层或内嵌
• weekStartsOn 周日 / 周一起始
• markDays 标记日（字符串或 { date, color }）
• 主题色、最小最大日期、回到今天

键盘 yk-keyboard

• 模式：number / digit / idcard / car / custom
• 车牌键盘：省份简称 ↔ 字母数字，新能源 8 位
• 默认不在键盘面板展示输入内容（页面自行展示 v-model）
• 长按连续删除、按键震动、侧栏删除 / 完成布局
• 已移除快捷金额条

复选框 yk-checkbox

• 对勾改为边框旋转单元素 + 绝对居中，修复真机贴左上

通知栏 yk-notice-bar

• 蒸汽模式用 translateX 定时器跑马灯（不用 CSS keyframes）

TabBar yk-tabbar

• 选中动效用 style + transition，结束强制 transform:none
• 连点先清空再播，避免图标错位

Toast（libs/toast.uts）

• App 纯文字默认 position: bottom，避免真机偏上

步骤条连线

• 横向改为「左半线 + 圆点 + 右半线」，间隔线可连续对接

浮球回弹

• 默认 zIndex: 10080，避免被页面内容遮挡
• 松手先过冲再吸附，弹性过渡更好

浮动面板拖拽

• 拖拽中关闭 height 过渡，高度跟手并实时 update:height

索引列表

• 侧栏加宽、完整 A–Z、实测 boundingClientRect 定位，点击更准

三、国际化（i18n）

新增 libs/locale.uts：

• 内置 zh-CN / en-US
• 指引、查看更多、安全验证、步骤、条码等文案走 t()
• main.uts 已调用 initYkLocale()
• Demo：接口页 →「国际化/宽屏」

四、宽屏（Widescreen）

新增 libs/widescreen.uts + yk-container：

• package.json 声明：i18n: y、widescreen: y、darkmode: y
• 样式补充 .yk_wide / .yk_narrow / .yk_page_wide_inner

五、工程与规范

• 全部 54 个组件补充：
  • @version 1.4.0
  • @author yangkang
  • Props 逐参数 /** 注释 */
• 主壳「接口 / 关于」页清理不可点击假宫格，关于改为只读信息 + 可点主题设置
• Demo 导航 / pages.json 注册新组件演示页
• 蒸汽模式 CSS 兼容：避免 max-width: %、避免不支持的嵌套选择器与 keyframes 依赖

六、已知说明

• yk-qrcode 为轻量矩阵示意，生产扫码请接服务端出图或完整算法包
• yk-barcode 为 Code39，非法字符会跳过
• 页面滚动统一原生滚动，不使用 scroll-view（索引列表依赖 pageScrollTo）

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

面向 uni-appX + Vue3 + UTS + 蒸汽模式（Vapor） 的跨端 UI 组件库。

• 作者：yangkang
• 版本：1.4.0
• 分发方式：uni_modules + easycom
• 主题色：绿色系（#07c160）
• 能力声明：暗黑模式 ✅ · 国际化 ✅ · 宽屏 ✅

适用端：Android · iOS · 鸿蒙 NEXT · WEB · 微信小程序（以 package.json platforms 为准）。

目录

1. 特性
2. 安装与接入
3. 快速开始
4. 主题
5. 国际化
6. 宽屏适配
7. 图标
8. 工具库 API
9. 组件一览与用法
10. 开发约定
11. 目录结构
12. Demo 工程
13. 更新日志
14. 作者与许可

特性

安装与接入

1. 放入工程

将本插件目录放到：

你的项目/uni_modules/yk-ui/

2. 配置 easycom（pages.json）

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^yk-(.*)": "@/uni_modules/yk-ui/components/yk-$1/yk-$1.uvue"
    }
  }
}

3. 引入全局样式（App.uvue）

@import '@/uni_modules/yk-ui/libs/style/index.css';

WEB 端也可在 main.uts 中额外 import 同一份 CSS。

4. 初始化（推荐在 main.uts）

import App from './App.uvue'
import { createSSRApp } from 'vue'
import {
  setYkUiConfig,
  initYkTheme,
  initYkLocale,
  initYkWidescreen
} from '@/uni_modules/yk-ui'

// #ifdef WEB
import '@/uni_modules/yk-ui/libs/style/index.css'
// #endif

export function createApp() {
  const app = createSSRApp(App)
  setYkUiConfig({
    imgBaseUrl: 'https://cdn.example.com',
    baseUrl: 'https://api.example.com',
    uploadUrl: '/api/upload'
  } as UTSJSONObject)

  initYkTheme()        // 主题（跟随系统 / 本地缓存）
  initYkLocale()       // 国际化
  initYkWidescreen()   // 宽屏

  return { app }
}

5. 页面根节点挂主题 class

<view class="yk_page" :class="themeClass">
  <!-- 内容 -->
</view>

import { getYkThemeClass } from '@/uni_modules/yk-ui'
const themeClass = ref(getYkThemeClass())

快速开始

模板

<view class="yk_page yk_theme_light">
  <yk-navbar title="示例" />
  <yk-button type="primary" text="提交" @click="onSubmit" />
  <yk-cell-group title="设置">
    <yk-cell title="消息通知" :isLink="true" />
  </yk-cell-group>
  <yk-modal />
</view>

脚本

import { showConfirm, showToast, setYkTheme } from '@/uni_modules/yk-ui'

async function onSubmit(): Promise<void> {
  const res = await showConfirm('确认提交？')
  if (res.confirm) {
    showToast('已提交')
  }
}

主题

CSS 变量

主题样式定义于 libs/style/variables.css，页面挂载：

• yk_theme_light 浅色
• yk_theme_dark 深色

常用变量示例：--yk-primary、--yk-bg、--yk-bg-2、--yk-text、--yk-border 等。

API

国际化

文件：libs/locale.uts

API

示例

import { setYkLocale, t } from '@/uni_modules/yk-ui'

setYkLocale('en-US')
const tip = t('guide.next')           // Next
const msg = t('rate.value')           // Rate

内置文案键（部分）

common.confirm / common.cancel / common.loading / common.empty
guide.next / guide.prev / guide.skip / guide.done
viewMore.expand / viewMore.collapse
security.tip / security.success / security.fail / security.reset
barcode.empty / steps.wait / steps.process / steps.finish / steps.error

宽屏适配

文件：libs/widescreen.uts · 组件：yk-container

<view class="yk_page" :class="wideClass">
  <yk-container :maxWidth="1080">
    <!-- 业务内容 -->
  </yk-container>
</view>

import { getYkWideClass } from '@/uni_modules/yk-ui'
const wideClass = ref(getYkWideClass())

注意：uvue 中 max-width 不支持百分比，请使用 px 数值（容器已按此处理）。

图标

• 字体：static/font/ykicon.ttf
• 映射：libs/icons.uts（内置 100+，如 search / home / plus / star / arrow-right …）

<yk-icon name="search" size="22px" color="#07c160" />
<yk-icon name="loading" :spin="true" />

从 iconfont.cn 扩展

1. 新建项目并添加图标，下载 Font class / Unicode
2. 覆盖或新增 .ttf 到 static/font/
3. 注册映射：

import { registerYkIcons } from '@/uni_modules/yk-ui'
import type { YkIconItem } from '@/uni_modules/yk-ui'

registerYkIcons([
  { name: 'my-icon', code: '\ue001' } as YkIconItem
] as YkIconItem[])

工具库 API

入口：import { … } from '@/uni_modules/yk-ui'

配置 / 图片

反馈

网络 / 上传

存储 / 路由 / 事件

通用工具

rpx2px / px2rpx / getWindowWidth / getWindowHeight / getStatusBarHeight
padZero / formatDate / sleep / clamp / isEmpty / uuid
copyText / getClipboard / makePhoneCall

动画辅助

ykSpinLoop / ykStopLoop / ykAnimateById / ykTabSelectAnim / ykAnimId

条码工具

encodeCode39 / mergeBarcodeModules

组件一览与用法

所有组件均标注 @version 1.4.0 · @author yangkang。
下列为常用 Props 摘要，完整参数见各组件源码内注释。

基础

<yk-button type="primary" text="提交" />
<yk-rate v-model="score" :allowHalf="true" />
<yk-steps :active="1" :list="stepList" />

导航与布局

<yk-float-ball icon="plus" badge="3" @click="onFab" />
<yk-guide v-model:show="showGuide" :steps="guideSteps" />
<yk-swiper :list="banners" :height="160" :card="true" />

表单

<!-- 金额：页面自己展示 value，键盘不回显 -->
<text>¥{{ amount }}</text>
<yk-keyboard v-model:show="showKb" v-model="amount" mode="number" />

<!-- 车牌 -->
<yk-keyboard v-model:show="showPlate" v-model="plate" mode="car" :newEnergy="true" />

反馈与展示

<yk-qrcode value="https://example.com" theme="primary" :rounded="true" :showActions="true" />
<yk-barcode value="YKUI2026" :width="300" :height="90" />
<yk-security @success="onVerified" />

开发约定

1. 蒸汽模式：优先使用 transform / opacity 过渡；复杂循环用 setInterval / ykSpinLoop。
2. 滚动：页面使用原生滚动，业务列表不要默认套 scroll-view（项目规范）。
3. 图片：资源路径经 getFullImgUrl，勿写死完整 CDN。
4. 样式 class：下划线命名 yk_xxx；避免 body 等全局类名；uvue 限制下勿用百分比 max-width、慎用嵌套选择器。
5. 接口字段：渲染直接取接口字段，不做无意义映射。
6. 分页：默认每页 15 条。
7. 表单提交：防重复点击、loading、并发控制。
8. 注释：新增组件需写 @version / @author yangkang，并为每个 Prop 写说明。

目录结构

uni_modules/yk-ui/
├── components/           # 54 个 yk-* .uvue 组件
│   ├── yk-button/
│   ├── yk-keyboard/
│   ├── yk-float-ball/
│   └── …
├── libs/
│   ├── style/            # variables.css / animation.css / index.css
│   ├── theme.uts         # 主题
│   ├── locale.uts        # 国际化
│   ├── widescreen.uts    # 宽屏
│   ├── toast.uts / modal.uts / request.uts / storage.uts …
│   ├── icons.uts         # 图标映射
│   └── barcode.uts       # Code39
├── static/font/
│   └── ykicon.ttf
├── index.uts             # 统一导出
├── package.json
├── changelog.md
└── readme.md

Demo 工程

本仓库即完整 Demo：

• 演示页路径形如：/pages/demo/button/button
• 配置见 pages/demo/nav.uts、pages/demo/api/nav.uts
• 页面原生滚动；主壳下拉刷新在导航栏下方

更新日志

近期重点（1.4.0）：

• 新增评分、步骤条、浮球、指引、轮播、索引、浮动面板、安全验证、条形码、单选等
• 强化二维码 / 返回顶部 / 日历 / 车牌键盘
• 国际化 + 宽屏
• 全组件参数注释与作者标注
• 真机兼容：Toast 位置、复选框对勾、TabBar 错位、步骤连线、浮球层级与回弹等

作者与许可

• 作者：yangkang
• 组件库：YK UI
• 版本：1.4.0
• 声明：插件不采集任何数据；无广告；无额外权限要求（见 package.json declaration）

如需二次开发，请保留作者信息与版本注释规范，便于团队协作与插件市场更新。