更新记录

1.0.0（2026-11-10） 下载此版本

初始化

平台兼容性

uni-app x(4.17)

其他

xtf-linkuiunix

插件文档

面向 uni-app x 蒸汽模式的 UI 组件库。本工作区有 112 个 .uvue 实现及一个空 .vue 占位，空占位不是组件聚合入口。不是传统 uni-app/Vue2 组件库，也不承诺原版全部 API 可以***改替换。

开发与平台基线

• 本轮支持/复验基线为 HBuilderX 5.26+，package.json 的 engines 据此设为 >=5.26.0，不是所有 API 最早可用版本的推断。
• manifest 配置 vapor=true、vapor-render-target=bytecode、样式隔离 2.0；本轮实际 Web 日志为 VDOM 模式，不能代替原生 Vapor 验收。
• 已验证 Web Chromium（Headless Edge 126）手机与桌面主要流程；平台元数据的 chrome 对应此 Chromium 范围，未单独验收 Safari。
• Android 部分文件通过 LSP，但 Android/iOS/HarmonyOS 未做本轮原生构建或真机验收；平台标记 - 表示不确定，不是已支持。小程序未承诺支持。
• 主题与国际化只对实际消费者生效，具体范围见下表。尚未发布为“112 组件全端验收”。
• 工程级原始审查、当前修复与测试证据分别见项目根目录 COMPONENT_AUDIT.md、COMPONENT_REPAIR_STATUS.md；COMPONENT_COMPLETENESS.md 保留原有 108 个组件的历史验收证据。本轮新增的 4 个组件以对应 Demo、生成文档和本轮编译结果为准。
• 新增 Space、Descriptions、DescriptionItem、StateView 已通过 Web Chromium 的 390px/1280px 视口及模块转换专项检查，52/52 项通过；详情见 新增组件验证报告。当前 112 个组件对应 117 篇文档、476 个示例；这些结果不代表原生端或发行构建通过。
• 2026-11-05 组件加固使用 HBuilderX 5.33 和现有 Web Edge 服务，输入、浮层、数据导航、媒体及 Tabbar 专项合计 514 个检查组通过。补充 Search 搜索/取消模式、Table 单元格插槽、四个组件的布局刷新入口，并完善相关 Demo；修复清单与验证边界见 组件修复与功能增强。

基础能力

• 四套主题：light、dark、neo、china-red
• 蒸汽模式安全的公共 Flex 布局类
• 内置简体中文和英文语言包

引入样式

在项目 App.uvue 的非 scoped 样式中引入：

@import "@/uni_modules/xtf-linkuiunix/theme/index.css";

主题通过组件或页面根节点的 class 指定。主题变量仅在该节点子树内生效：

<view class="xtf-theme xtf-theme-dark xtf-layout-page">
  <text class="page-title">内容</text>
</view>

蒸汽模式下组件默认样式隔离。业务自定义样式使用独立 class，不依赖页面全局 class 穿透组件；主题 token 由实际消费者读取，不能认为引入全局 CSS 就覆盖所有硬编码颜色。

xtf-config-provider

xtf-config-provider 是主题和全局组件配置的作用域容器。内层是独立配置作用域，并非仅将显式属性逐项合并到外层 getter；移除内层后恢复外层，外层配置不受影响。

<xtf-config-provider
  theme="dark"
  locale="en-US"
  size="md"
  component-size="lg"
  :safe-area="true"
  :z-index="3000"
  :duration="200"
  :ripple="true"
  :disabled="false"
  :theme-vars="{ '--xtf-color-primary': '#0f766e' }"
>
  <view class="xtf-layout-page xtf-safe-bottom">
    <text class="xtf-text-lg">Settings</text>
  </view>
</xtf-config-provider>

支持的属性：

组件通过 inject(XTF_CONFIG_PROVIDER_KEY, null) 读取 XtfConfigProviderContext，没有 Provider 时使用自身默认值，不依赖 globalProperties。

