Atomic Calendar Revive 事件处理管道 pipeline 源码剖析：排序、过滤与去重是如何实现的

【免费下载链接】atomic-calendar-reviveAn advanced calendar card for Home Assistant Lovelace.项目地址https://gitcode.com/gh_mirrors/at/atomic-calendar-revive点击查看免费下载Atomic Calendar Revive 是一款为 Home Assistant Lovelace 打造的进阶日历卡片支持 Google Calendar 与 CalDAV 日历。它最强大的地方在于事件处理管道pipeline从拉取原始事件到过滤、多日拆分、去重、排序、数量截断全部在一条清晰的流水线上完成。本文将带你读懂这条管道的设计与实现原理帮你理解maxDaysToShow、hideDuplicates、sortBy等配置项背后到底发生了什么。一、管道全景一次数据流的旅程 ️管道的核心实现在 src/lib/pipeline.ts对外暴露三个入口函数分别服务于卡片的三种展示模式入口函数服务视图说明fetchEventModeEvents事件列表模式计算日期窗口 → 拉取 → 处理fetchPlannerEvents计划Planner模式周视图窗口 → 拉取 → 处理fetchRawEventsprocessEvents日历月视图拉取整月数据后处理各视图的调用点分别在 src/lib/views/EventView.ts、src/lib/views/PlannerView.ts 与 src/lib/views/month-grid.ts。处理主函数processEvents的完整流程只有一屏src/lib/pipeline.ts#L197-L229可以概括为五步逐事件过滤不通过则直接丢弃continue多日事件拆分expandMultiDay把跨天事件切成每天一份二次过滤hideFinishedEvents隐藏已结束事件去重hideDuplicates合并同名同时间的重复事件排序 截断sortEvents排序后用maxEventCount限制数量二、第一步按日历实体并行拉取原始事件fetchRawEventssrc/lib/pipeline.ts#L259-L297为每个配置的日历实体构造一个calendars/{entity}?start...end...的 API 请求并用Promise.all并行执行。两个细节值得注意每个实体可以有自己的时间窗口实体级maxDaysToShow会收窄请求的end时间避免为只看今天的日历拉取整周数据失败隔离某个日历请求失败只会被记入failed数组不会让整张卡片挂掉视图层会据此给出降级提示三、核心一条过滤漏斗决定哪些事件能上卡 拉到的原始事件会依次穿过 9 道过滤器src/lib/pipeline.ts#L200-L215任何一道不过即被丢弃过滤器对应配置项作用passesAllDayBeforeWindowstartDaysAhead剔除在展示窗口开始前就已结束的整天事件passesDeclinedshowDeclined是否显示已被拒绝的受邀事件passesAllDayHiddenshowAllDayEvents是否隐藏整天事件passesBlocklistblocklist标题正则黑名单命中即丢弃passesBlocklistLocationblocklistLocation地点正则黑名单passesAllowlistallowlist标题正则白名单不命中即丢弃passesAllowlistLocationallowlistLocation地点正则白名单passesMaxDaysWindowmaxDaysToShow超出天数窗口的未来事件被剔除passesTimeOfDayWindowstartTimeFilter/endTimeFilter只保留落在指定时刻区间内开始的事件几个容易踩坑的设计点黑白名单匹配的是原始标题rawTitle而不是被titleReplace改写后的展示标题。这样即使你用titleReplace把Dinner Sushi前缀抹掉了allowlist: ^Dinner 依然能命中——这个行为有专门的回归测试保护src/tests/pipeline.test.ts#L60-L80Calendar 模式跳过窗口过滤passesAllDayBeforeWindow和passesMaxDaysWindow对月视图直接放行src/lib/pipeline.ts#L47-L51因为月网格需要展示当月所有格子maxDaysToShow的实体级覆盖实体级maxDaysToShow优先于全局值这正是多卡片滑动布局能各自看不同天的原理四、多日事件拆分showMultiDay 的幕后逻辑开启showMultiDay后跨天事件会在过滤器通过后被expandMultiDay展开src/lib/pipeline.ts#L145-L153EventClass.split()src/lib/event.class.ts#L273-L295按天深拷贝事件打上addDays、_isFirstDay、_isLastDay标记让每一天都有一份部分事件拆分后还要过一遍可见性窗口computeVisibilityWindow按模式算出起止范围只有落在窗口内的部分才会保留Event/Planner 模式Calendar 模式则保留全部实体级showMultiDay可以独立于全局开关生效方便每张卡片只看一天的滑动布局五、去重原理hideDuplicates 如何合并重复事件applyHideDuplicatessrc/lib/pipeline.ts#L157-L180采用经典的哈希键去重两遍扫描以标题|开始时间|结束时间拼接为键。相同的事件比如同一个事件同时同步到了两个日历实体只会保留第一条其余来源的日历名被追加进calendars列表第二遍把收集到的来源名用,拼接后写回事件的originName卡片上这条事件仍会显示所有来源日历信息不丢失这正是官方文档描述的行为based on summary, start time and end time见 docs/configuration/main.rst 第 35 行。对应测试见 src/tests/pipeline.test.ts#L141-L162。六、排序规则按天分桶 两种排序策略排序逻辑独立在 src/common/sort_events.ts 中分四步全局按startDateTime升序保证天的天然顺序按YYYY-MM-DD分桶逐天处理整天事件按标题字母序排列allDayBottom: true时反转并放到当天底部src/common/sort_events.ts#L24-L29sortBy: start普通事件按开始时间升序sortBy: milestone里程碑模式正在运行的事件排最前其余按距当前时间最近者排序已结束事件沉底src/common/sort_events.ts#L37-L74天内合并整天事件与时刻事件按allDayBottom决定上下位置跨天合并各天数组依序拼接天内的自定义排序不被破坏这个先分桶、桶内精排、再按桶序合并的结构避免了全局比较器里处理跨天、跨类型事件时的复杂性。七、数量截断maxEventCount 与 softLimit 的软硬两级限制最后的applyEventCountLimitsrc/lib/pipeline.ts#L182-L193实现了硬限制 软缓冲只设maxEventCount超出部分直接截断截掉的数量记入hidden卡片上显示 x hidden同时设softLimit事件数不超过maxEventCount softLimit时不截断——避免只多出 1 条就截断造成的观感跳动说明见 docs/configuration/event.rst 第 13 行排序发生在截断之前所以被保留的永远是时间上最靠前的事件八、三种模式下的行为差异一览 行为Event 模式Calendar 模式Planner 模式日期窗口maxDaysToShowstartDaysAhead整个可见月份plannerDaysToShow周窗口窗口前整天事件剔除保留剔除maxDaysToShow过滤生效跳过生效用plannerDaysToShow作基准showPastDaysOfWeek窗口锚定到本周一firstDayOfWeek感知——周窗口的对齐算法在getEventModeStartsrc/lib/pipeline.ts#L35-L43用当前星期几减去firstDayOfWeek得到偏移量负数时补 7从而把窗口起点回退到本周第一天。九、测试如何守护这条管道管道是纯函数式的数据加工层因此拥有非常完整的测试套件 src/tests/pipeline.test.ts540 行用vi.useFakeTimers固定系统时间逐一覆盖黑名单/白名单、hideDuplicates合并来源名、softLimit边界、单日窗口不泄漏次日整天事件、showPastDaysOfWeek的周日/周一周界回归等场景是理解每个过滤器预期行为最快的活文档。十、相关配置项速查主配置maxDaysToShow、maxEventCount、hideDuplicates、showDeclined、showAllDayEvents、hideFinishedEvents、sortBy、allDayBottomdocs/configuration/main.rst实体级过滤blocklist、allowlist、startTimeFilter、endTimeFilter、showMultiDaydocs/configuration/entity.rst事件模式扩展softLimit、showHiddenText、hiddenEventTextdocs/configuration/event.rst默认值定义src/defaults.ts理解了这条管道你就能解释卡片上大多数为什么这条事件没显示 / 为什么排在这个位置的问题——答案几乎都藏在processEvents那 30 行主干里。赞分享【免费下载链接】atomic-calendar-reviveAn advanced calendar card for Home Assistant Lovelace.项目地址https://gitcode.com/gh_mirrors/at/atomic-calendar-revive点击查看免费下载相关推荐github_preprocessing.py源码逐行剖析github-code去重与质量过滤的实现原理github_preprocessing.py源码逐行剖析github code去重与质量过滤的实现原理 github_preprocessing.py 是gitinspector国际化实现如何为项目添加新的语言翻译gitinspector国际化实现如何为项目添加新的语言翻译 gitinspector是一款强大的git仓库统计分析工具支持多语言国际化功能。本文将详细介绍人工智能大模型AI Agent多智能体金融科技后端前端Machine-Learning-for-Algorithmic-Trading-Second-Edition_Original中的100Alpha因子库构建盈利策略的秘密武器Machine Learning for Algorithmic Trading Second Edition_Original中的100Alpha因子库构上一篇fpinscala 幺半群实战用 Scala 3 given 定义积幺半群productMonoid下一篇一文看懂CodexSkillManagermacOS上的Codex技能管理神器让AI技能管理变简单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考