更新记录

0.10.4（2026-08-17） 下载此版本

• 增强 bsx-carousel-shell，支持受控索引、change / update:current 双向同步、item 作用域插槽、纯内容模式、自动高度及指示区域开关
• 完善高频输入与表单能力：Input、Textarea 增加焦点、失焦、确认、变更、只读、自动聚焦和清空配置；Form 增加单字段校验，FormItem 增加必填标记
• 修复 Stepper 步长计算越过 min / max 的问题，Picker 增加禁用选项支持
• 增强 Refresh 的受控刷新、加载更多、完成、错误和重试状态
• 为 Tabs、AccordionItem 增加 Vapor 原生节点测量路径，取消 Collapse 长内容的固定高度裁剪
• 修复 Modal 操作关闭时可能重复派发 close 事件的问题
• 补齐宿主演示页对 Input、Textarea、Refresh、Picker、Form、Collapse 和 CarouselShell 新增能力的交互示例

0.10.3（2026-08-09） 下载此版本

• 开放 Checkbox、Radio、Rate、Slider、Progress、Loading、Result、Button、Fab、Input 的图标或关键颜色配置，并补充 SearchBar、Popup、Tag、DatePicker、Dropdown、Collapse 的图标属性；修复 ActionSheet 外部面板与遮罩 class 未注册的问题
• 补充 Drawer、NoticeBar、NumberKeyboard、ImageUploader、BackTop、Menu、Cell、ListItem 的关闭、删除、添加和导航图标配置属性
• 统一开放 Select、Picker、Cascader、TreeSelect 的触发器、层级导航和选中图标配置属性
• 为 Tabs、Segmented、Steps、Calendar、TabBar 增加选中、激活、完成和禁用状态颜色配置入口
• 为 Alert、Toast、Empty、NavBar、NoticeBar、Tag 增加状态点、图标、文本、背景和导航图标颜色配置入口
• 为 Timeline、SwipeAction、Grid、PasswordInput 增加任意语义颜色、操作按钮颜色、徽标颜色和掩码字符配置入口

0.10.2（2026-08-08） 下载此版本

0.10.2（2026-08-08）

• 增强 bsx-switch，新增 Material 风格、尺寸与颜色配置，并支持通过 showThumbContent 控制滑块内的状态文本或 Remix Icon 图标，兼容 VDOM 与 Vapor 模式

0.10.1（2026-08-07）

• 修复 bsx-descriptions 将 bsx-d-flex 误用于 text 节点导致的 Vapor 样式告警
• 优化 bsx-count-to 的 Vapor 动画更新频率，减少多实例同时计数时的原生文本更新压力；VDOM 保持原有逐帧更新
• 为 bsx-floating 增加 Vapor 专用节点引用测量，使用 getBoundingClientRectAsync() 替代选择器查询，并增加动态内容布局重试与销毁保护
• 保留 bsx-floating 的 VDOM createSelectorQuery 测量路径，避免影响原有 VDOM 行为
• 修复浮层触发器对嵌套 bsx-button slot 的点击兼容，触发事件统一使用 click
• 为浮层面板补充基础 Flex 布局；Popover、Tooltip 显式传入面板尺寸，避免 Vapor 样式隔离导致面板无尺寸
• Vapor 下关闭 Popover、Tooltip、Dropdown 的隐藏过渡 class，避免动态 opacity 与 transform 样式冲突；VDOM 保留原有过渡动画
• 完成第一阶段 Vapor 类型与平台元数据治理，最低 HBuilderX 调整为 5.21
• 为折叠、浮动面板和水印组件增加异步测量与销毁保护
• 固定 bsx-watermark 根节点不参与 flatten，避免 Vapor 下 pointer-events、overflow 和层级异常
• 修复 bsx-grid 根节点缺少 display: flex 的布局问题
• 增加宿主应用 Vapor 适配要求和人工验证清单

平台兼容性

uni-app x(4.71)

其他

bsx-ui

bsx-ui 是面向 uni-app x 的移动端优先的类Bootstrap的 UI 组件库，代码全部由AI实现。采用 uni_modules 插件规范组织，包含三部分能力：

BSX-UI 演练场

• bsx-* 工具类样式集
• 基于工具类构建的基础组件
• 轻量 API 入口与组件配套调用能力
• 内置 light / dark 两套主题模式
• 按 基础色板 -> 语义 token -> 组件 token 组织的色彩系统

当前版本已按 uni-app x Vapor 模式完成前四阶段适配。使用方仍需在宿主应用中启用 Vapor，并按项目根目录的 VAPOR-MIGRATION.md 完成配置和人工验证。

目录结构