已核实消费矩阵

Provider 根节点禁用时的整体 opacity 仍作用于子树；Input/Select 局部 false 恢复操作但不能抵消祖先透明度。List、Form、Cascader 并非所有默认文案都已接入 locale。

组件解析

本示例工程 pages.json 当前为 autoscan=false、112 条精确 .uvue 迁移路径映射，覆盖全部实现，不包含空 .vue 占位。此前 68 条映射和 40 个缺口是审查基线，现已补齐。

库内组件依赖均已显式导入；两库并存的业务工程仍建议使用显式 .uvue import 和 PascalCase 标签。关闭扫描不能保证运行中的编译器立即丢弃旧解析结果：历史修复完成后，原有 105 个注册页的 HTTP 模块链扫描已无旧库导入。本轮新增页面不继承该历史运行证据，以本轮重新编译结果为准；空 .vue 也不作为统一入口。

多语言

组件内使用 UTS 语言工具，不使用 app.config.globalProperties：

import { getLocaleText } from "@/uni_modules/xtf-linkuiunix"

const confirmText = getLocaleText("zh-Hans", "common.confirm", "确认")

公共 CSS

• 布局：xtf-layout-page、xtf-layout-row、xtf-layout-column、xtf-layout-center、xtf-layout-fill
• 表面：xtf-surface、xtf-surface-muted、xtf-surface-primary、xtf-border、xtf-radius-*、xtf-shadow-card
• 文本：xtf-text-xs 至 xtf-text-xl、xtf-text-secondary、xtf-text-primary、xtf-text-danger、xtf-text-ellipsis
• 间距和安全区：xtf-p-*、xtf-mt-*、xtf-mb-*、xtf-safe-top、xtf-safe-bottom、xtf-safe-horizontal

文本 class 必须挂载在 <text> 上。所有 CSS 均为独立 class 选择器，适用于蒸汽模式。

基础组件

xtf-text

<xtf-text level="title" text="标题" />
<xtf-text color="secondary" :lines="1" text="单行省略的辅助说明" />
<xtf-text copyable text="点击即可复制" @copy="onCopy" />

常用属性：text、level、color、align、lines、bold、underline、delete-line、selectable、copyable、clickable、custom-class、custom-style。

lines 为有限正整数时限制行数，1 单行省略，2 及以上在 Web 使用内部文本裁剪层；非正/非有限值不限行。App 路径保留 lines 样式并绑定 max-lines，原生 VDOM/Vapor 实际效果仍待设备验证。下划线和删除线现分别使用 text-decoration-line: underline / line-through，不再用底边框或弱化透明度代替；本轮已验证 Web 多行实际高度、展开和删除线样式。

indent=true 在正文前加入两个全角空格，仅缩进首行。click/tap/longpress 透传组件收到的 Uni 事件引用，不保证与 Web DOM 原事件同对象。copyable 独立于 clickable；复制内容取点击时 text 属性快照，slot 只展示，不读取其 DOM 文本。copy 返回成功复制的快照；copy-error 返回失败对象或同步异常，卸载后不发送迟到回调。当前专项模拟剪贴板回调，系统权限和底层写入待设备验收。

xtf-icon

<xtf-icon name="search" size="md" theme="primary" />
<xtf-icon name="notifications" theme="danger" badge="8" round variant="soft" />

常用属性：name、size、theme、color、variant、round、clickable、spin、dot、badge、badge-max。

图标实际加载本模块 static/iconfont/remixicon.woff，并非 App 内置 uni-icon。内置别名和有限的 Remix 字形映射不等于完整图标目录；未知名称显示 ?，发布时需一并带上字体资源。

size 支持 xs/sm/md/lg/xl、数字、数字字符串、px、rpx；未带单位的自定义数字沿用 rpx。clickable=true 时透传原始 click 事件。spin/pulse 使用 UniElement.animate，同开时 pulse 优先；隐藏和卸载清理，原生效果仍需实机验证。grad/opsz 不承诺改变字体渲染。

