@composy/notice-center-core

@composy/notice-center-core

消息中心 — 面向企业应用的企业级统一消息聚合与管理面板核心库（渲染库架构，非 Web Component）。

notice-center-core 是一个框架无关的核心引擎：通过 NoticeCenter 类实例 + DOMRenderer + StyleManager 直接操作宿主 DOM 渲染消息聚合面板。内置消息分类（待办/通知/提及/系统）、优先级与状态管理（未读/已读/归档）、时间分组、关键字与多条件筛选、批量操作（批量已读/删除）、主题切换（亮/暗）、偏好设置（邮件/站内信/推送/免打扰）及完整的事件回调体系。核心库只承担框架无关的能力总线，packages/vue 另行提供 Vue 3 适配器；本包不依赖任何 UI 框架。

安装

# pnpm
pnpm add @composy/notice-center-core
# npm
npm install @composy/notice-center-core

目录结构

packages/core/
├── src/
│   ├── index.ts            # 统一导出入口
│   ├── types/index.ts      # 全部类型与接口定义
│   ├── core/               # notice-center.ts / event-emitter.ts / data-store.ts
│   ├── renderer/           # dom-renderer.ts / style-manager.ts
│   ├── theme/              # theme-manager.ts / tokens.ts（lightTokens/darkTokens）
│   └── utils/              # time.ts / search.ts / icons.ts
├── .ldesign/               # @composy/builder、ESLint、TypeScript canonical 配置
├── tsconfig.json           # 指向 .ldesign/tsconfig.json 的兼容入口
└── package.json

核心 API 详表

以下导出均严格来自 src/index.ts，按分组列出。

常量与核心（core/）

渲染器与主题（renderer/ theme/）

工具（utils/）

类型（types/）

使用示例

import { createNoticeCenter } from '@composy/notice-center-core'

const nc = createNoticeCenter({
  container: '#app',
  theme: 'light',
  categories: [{ key: 'todo', label: '待办', order: 1 }],
  onMessageClick: msg => console.info('点击消息', msg.id),
  onActionClick: (msg, action) => console.info('点击操作', action.label),
})

nc.addMessage({
  id: 'm1',
  title: '审批待办',
  summary: '有一个审批请求等待处理',
  category: 'todo',
  priority: 'high',
  status: 'unread',
  sender: '系统',
  createdAt: new Date().toISOString(),
})
nc.markAsRead(['m1'])
console.info('未读数：', nc.getUnreadCounts())
nc.setFilter({ keyword: '审批' })
nc.setTheme('dark')
nc.on('category:changed', cat => console.info('切换分类', cat))
nc.destroy() // 卸载时销毁

消息 content 可以包含基础富文本。详情渲染会保留常用文本格式标签和安全链接，并移除脚本、事件属性、内嵌媒体及不安全协议。外部操作链接只允许 http、https、mailto 和 tel。

全局设计变量

组件样式使用 packages/color 和 packages/size 生成的 --ld-* CSS 变量。宿主应用需要先注入颜色、字体、间距、圆角和像素变量；核心包不再内置独立硬编码色板或尺寸。destroy() 会恢复挂载容器原有的 --nc-* 样式变量与 data-nc-theme 属性。

构建脚本 & 验证命令

产物说明

exports 暴露多入口；根入口按 types/import/require/default 映射到 es、lib：

• es/ — ESM 产物（index.js + index.d.ts），import 与类型入口（module/types 指向）。
• lib/ — CJS 产物（index.cjs），require 入口（main 指向 lib/index.cjs）。
• esm/ — 对应模块结构的 ESM 源文件目录。
• dist/ — UMD 浏览器产物（index.js/index.min.js），unpkg/jsdelivr/browser 指向。

子路径别名（./core/*、./renderer/*、./theme/*、./types、./utils/*）均同时解析到 es 与 lib。sideEffects: false，可安全 tree-shaking。

备注

• 依赖：dependencies 为空，无运行时三方依赖；devDependencies 含 @composy/builder、@composy/testing、@composy/release、@antfu/eslint-config、typescript。发布注册中心 http://npm.longrise.cn:6286/。
• 渲染库架构：非 Web Component、无 Shadow DOM；直接操作宿主 DOM，样式由 injectStyles() 注入 <head>，destroy() 释放渲染与事件。
• 浏览器依赖：使用 document/window，仅限浏览器环境，SSR 需环境判断。
• 容器解析：container 为字符串选择器时找不到元素会抛 [NoticeCenter] Container not found。
• 样式实现：组件使用 .nc-* 内部选择器，并将 --ld-* 全局设计变量映射到容器级 --nc-* 主题变量；尺寸、颜色来自宿主提供的 Color/Size token。
• 正文安全：消息详情采用允许列表清洗富文本，链接协议经过校验；输入标题、摘要、分类标签和操作按钮文案按文本渲染。

License

MIT

Runtime safety notes

• NoticeCenter derives the DOM owner from container.ownerDocument, so containers in an iframe or detached document keep their styles and generated nodes in that document.
• injectStyles(ownerDocument?) returns an idempotent release function. Multiple instances in one document share #nc-styles; the style element is removed after the last release.
• DataStore treats NoticeMessage.id as a stable key. Repeated IDs are upserted, batch order is preserved for new messages, and returned messages remain isolated snapshots.
• normalizeSearchFilter trims keywords, drops invalid dates, and normalizes reversed date ranges. Invalid message timestamps never produce NaN relative-time output.
• sanitizeMessageContent(html, ownerDocument?) keeps the existing allowlist and can parse content using the container's owner document.