bsx-ui/
├── components/
│   ├── bsx-alert/
│   ├── bsx-avatar/
│   ├── bsx-badge/
│   ├── bsx-button/
│   ├── bsx-card/
│   ├── bsx-divider/
│   ├── bsx-form-item/
│   └── bsx-input/
├── index.scss
├── styles/
│   ├── base/
│   ├── internal/
│   ├── layout/
│   └── utilities/
├── theme/
│   ├── semantic.scss
│   └── tokens.scss
├── changelog.md
├── package.json
├── api/
│   ├── clipboard.uts
│   ├── feedback.uts
│   ├── registry.uts
│   └── theme.uts
└── readme.md

接入方式

1. 页面使用工具类

在宿主项目的 App.uvue 全局样式中引入：

@import "./uni_modules/bsx-ui/index.scss";

引入后，页面可以直接使用 bsx-* 工具类，例如：

<view class="bsx-d-flex bsx-flex-row bsx-items-center bsx-p-4 bsx-bg-white">
  <text class="bsx-text-base bsx-fw-semibold bsx-text-title">Hello bsx-ui</text>
</view>

3. 国际化

组件库内置 zh-CN 和 en-US 组件文案。宿主应用负责决定当前语言，并可只覆盖需要调整的 bsx.* key：

import { setBsxLocale, setBsxMessages } from './uni_modules/bsx-ui'

setBsxLocale('en-US')
setBsxMessages({
  'en-US': {
    'bsx.empty.title': 'Nothing here'
  }
})

组件显式传入的 title、text、placeholder 等文案优先于语言包。业务页面文案应由宿主自己的 t() 和语言资源管理，不要放入 bsx-ui。

2. 使用组件

组件符合 easycom 规范，无需手动注册：

<bsx-button text="确定" type="primary" theme="light" />
<bsx-card title="标题" body-text="正文内容" theme="dark" />
<bsx-form-item label="项目名称">
  <bsx-input placeholder="请输入内容"></bsx-input>
</bsx-form-item>

主题与定制

所有基础组件都提供 theme 属性，当前支持：

• light
• dark

示例：

<bsx-button text="保存" type="primary" theme="dark" />
<bsx-alert title="提示" description="暗色主题提示块" type="info" theme="dark" />

Switch 开关

bsx-switch 支持默认风格和 Material UI 风格，兼容 VDOM 与 Vapor 模式。两种风格均支持尺寸、主题、状态内容以及滑块和轨道颜色配置。

属性

事件

基础用法

<bsx-switch v-model="enabled" label="接收通知"></bsx-switch>
<bsx-switch v-model="enabled" label="Material" variant="material"></bsx-switch>

滑块文字和图标

只有同时满足以下条件时才显示滑块内容：

• showThumbContent 为 true
• 当前状态对应的文本或图标不为空

同一状态同时设置图标和文本时，优先显示图标。activeIcon 和 inactiveIcon 接收 Remix Icon 字体字符。

<bsx-switch
  v-model="darkMode"
  variant="material"
  show-thumb-content
  active-icon="&#xF1BF;"
  inactive-icon="&#xEF75;"
></bsx-switch>

<bsx-switch
  v-model="enabled"
  show-thumb-content
  active-text="ON"
  inactive-text="OFF"
></bsx-switch>

尺寸和颜色

<bsx-switch
  v-model="enabled"
  variant="material"
  size="lg"
  thumb-color="#ffffff"
  track-on-color="#1976d2"
  track-off-color="#9e9e9e"
></bsx-switch>

自定义颜色的优先级高于 theme 默认颜色。清空对应颜色属性后，组件恢复使用当前主题颜色。Material md 使用 58 × 38px 点击区域、34 × 14px 轨道和 20 × 20px 滑块。

图标与状态颜色配置

组件默认保留原有主题和图标。下列属性传入非空值后覆盖对应节点；清空属性即可恢复主题默认值。

表单与反馈

图标与导航

选择与状态

bsx-action-sheet 的 panelClass 和 maskClass 已注册为 externalClasses，可以在样式隔离模式下覆盖面板与遮罩节点。

色彩系统

bsx-ui 的色彩系统采用三层结构：

• 基础色板：提供 gray / primary / success / warning / danger 以及 blue / cyan / green / lime / gold / orange / red / magenta / purple 等扩展色系，每个色系保留 10 档阶梯。
• 语义 token：负责把色板映射为页面背景、容器背景、标题文本、正文文本、弱化文本、边框、状态色、浅色填充等通用角色。
• 组件 token：负责把语义 token 绑定到具体组件槽位，例如 button primary bg、button secondary text。

当前已经将 Button、Input、Tag、Alert 接入组件 token，后续组件建议按同一模式演进。