xtf-button

<xtf-button label="保存" theme="primary" @click="save" />
<xtf-button label="删除" type="outline" theme="danger" />
<xtf-button label="提交" :loading="submitting" block />

常用属性：label、type、theme、color、soft-color、size、shape、round、block、disabled、loading、throttle、custom-class、custom-style。

支持 solid、light、outline、ghost、neo 五种样式，以及 primary、success、warning、danger、info 五种语义主题。未显式传入 size 时，按钮读取最近 xtf-config-provider 的 component-size；同时响应其 disabled 状态。

click/tap/longpress 透传组件收到的 Uni 事件；disabled/loading/Provider 全局禁用时拦截，局部 false 不解锁全局 true。loading 复用 Loading spinner。节流支持首点、临界值及回拨保护，非有限或非正 throttle 按不节流处理。Web 支持 Enter/Space、焦点与 ARIA，不承诺原生键盘/读屏等效；ButtonGroup 按实际元素顺序同步动态首尾和间距，原生重排待设备验收。

xtf-number-box

支持有限数值、小数/指数步长、动态 min/max/step 和输入提交。decimalLength 有效精度限制 0～20，不是任意精度运算；数值尺寸默认 rpx，显式 px 字符串保持 px。modelValue 优先于 value，父级不回写时保留本地提交，不自动解释为业务拒绝并回滚；动态约束同步不额外发送 change。禁用/只读后拒绝迟到的输入提交，blur/confirm 不重复发送同一值变化。未新增长按步进功能。

Picker、Rate 与 Grid

Picker 支持单列、多列和混合级联；首项可以是叶子，后续项仍可包含 children。叶子路径不会附带不存在的子值，数值、字符串与布尔业务值保持身份。mask-top-style / mask-bottom-style 接受字符串或样式对象并透传至两处滚轮；Web 不显示这两个原生属性，设备效果待验。

Rate 的 size 支持 sm/md/lg（32/40/48rpx）、有限正数、数字字符串和 px/rpx；非法值回退 48rpx。字符 display-mode 支持 star、heart、diamond、bolt、flame、crown、shield、dot；thumb/pill/bar/block/ticket 几何形态和图片模式尚未实现。

Grid/GridItem 的父级媒体尺寸、模式、标题/说明/间距可继承并由子项覆盖，零值保留。数据项 padding/radius/minHeight 的数值和数字字符串按 rpx，合法 px/rpx 字符串保留单位，非法值回退父值。minHeight 是最小高度，零值仍允许内容撑高；rowSpan 保留原有至少 120rpx 的行高近似。

浮层服务

Dialog、Toast、Notify、ActionSheet 的 manager 位于各组件目录的 service.uts，不从库根入口假设导出。先在当前页面挂载对应 service 宿主，再调用 manager；声明式 show/事件使用方式继续保留。例如 Toast：

<template>
  <XtfToast service closeable />
</template>

<script setup lang="uts">
import XtfToast from "@/uni_modules/xtf-linkuiunix/components/xtf-toast/xtf-toast.uvue"
import { toastManager } from "@/uni_modules/xtf-linkuiunix/components/xtf-toast/service.uts"

function showSaved(): void { toastManager.success("保存成功") }
</script>

实际调用按钮和事件反馈见工程对应 Demo；manager 返回状态快照或通知项，不是等待用户确认的 Promise。处理用户结果仍监听宿主事件。

各 manager 从 @/uni_modules/xtf-linkuiunix/components/xtf-对应名称/service.uts 导入。它们是模块共享状态；Dialog/Toast/ActionSheet 通常各挂一个服务宿主，避免多个实例重复展示，页面离开时按业务所有权清理常驻提示/队列。服务宿主原生生命周期和跨页面层级仍待设备验收。