@composy/announcement-vue

@composy/announcement-vue

@composy/announcement-core 的 Vue 适配层：提供 AnnouncementBoard / AnnouncementMarquee / AnnouncementModal 三个组件、对应组合式函数与全局注册插件，公告逻辑全部保留在框架无关核心包中。

✨ 核心能力

• 🧩 声明式组件：三个核心形态均有对应 Vue 组件，Props 响应式同步，主题与 token 更新不重建实例
• 🔁 v-model 弹窗：AnnouncementModal 支持 v-model 控制显隐
• 🧰 组合式函数：useAnnouncementBoard / useAnnouncementMarquee / useAnnouncementModal 管理实例与响应式状态（如 unreadCount）
• 🔌 全局插件：AnnouncementPlugin / createAnnouncementPlugin(options?) 全局注册组件
• 🎨 Token 化样式：复用核心 ldesign-announcement-* 类名前缀与 --ldesign-announcement-* CSS 变量
• 🔁 双版本兼容：基于 vue-demi，Peer 依赖 vue ^2.7.0 || ^3.5.32

📦 安装

pnpm add @composy/announcement-vue vue

• Peer 依赖：vue ^2.7.0 || ^3.5.32
• 运行依赖：@composy/announcement-core ^0.0.1、vue-demi

🚀 快速开始

<script setup lang="ts">
import type { Announcement, ThemeTokenOverrides } from '@composy/announcement-vue'
import {
  AnnouncementBoard,
  AnnouncementMarquee,
  AnnouncementModal,
} from '@composy/announcement-vue'
import { ref } from 'vue'

const announcements = ref<Announcement[]>([])
const modalVisible = ref(false)
const activeAnnouncement = ref<Announcement | null>(null)
const currentPage = ref(1)
const readIds = ref<string[]>([])

const themeTokens: ThemeTokenOverrides = {
  light: {
    colorPrimary: 'var(--ld-primary-default)',
    spacingLg: 'var(--ld-spacing-xl)',
  },
}

function handleRead(announcement: Announcement) {
  // 已读上报：记录并同步到消息中心
  readIds.value = [...readIds.value, announcement.id]
}

function handlePageChange(page: number) {
  currentPage.value = page
}

function openAnnouncement(announcement: Announcement) {
  activeAnnouncement.value = announcement
  modalVisible.value = true
}
</script>

<template>
  <AnnouncementBoard
    :announcements="announcements"
    show-summary
    theme="system"
    @read="handleRead"
    @page-change="handlePageChange"
  />

  <AnnouncementMarquee :announcements="announcements" separator=" | " @click="openAnnouncement" />

  <AnnouncementModal
    v-if="activeAnnouncement"
    v-model="modalVisible"
    :announcement="activeAnnouncement"
    :theme-tokens="themeTokens"
  />
</template>

📖 API 参考

组件与事件

Props 与核心配置同名对齐（Board 仍由组件内部容器承载；Modal 可选传入 container 指定弹窗挂载文档），如 Board 的 announcements、show-summary、theme、theme-tokens；Modal 支持 v-model、container 和多文档挂载。

组合式函数

import { useAnnouncementBoard } from '@composy/announcement-vue'

const { create, setAnnouncements, setTheme, setThemeTokens, markAllAsRead, unreadCount } =
  useAnnouncementBoard()

create(container, { announcements, showSummary: true })
setAnnouncements(nextList)
setTheme('dark')
setThemeTokens({ colorPrimary: 'var(--ld-primary-default)' })
markAllAsRead()

if (unreadCount.value > 0) {
  // 展示未读角标
}

• useAnnouncementBoard()：返回实例 ref、unreadCount 响应式未读数，以及 create(container, config?)、数据增删改（setAnnouncements / addAnnouncement / updateAnnouncement / removeAnnouncement / clearAnnouncements）、已读管理（markAsRead / markAllAsRead）、视图控制（setCategory / setSearch / setPageSize / setSortOptions / setPage / openDetail / closeDetail / setUnreadOnly / getPagination / getStats）、主题与文案（setTheme / setThemeTokens / setLocale）、批量配置（updateOptions）与 refresh / destroy
• useAnnouncementMarquee()：播报条实例的创建、播放控制（play / pause / isPlaying）与运行时调整（setSpeed / setDirection / setSeparator / updateOptions / refresh）
• useAnnouncementModal()：弹窗实例的创建、开关控制（open / close / isOpen）、内容热更新（setAnnouncement）与配置更新（updateOptions）

运行时同步约定

• Board 的 announcements、pageSize、theme、themeTokens、locale、unreadOnly 等变化通过 core 运行时 API 就地生效，不重建实例；
• Marquee 的 speed / direction / separator / pauseOnHover 等同样走 setter 热更新；
• Modal 的 announcement 引用变化通过 setAnnouncement 就地刷新（弹窗打开中也即时生效），展示配置变化通过 updateOptions 应用；
• 仅结构性配置（如 categories、renderContentAs、hideExpired 等）变化才会重建底层实例。

插件

import { AnnouncementPlugin } from '@composy/announcement-vue'
import { createApp } from 'vue'

createApp(App).use(AnnouncementPlugin)
// 或使用工厂：createApp(App).use(createAnnouncementPlugin(options))

类型重导出

主入口重导出核心类型：Announcement、Attachment、AnnouncementCategory、AnnouncementPriority、AnnouncementSortOptions、AnnouncementStats、AnnouncementUpdate、ContentRenderMode、MarqueeConfig / MarqueeInstance、ModalConfig / ModalInstance、ThemeMode、ThemeTokenOverrides、ThemeTokens 等，以及 categoryLabels、priorityLabels、zhCNLocale、enUSLocale、defaultLocale、lightTokens、darkTokens 运行时常量。

🎨 样式与主题

• 组件复用核心样式体系：类名 ldesign-announcement-*，CSS 变量 --ldesign-announcement-*。
• 默认颜色与尺寸引用由 packages/color 和 packages/size 生成的 var(--ld-*) 变量。宿主应用需加载对应的 Color 与 Size CSS 变量，或通过主题覆盖提供自定义变量。
• 通过 Props theme / theme-tokens / locale 或组合式函数的 setTheme() / setThemeTokens() / setLocale() 在运行时切换，无需重建实例。

🔨 构建产物与验证

使用 @composy/builder 构建，产出 dist/（浏览器 bundle 与 CSS）、es/、lib/ 等产物。

验证命令（取自包 package.json）：

pnpm build              # Builder + 产物归一化和 exports 检查
pnpm type-check         # ESM / Vue SFC 类型检查
pnpm type-check:cjs     # CJS / Vue SFC 类型检查
pnpm lint:check         # 使用 .ldesign/eslint.config.js 严格检查

Builder、ESLint 与 TypeScript 的权威配置分别位于 packages/vue/.ldesign/；根目录配置文件只保留兼容转发入口。Vue 适配包依赖 packages/core，构建前应先完成 Core 构建。

🔗 相关链接

• 工作区总览
• @composy/announcement-core — 核心库完整 API、数据模型与主题约定