wx-sky-ui

介绍

wx-sky-ui 是专为微信小程序 Skyline 渲染引擎 打造的高性能、高颜值、轻量化自定义组件库。

在微信小程序全新推出的 Skyline 渲染引擎下，许多传统的 WebView 组件库面临排版错乱、动画生硬或样式不兼容的严峻挑战。本项目致力于填补这一生态空白，采用全 Flex 盒模型排版、Compositor 硬件加速动画与高颜值的 HSL 色彩体系，为您提供开箱即用、媲美原生 App 的极致流畅组件交互体验。

已就绪组件地图 (Component Map)

基础组件

| 组件 | 说明 | 文档 | |------|------|------| | Button 按钮 | 拥有流畅微阴影与按压 HSL 降明度反馈的示范级按钮 | - | | Icon 图标 | 支持 SVG 路径、渐变色、多色复杂 SVG 的高性能图标组件 | - | | NavBar 导航栏 | 胶囊高度动态避让、向左返回图标后自适应流式标题栏 | - | | Cell 单元格 | 纯 CSS 手绘极细右箭头，高档按压态过渡 | 文档 | | Tag 标签 | 莫兰迪低饱和度色彩，搭配同色系极淡背景 | - |

表单组件

| 组件 | 说明 | 文档 | |------|------|------| | Input 输入框 | 支持搜索、一键清除、三大变体以及硬件加速弹性挤压动画 | 文档 | | Textarea 多行输入 | 支持自动增高、字数统计的多行文本输入框 | 文档 | | Switch 开关 | 滑块四周保留黄金边距，按压时横向微缩扁变形 | 文档 | | Radio 单选 | 勾选对勾采用纯 CSS 路径延迟过渡绘制 | 文档 | | Checkbox 复选 | 选中时采用高对比、低饱和度 HSL 品牌色 | 文档 | | Slider 滑块 | 滑块按压伴随呼吸光晕，数字气泡弹性淡入 | 文档 | | Rate 评分 | 纯 CSS 物理手绘高精度五角星，点亮时微缩放反弹 | 文档 | | SelectInput 多选输入 | Tag 标签堆叠，支持删除和清除 | 文档 | | Uploader 上传 | 支持图片预览、删除的上传组件 | - |

反馈组件

| 组件 | 说明 | 文档 | |------|------|------| | Dialog 模态弹出框 | 极克制的 scale + opacity 双向平滑缓动渐现 | 文档 | | Toast 轻提示 | 淡入淡出贝塞尔曲线调优，极低包体积 | - | | ActionSheet 动作面板 | 上边缘 24rpx 大圆角，按压反馈柔和 | 文档 | | PopupSelect 弹出选择 | 高颜值底部半屏大圆角滑出抽屉式滚动选项选择器 | - | | DropdownSelect 下拉选择 | 从触发元素下方弹出的轻量级下拉选择器 | - | | SwipeCell 滑动单元格 | 基于 gesture-handler，摩擦阻尼经物理公式调优 | 文档 |

展示组件

| 组件 | 说明 | 文档 | |------|------|------| | Badge 徽标角标 | 自带极细白边描边，数字字体选用等宽排版 | 文档 | | Progress 进度条 | 端点完美圆角，进度变化使用缓动插值 | 文档 | | Skeleton 骨架屏 | 亮暗扫光采用极轻柔渐变，约 1.5s 周期 | 文档 | | Swiper 轮播 | 支持卡片模式、指示器、自动播放的轮播组件 | 文档 | | Subsection 分段器 | 高颜值分段切换控制器 | - |

高阶组件

| 组件 | 说明 | 文档 | |------|------|------| | Editor 富文本编辑器 | 尊贵悬浮毛玻璃工具栏，视口防遮挡避让 | 文档 | | HtmlRenderer 富文本渲染 | 人眼工效阅读排版，多媒体懒加载渐现 | 文档 | | DatetimePicker 日期时间选择 | 内置日历与时间滑块，支持日期时间范围多选 | - | | FloatButton 悬浮按钮 | 支持胶囊/圆形形态、Speed Dial 子菜单展开 | - |

快速开始（使用者）

1. 安装

npm install wx-sky-ui

[!IMPORTANT] ⚠️ 微信小程序 npm 构建常见报错与目录配置指南

在许多微信小程序项目中，如果您在 project.config.json 中配置了小程序根目录（例如 "miniprogramRoot": "miniprogram/"），微信开发者工具在执行 “构建 npm” 时，只会自动在小程序根目录（如 miniprogram/）下寻找 package.json，而不是项目最外层的根目录。

如果您遇到微信开发者工具提示找不到组件，或者 miniprogram_npm/ 目录下没有生成组件文件夹，请按以下步骤检查与修复：