命名约定

• 色板层：$bsx-{color}-{step}，例如 $bsx-primary-7
• 语义层：$bsx-color-{role}-{theme} 或 $bsx-{status}-soft
• 组件层：$bsx-{component}-{theme}-{variant}-{slot}

建议的品牌化开放层级

• 预置主题包：默认、暗色、高对比、品牌主题
• 品牌主色驱动：只改品牌主色，由系统生成状态阶梯和浅色填充
• 语义 token 覆盖：允许有设计能力的团队覆盖页面、文本、边框、状态色

不建议把全部组件 token 直接暴露给业务侧，否则组件升级和主题一致性会快速失控。

除内置主题外，组件还通过 externalClasses 暴露有限扩展点，可在页面中传入扩展 class 做品牌化定制：

<bsx-button
  text="品牌按钮"
  type="primary"
  content-class="brand-button-shell"
  text-class="brand-button-text"
/>

.brand-button-shell {
  background-color: #7a5af8 !important;
  border-color: #7a5af8 !important;
}

.brand-button-text {
  color: #ffffff !important;
}

API 入口

当前 index.uts 仅暴露与组件库本身强相关的轻量 API：

• theme：主题模式查询
• registry：组件与工具类导航元数据
• feedback：轻量提示反馈
• clipboard：示例代码与文本复制
• overlay：为 modal、action-sheet、picker 预留的编程式控制结构

当前已导出的 API 包括：

• getBsxThemeModes()
• getBsxCurrentTheme()
• isBsxDarkMode()
• getBsxComponentItems()
• getBsxComponentMeta(name)
• getBsxUtilityItems()
• showBsxToast(message)
• showBsxSuccess(message)
• showBsxError(message)
• createBsxModalOverlayOptions()
• openBsxModal(options)
• closeBsxModal(options)
• createBsxActionSheetOverlayOptions()
• openBsxActionSheet(options)
• closeBsxActionSheet(options)
• createBsxPickerOverlayOptions()
• openBsxPicker(options)
• closeBsxPicker(options)
• copyBsxText(content, successText?)
• copyBsxSnippet(content)

这组 overlay API 当前只负责统一选项结构和开关控制，不直接创建全局弹层实例。这样可以先稳定对外接口，再按需要升级成真正的编程式挂载实现。

不建议在 bsx-ui 中继续整合完整的 uni 原子 API。请求、存储、路由、权限、设备环境这类基础能力，更适合拆到独立的 bsx-core。

当前实现概览

组件库当前覆盖以下移动端 UI 能力：

• 基础与排版：文本、标题、段落、链接、统计、卡片、分割线、头像、图标、图片、描述列表、水印与标签。
• 表单与选择：输入框、多行输入、搜索、开关、单选、多选、评分、滑条、步进器、选择器、日期/日历、级联、树选择、密码输入和数字键盘。
• 导航与内容组织：导航栏、标签页、底部导航、分段控制、菜单、宫格、列表、单元格、折叠面板、步骤条、时间轴、轮播和索引列表。
• 反馈与浮层：提示、加载、骨架、结果、空状态、进度、弹窗、抽屉、动作面板、浮动面板、气泡、提示气泡、二次确认、悬浮操作与回到顶部。
• 数据与媒体：轻量表格、刷新加载、分页、侧滑操作、图片选择上传与倒计时。

关键能力

• bsx-form / bsx-form-item：支持基于 model 与 rules 的必填、最小长度、最大长度校验；组件实例可调用 validate()、resetFields()、clearValidate()。
• bsx-table：面向移动端的静态数据表格，支持列宽、文本对齐、斑马纹和横向滚动；不包含排序、固定列或虚拟滚动。
• bsx-tab-bar：支持图标、激活图标、角标、禁用态、固定底部和安全区；固定模式下由页面预留底部空间。
• bsx-switch：支持 default / material 两种风格、sm / md / lg 尺寸、滑块与轨道颜色覆盖；两种风格均可通过 showThumbContent 控制是否显示 activeText、inactiveText 或对应的 activeIcon、inactiveIcon 状态内容。
• bsx-tree-select：首版为两级双栏选择，适合分类、权限和组织架构叶子节点选择；不递归展开三级及以上树。
• bsx-watermark：支持数量与铺满区域；水印仅用于视觉标识，不能替代防截屏或数据安全措施。

已提供组件

