🚀 三步集成

1

引入框架

通过 <script defer> 加载，内联执行初始化。

<script defer src="data-context-card.umd.js" onload="DataContextCard.init()"></script>
2

定义模板

创建 <template> 作为投影内容。

<template id="card"> <div>投影内容</div> </template>
3

声明触发

给触发元素添加 data-context-card 属性，值为模板 ID。

<span data-context-card="card">悬停查看</span>

以下四个示例基于真实的 data-context-card 协议。将鼠标悬停在触发区域上即可看到上下文投影卡片。

1 基础文本投影
悬停查看提示
触发元素：<span class="demo-trigger-plain" data-context-card="demo-tooltip"> 最简单的文本投影场景，适合工具提示、帮助信息
2 富媒体卡片
thumb
城市天际线
悬停查看完整详情卡片
投影 ⟩
触发元素：<div class="demo-trigger-rich"> … <span data-context-card="demo-media">投影 ›</span> 悬停「投影 ›」时投影图片、文字描述与交互按钮的完整卡片
3 表格行详情
项目状态进度
框架核心重构 ● 进行中 75%
单元测试覆盖● 待办30%
文档编写● 待办10%
触发元素：<tr data-context-card="demo-table"> (整行) 表格行悬停显示任务详情投影卡片，适合后台管理系统
4 事件监听 + Portal
悬停触发 dcc:mount 事件
等待事件...
触发元素：<div class="con" data-context-card="demo-events"> 框架在 mount/unmount 时触发自定义事件，方便 React/Vue Portal 集成

🎯 核心协议 （必须了解）

属性说明
data-context-card="id"标记触发元素，值为 <template> 的 ID
data-context-card-size="N"覆盖默认 25vw 尺寸（如 40 → 40vw）
<template id="id">定义投影内容，框架自动克隆到浮动卡片
DataContextCard.init()激活运行时，扫描所有 [data-context-card] 并绑定

⚙️ 常用配置 （建议了解）

初始化前修改 DataContextCard.config：

配置项默认值说明
offset12卡片与触发元素的间距 (px)
edgePadding16卡片与视口边缘的最小间距 (px)
hideDelay120隐藏延迟 (ms)
DataContextCard.config.offset = 16 DataContextCard.init()

自定义事件

事件说明
dcc:mount卡片渲染完成时触发。外部框架（React/Vue 等）可监听此事件，获知何时将子组件挂载到卡片 DOM 内。
e.detail.mode === 'template' 表示内容来自模板克隆；'portal' 表示未找到模板，等待外部注入。
dcc:unmount卡片即将隐藏时触发，外部框架在此事件中执行清理（卸载 Portal 子组件、释放资源等）
document.getElementById('data-context-card-container') .addEventListener('dcc:mount', (e) => { console.log('mode:', e.detail.mode) // 'template' | 'portal' })

🔧 进阶 （按需查阅）

PC 端尺寸微调
配置项默认说明
pc.minWidth280卡片最小宽度 (px)
pc.maxWidth480卡片最大宽度 (px)
pc.maxHeight560卡片最大高度 (px)
mobile.maxWidthRatio0.92移动端最大宽度占视口比
mobile.maxHeightRatio0.75移动端最大高度占视口比
animationDuration160动画时长 (ms)
API 方法
DataContextCard.init(selector?)
全局初始化，默认选择器 [data-context-card]
DataContextCard.bind(el)
手动绑定单个元素
DataContextCard.bindAll(selector)
手动批量绑定
DataContextCard.unbind(el)
解绑单个元素
DataContextCard.show(el)
编程式显示
DataContextCard.hide()
编程式隐藏（带延迟）
DataContextCard.closeActive()
立即强制隐藏
DataContextCard.getProjectionSlot()
获取内容容器，用于 Portal 接管
DataContextCard.destroy()
完全销毁运行时（SPA 路由切换使用）
框架集成示例
HTML (UMD)
<script src="data-context-card.umd.js"></script> <script>DataContextCard.init()</script>
ESM
import DataContextCard from 'data-context-card' DataContextCard.init()
React
useEffect(() => { DataContextCard.init() return () => DataContextCard.destroy() }, [])
Vue
onMounted(() => DataContextCard.init()) onUnmounted(() => DataContextCard.destroy())
其他
data-portal — 标记框架不管理的 DOM 容器。当模板内部有 data-portal 元素时，卡片隐藏不会清空该容器内容，确保外部框架（React Portal、Vue Teleport 等）渲染进去的子组件在显示/隐藏切换中保持状态不丢失。
data-dcc-close — 模板内关闭按钮标记
📱 移动端自动识别触摸设备，点击切换显示/隐藏
📘 内置 TypeScript 类型声明，无需 @types
🌍 支持 Chrome · Edge · Safari · Firefox 等所有现代浏览器