1. 同步依赖配置：确保小程序根目录下的 miniprogram/package.json 的 dependencies 中已添加了 "wx-sky-ui": "^1.0.0"。
2. 安装依赖包：打开终端，进入小程序根目录（如 miniprogram/），执行依赖安装命令：

   cd miniprogram
   npm install

   确保依赖成功下载到 miniprogram/node_modules/ 下。
3. 重新构建 npm：在微信开发者工具中，点击顶部菜单栏的 工具 (Tools) -> 构建 npm (Build NPM)。构建完成后，miniprogram/miniprogram_npm/ 目录下就会成功编译生成 wx-sky-ui 文件夹，对应的报错就会自动消失！

2. 构建 npm

在微信开发者工具中，点击 工具 → 构建 npm，生成 miniprogram_npm 目录（如果项目使用了 miniprogramRoot 配置，则生成在对应的小程序根目录下，详见上方说明）。

3. 按需引入组件

在页面的 index.json 中声明需要的组件（用哪个引哪个）：

{
  "usingComponents": {
    "sky-button": "wx-sky-ui/button/index",
    "sky-icon": "wx-sky-ui/icon/index",
    "sky-input": "wx-sky-ui/input/index"
  }
}

4. 在 WXML 中使用

<sky-button type="primary" round>确认提交</sky-button>
<sky-icon name="arrow_right" size="32rpx" />
<sky-input placeholder="请输入" clearable />

[!TIP] ⚡ 极致包体积优化与按需引入说明（必读）

由于 wx-sky-ui 是一个功能极其丰富、视觉动效饱满的高性能 Skyline 组件库，整包的代码体积相对较大。强烈建议您切勿在 app.json 中进行全局注册！ 否则会导致所有组件都被打包进小程序的主包，极易突破微信小程序官方的主包体积上限（2048 KB / 2 MB）从而导致上传失败。

请始终坚持在具体页面的 index.json 中进行页面级“按需引入”。微信小程序的 usingComponents 天然支持按需编译，只有被声明并实际使用的组件才会被打包进最终的生产环境代码中。

📊 优化前后包体积直观对比

| 编译/引入方式 | 本地开发物理大小 | 上传包实际大小 (剔除 .map 后) | 占主包上限比例 (2048KB) | 上传结果 | | :--- | :--- | :--- | :--- | :--- | | 全量引入（在 app.json 全局注册） | 1037.28 KB (1.01MB) | 约 500 KB | ~25.0% | ❌ 极易撑爆主包，导致上传失败 | | 按需引入（页面级仅引入 sky-icon） | 135.31 KB | 约 60 KB | ~2.9% | ✅ 极速上传，包体积极其轻量 |

💡 温馨提示：

1. 本地构建时，输出的组件包中包含了用于开发调试的 .map 源码映射文件（如 presets.js.map 等），所以本地物理体积看起来会偏大（约占一半体积）。
2. 微信开发者工具在进行 “上传/发布” 编译时，会自动过滤并剔除所有 .map 文件。因此，在按需引入后，微信真正在生产环境打包时的实际体积会非常小，完全不必担心体积压力。

自动化构建与开发指南

本项目采用 TypeScript + Sass/SCSS + Gulp 的现代化构建体系：

1. 安装开发依赖

npm install

2. 自动化构建与同步

# 启动一次性编译打包（将 src 编译至 miniprogram_dist 并同步至 example/components）
npm run build

# 挂起后台实时监听（推荐在本地开发和调整组件源码时开启）
npm run dev

# 清理构建产物
npm run clean

3. 代码规范检查

# ESLint 检查
npx eslint src/

# Prettier 格式检查
npx prettier --check src/

4. 微信开发者工具预览联调

1. 打开微信开发者工具，选择 "导入项目"。
2. 导入本项目下的 wx-sky-ui/example 目录。
3. 在模拟器或真机中预览组件效果。

设计与视觉规范

• 全 Flex 排版：Skyline 引擎不支持 Grid 布局，全量采用高性能 Flex 布局。
• 零图标体积压力：所有图标采用纯 SVG 路径渲染，无需外部字体图标库。
• Compositor 硬件加速动画：所有动画仅改变 transform 与 opacity，避开重排机制。
• HSL 色彩体系：统一使用 HSL 色彩空间，便于全局换肤与主题定制。

联系作者

如果你需要技术咨询、组件定制开发或商务合作，欢迎添加作者微信：

• 微信号：yoy999901
• 联系事由：wx-sky-ui 组件库技术咨询 / 定制开发 / 商务合作

[!NOTE] 添加时请备注来意（如：组件库咨询、项目合作等），以便快速通过验证。