• bsx-text
• bsx-heading
• bsx-paragraph
• bsx-link
• bsx-stat
• bsx-form
• bsx-progress
• bsx-result
• bsx-countdown
• bsx-count-to
• bsx-segmented
• bsx-carousel-shell
• bsx-radio-group
• bsx-checkbox-group
• bsx-popup
• bsx-floating
• bsx-overlay-host
• bsx-search-bar
• bsx-picker
• bsx-cell
• bsx-cell-group
• bsx-button
• bsx-badge
• bsx-back-top
• bsx-card
• bsx-alert
• bsx-input
• bsx-icon
• bsx-image-uploader
• bsx-form-item
• bsx-grid
• bsx-divider
• bsx-date-picker
• bsx-avatar
• bsx-switch
• bsx-swipe-action
• bsx-checkbox
• bsx-radio
• bsx-rate
• bsx-textarea
• bsx-timeline
• bsx-table
• bsx-select
• bsx-dropdown
• bsx-modal
• bsx-toast
• bsx-action-sheet
• bsx-popover
• bsx-tooltip
• bsx-drawer
• bsx-tabs
• bsx-tab-bar
• bsx-nav-bar
• bsx-pagination
• bsx-stepper
• bsx-slider
• bsx-steps
• bsx-notice-bar
• bsx-loading
• bsx-load-more
• bsx-skeleton
• bsx-empty
• bsx-tag
• bsx-collapse
• bsx-accordion-item
• bsx-collapse-group
• bsx-list
• bsx-list-item
• bsx-menu
• bsx-refresh
• bsx-password-input
• bsx-index-list
• bsx-cascader
• bsx-tree-select
• bsx-calendar
• bsx-popconfirm
• bsx-number-keyboard
• bsx-fab
• bsx-descriptions
• bsx-watermark

bsx-carousel-shell 扩展属性

• current：受控当前索引。轮播滑动后触发 change(index) 与 update:current；外部修改 current 会同步切换轮播。
• item 作用域插槽：提供 index、item 和 active，可按当前索引渲染自定义内容，例如人设页的 sentence-practice-card。
• contentOnly：纯内容模式，移除默认图片、遮罩、背景和展示文案，仅渲染轮播容器与自定义 item 插槽内容，默认 false。
• autoHeight：传递给内部 swiper，使当前项高度随内容变化；height 仍作为固定高度回退值。插槽内容更新后组件会重新测量当前项。
• showDots / showFooter：分别控制指示点和底部指示区域，默认均为 true；showCounter 继续单独控制计数器。

0.10.4 高频组件能力

• bsx-input：增加 readonly、autoFocus、focus、confirmType、cursorSpacing、clearable，并透传 focus、blur、change、confirm、clear 事件。
• bsx-textarea：增加 readonly、autoFocus、focus、confirmType、cursorSpacing，并透传 focus、blur、change、confirm 事件。
• bsx-stepper：步长计算结果自动限制在 min 和 max 范围内。
• bsx-picker：选项支持 disabled: true，禁用项不可选并保持禁用视觉。
• bsx-refresh：增加 refreshing、loadingMore、finished、error 受控状态，以及完成、错误和重试文案；新增 retry 事件。
• bsx-form：暴露 validateField(prop) 单字段校验方法。
• bsx-form-item：增加 required 必填标记。
• bsx-tabs、bsx-accordion-item：Vapor 模式使用 getBoundingClientRectAsync() 进行动态节点测量；VDOM 保留原有查询路径。
• bsx-collapse：取消 320px 的内容高度上限，避免长内容展开时被裁剪。

以上能力均已同步到宿主项目的对应组件演示页；演示页中的开关、步进器和事件结果用于验证受控属性及交互回调。

工具类分层

• base：基础显示与页面壳层类
• layout：flex、尺寸、定位类
• utilities：spacing、typography、color、background、border、radius、shadow
• theme：SCSS token 与语义色映射

样式约束

• 仅使用 class 选择器
• 所有 display: flex 都显式声明 flex-direction
• 文本样式必须直接写在 <text> 节点上
• 优先使用 px，仅在确有需要时使用其他单位

样式隔离 2.0

组件默认按 styleIsolation: 'isolated' 设计：

• 页面可以使用全局 bsx-* 工具类
• 组件内部不会直接引用页面级 class
• 组件通过 externalClasses 暴露有限样式扩展入口

这意味着：

• 页面布局与演示可以依赖全局工具类
• 组件内部仍然复用同一套工具类文件，但在组件私有样式上下文内生效

开发约定

• 组件使用 .uvue 文件和 <script setup lang="uts">
• UTS 数据结构优先使用 type
• 组件目录使用 components/组件名/组件名.uvue
• 新增组件时统一使用 bsx- 前缀
• 发布前同步更新 package.json 和 changelog.md

平台兼容性

当前 package.json 平台状态仍使用待验证标记。每个平台完成实际编译与交互测试后，再将对应平台更新为 √。