▶_MiniApp Toolkit

WX Calendar

UI 库活跃维护

微信小程序日历组件，支持年/月/周日程视图、Skyline 渲染、农历插件、多端兼容（Donut/UniApp/Taro），TypeScript 原生支持，npm 包 @lspriv/wx-calendar。

★ 399🕒 最近更新 2026-01
官网文档
日历calendar微信小程序Skyline农历日程

特性

  • 年/月/周日程视图切换
  • 支持 Skyline 和 WebView 双渲染模式
  • 插件扩展机制（农历、节假日等）
  • TypeScript 原生类型支持
  • npm 安装 + 微信构建 npm
  • 多端兼容（Donut/UniApp/Taro）
  • 160+ npm 版本持续迭代

详细文档

WX Calendar — 微信小程序日历组件#

资源概述#

WX Calendar 是一款功能丰富的微信小程序日历组件，由 lspriv 个人开发维护，GitHub 仓库 lspriv/wx-calendar 拥有 399 stars / 56 forks，MIT 协议。项目支持年/月/周日程视图切换、Skyline 和 WebView 双渲染模式、插件扩展机制（农历/节假日等），是微信小程序日历场景的高质量解决方案。

核心亮点：npm 包 @lspriv/wx-calendar 已发布 160+ 版本持续迭代；TypeScript 原生编写提供完整类型提示；支持 Skyline 渲染引擎获得更流畅的滚动体验；通过插件机制可灵活扩展农历、节假日等功能；兼容 Donut、UniApp、Taro 多端框架。

设计规范#

  • 双渲染模式：支持 Skyline（高性能原生渲染）和 WebView 两种模式，Skyline 模式下获得 60fps 流畅滚动
  • 视图切换：提供 month（月视图）、week（周视图）、schedule（日程视图）三种模式，用户可自由切换
  • rpx 适配：全部尺寸使用 rpx 单位自动适配不同屏幕
  • 主题定制：通过 CSS 变量和组件属性自定义颜色、字体等视觉风格
  • 农历支持：通过 @lspriv/wc-plugin-lunar 插件集成农历显示
  • 基础库要求：最低 SDKVersion >= 3.0.0

审核规范#

WX Calendar 作为 UI 组件库本身无需审核。使用该组件构建的小程序提交微信审核时需注意：

  • 日历交互行为需符合微信设计规范
  • Skyline 模式需在 app.json 中配置 "renderer": "skyline" 且基础库 >= 3.0.0
  • Donut 平台需在本地设置中开启「使用 SWC 编译脚本文件」和「编译 worklet 代码」

开发指南#

快速上手#

code
# 安装
npm i @lspriv/wx-calendar -S
code
// 页面 page.json
{
  "usingComponents": {
    "calendar": "@lspriv/wx-calendar"
  }
}
code
<!-- 页面 page.wxml -->
<calendar id="calendar" bindload="handleLoad" />
code
// 页面 page.ts
import { WxCalendar } from '@lspriv/wx-calendar/lib';
import { LunarPlugin } from '@lspriv/wc-plugin-lunar';

// 注册农历插件
WxCalendar.use(LunarPlugin);

Page({
  handleLoad(detail) {
    const calendar = this.selectComponent('#calendar');
    // 获取选中日期、切换视图等操作
  }
});

类型检查配置#

由于小程序构建 npm 的特殊性，需在项目根目录配置路径映射：

code
// tsconfig.json 或 jsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@lspriv/wx-calendar/*": ["./node_modules/@lspriv/wx-calendar/dist/*"]
    }
  }
}

多端使用#

Donut 平台：需在开发者工具 → 详情 → 本地设置中开启：

  • 使用 SWC 编译脚本文件
  • 编译 worklet 代码
  • Android XWeb SDK（在 project.miniapp.json 中开启）

UniApp：

  1. 创建 components/wx-calendar/ 目录，拷贝 dist 文件
  2. 在 pages.json 的 globalStyle 中配置 usingComponents

Taro： 使用官方 Taro 插件 @lspriv/plugin-taro（注意：引入原生组件后将失去多端转换能力）

常见陷阱#

  • selectComponent 时机：必须在 bindload 事件回调后执行 selectComponent('#calendar')，否则组件可能未初始化完成
  • Skyline 配置：Skyline 模式需 app.json 中正确配置 renderer，且不支持部分 WebView 专属 CSS
  • npm 构建依赖：必须执行微信开发者工具的「构建 npm」步骤，否则组件路径无法解析
  • 类型提示：不配置 tsconfig/jsconfig paths 将无法获得 TypeScript 类型提示
  • 插件依赖：农历等功能依赖独立插件包，需单独安装 @lspriv/wc-plugin-lunar

生态资源#

推荐框架#

  • 微信小程序原生框架（最佳兼容性，Skyline 原生支持）
  • Donut 跨端框架（原生支持）
  • UniApp（通过拷贝 dist 文件方式集成）
  • Taro（通过 @lspriv/plugin-taro 插件集成）

推荐 UI 库#

  • WX Calendar 本身（日历场景专用）
  • 通用 UI 库：Vant Weapp、TDesign miniprogram、Wot Design Uni

社区资源#

版本更新#

  • 最新稳定版：v1.8.4（2025-02-15）
  • 最新 Alpha：v1.8.5-alpha.4（2026-01-12）
  • NPM 发布次数：160+ 版本
  • 维护状态：✅ 活跃维护中
  • 许可证：MIT
  • 创建时间：2021-04-08
  • 贡献者：1 人（lspriv，503 commits）
  • 最近动态：持续 Alpha 迭代，预览页面更新，Skyline 支持

支持平台

微信小游戏T1微信小程序T0