Slidev 手绘风格标注指南：用 v-mark 指令与 Rough Notation 为幻灯片元素添加高亮标记

Slidev 手绘风格标注指南用 v-mark 指令与 Rough Notation 为幻灯片元素添加高亮标记【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev在面向开发者演示的 Slidev 幻灯片中我们经常需要在讲解过程中逐步强调某个关键词、框选一段代码或给一行结论划线。Slidev 自 v0.48.0 起内置了 Rough Notation手绘风标注库集成通过v-mark指令即可为任意 DOM 元素添加下划线、圆形、高亮、方框等手绘风格的标注并可与点击动画click体系完全打通。读完本篇你将掌握v-mark的全部用法类型、颜色、点击时机、高级选项并理解它在源码层面的触发机制能直接在自己或团队的 Slidev 演示中落地使用。一、什么是 Rough MarkersRough Notation 是一套以“手绘/涂鸦”视觉风格渲染标注的库其标注边缘带有轻微抖动与颗粒感观感上更接近手写在纸上的随意批注而非机械的 CSS 描边。Slidev 将其以内置形式集成到演示框架中任何被v-mark指令标记的元素都会在幻灯片渲染后由一个底层的 Rough 标注对象驱动绘制。从实现上看该功能位于 packages/client/modules/v-mark.ts它通过slidev/rough-notation的annotate(el, options)为 DOM 元素创建标注实例再结合点击导航状态决定标注的显示与隐藏。v-mark指令与v-click、v-drag、v-motion等一并由 packages/client/setup/main.ts 在应用初始化时全局注册app.use(createVMarkDirective())因此无需额外安装或配置在任意 Slidev 项目中开箱即用。适用前提该功能自 v0.48.0 起可用需要 Slidev 客户端版本不低于该版本。二、快速上手最小示例在最简形态下只需给任意元素加上v-mark它就会使用默认的underline下划线类型并在首次点击后显示span v-markImportant text/span把这段代码放进一页slides.md的某个 Vue 组件块或普通 Markdown 行内点击幻灯片后你就能看到 Important text 被一条手绘下划线标出。v-mark可以作用在文本、图片、代码块、div等任何可承载 DOM 的元素上天然适合“行内标注 外围框选”两类场景。三、标注类型Type通过修饰符modifier选择标注形状默认值为underline。代码层面支持的修饰符与 Rough Notation 的类型一一对应见 packages/client/modules/v-mark.ts 中vMarkModifiers的定义修饰符对应的标注类型效果v-mark.underlineunderline下划线默认v-mark.circlecircle圆形/椭圆形环绕框选v-mark.boxbox矩形方框v-mark.highlighthighlight底色高亮v-mark.strike-throughstrike-through删除线/贯穿线v-mark.crossed-offcrossed-off交叉十字通常用于“划掉/作废”v-mark.bracketbracket大括号括注为了方便书写源码还提供了一组类型别名修饰符与上述类型等价strike、linethrough、line-through→strike-throughcross、crossed→crossed-off用法示例span v-mark.underlineUnderlined/span span v-mark.circleCircled/span span v-mark.boxBoxed/span span v-mark.highlightHighlighted/span span v-mark.strike-throughStruck through/span在对象写法中则通过type字段指定例如{ type: circle }。修饰符与对象写法可以在同一个元素上共存见下文“对象写法与优先级”。四、标注颜色Colorv-mark对颜色的处理有两种途径。内置颜色修饰符。直接以颜色名作为修饰符例如v-mark.red。源码中支持的内置颜色与 UnoCSS 主题色一致包括black、blue、cyan、gray、green、indigo、lime、orange、pink、purple、red、teal、white、yellow。其底层实现是把对应颜色追加为 CSS 类如text-red再在渲染时同步到标注实例上源码中addClass会将类名合并进options.class。由于用到了 UnoCSS 的按需扫描源码中相关行带有unocss-include注释以保证这些工具类能被正确生成。span v-mark.redRed marker/span span v-mark.blueBlue marker/span span v-mark.circle.orangeCircled and orange/span自定义颜色。当内置色无法满足需求时使用对象语法传入任意合法的颜色值span v-mark{ color: #234 }Custom color/span值得注意类型修饰符与颜色修饰符可自由组合且不冲突例如v-mark.underline.orange、v-mark.circle.orangeSlidev 官方演示模板 demo/starter/slides.md 中即大量使用了这种组合来讲解该指令。五、点击时机与 v-click 体系打通v-mark的显示节奏与v-click完全一致这是它最有价值的行为特性标注默认不在页面初始渲染时出现而是在导航到对应点击序号后才“画”出来。它支持与v-click相同的自定义点击值span v-mark5Appears on click 5/span span v-mark1Next click/span这里5表示从第 5 次点击起显示1表示在父级v-click/v-click容器的下一次点击后显示。底层实现中v-mark指令复用了v-click模块导出的resolveClick函数见 packages/client/modules/v-click.ts 中resolveClick把at值解析成具体的点击区间与激活状态再通过watchEffect监听该状态激活时调用 Rough 标注的show()未激活则调用hide()。因此在演示时你可以实现“先抛出文字 → 再单击圈出重点”的逐步讲解节奏而不需要把标注做成一次性静态样式。六、对象语法与高级选项当需要同时控制类型、颜色、出现时机等多个维度时可以向v-mark传入一个对象这是最完整的用法span v-mark{ at: 5, color: #234, type: circle } Important text /span该对象等价于在第 5 次点击后用自定义颜色#234的圆形圈出该文字。注意上方示例中使用的 Vue 绑定语法v-mark{ ... }是在.vue单文件组件内直接书写的方式在slides.md的 Markdown 正文里如需同样的字面量对象可把绑定值写在引号中或将该片段放入 Vue 组件块中Slidev 会对 Markdown 内的 Vue 指令作对应解析。从源码类型定义看RoughDirectiveOptions对象支持以下字段字段说明type标注类型underline、circle、box、highlight、strike-through、crossed-off、bracket缺省为underlinecolor标注颜色值可为任意合法颜色字符串at触发点击值接受数字、1等原始RawAtValue值class追加到标注实例上的 CSS 类内置颜色修饰符即通过它注入text-*类delay延迟毫秒见下文动态修饰符opacity标注透明度0–1animationDuration手绘动画绘制时长毫秒级此外Rough Notation 底层还暴露如描边宽度、内边距、绘制迭代次数等更细粒度参数可通过对象透传至底层标注实例具体以当前依赖的slidev/rough-notation类型定义RoughAnnotationConfig为准。七、实用的动态修饰符延迟与透明度除类型与颜色外v-mark还通过“动态修饰符”支持延迟和透明度其实现同样位于 packages/client/modules/v-mark.tsvMarkModifiersDynamic延迟v-mark.delay300表示 300 毫秒后开始绘制delay后不带数字时如v-mark.delay默认取300毫秒。你也可以用绑定值提供数字如v-mark.delay500。透明度v-mark.op50将透明度设为0.5不带数字的v-mark.op默认视为100即不透明。其原理是把整数值除以 100 后写入标注的opacity选项。示例span v-mark.circle.delay3005Circled after a short delay/span span v-mark.highlight.op40Soft highlight at 40% opacity/span这类修饰符很适合做“慢节奏强调”或“弱化高亮”的视觉层级控制。需要注意的是若修饰符无法匹配任何已知的类型、颜色或动态规则客户端会在控制台输出[Slidev] Invalid modifiers for v-mark:的警告信息对应源码中的console.warn分支便于你排查拼写错误。八、源码运行机制标注如何被创建与同步深入 packages/client/modules/v-mark.ts 可以看到完整的执行链路理解它有助于排查与扩展指令挂载mounted当带v-mark的元素被挂载时先通过useNav()获取演示导航状态含是否为打印/导出模式isPrintMode随后依据绑定值构造一个响应式的options若绑定值是对象则展开之否则视为{ at: bindingValue }遍历元素上的所有修饰符在vMarkModifiers与vMarkModifiersDynamic中逐一定位并改写选项未匹配的修饰符会被收集并在控制台告警合并后若未指定type则兜底为underline。创建标注实例调用annotate(el, options)生成 Rough 标注但此时并不急于显示。接入点击体系调用resolveClick(el, binding, at)解析点击区间若元素没有可用的点击上下文例如没有父级v-click且自身没有at则直接annotation.show()立即显示。响应式同步通过watchEffect监听点击激活状态激活时执行show()否则执行hide()同时若options中带有class或color会在每次变化时同步写入标注实例。打印/导出适配当处于打印模式时源码会把animationDuration压缩为 1 毫秒确保导出 PDF 时标注以完成态呈现而不会截取到动画中间帧。卸载清理指令unmounted时调用内部watchStopHandle停止监听避免内存泄漏。这套链路意味着v-mark的显隐状态完全由全局点击计数器驱动因此在演示者模式、导出与时间轴click 进度条中都能与其它v-click元素保持同一步调。九、实战建议与组合技巧与 v-click 容器嵌套将v-mark元素放进v-click/v-after容器或用v-mark1实现相对父级点击延后的标注可构建“句子出现 → 关键术语被圈出”的两段式讲解。给代码加标注Rough 标注作用于任意元素直接给代码块中的code片段或行包装上v-mark.circle可替代部分人工画圈步骤。层级排布v-mark.highlight.op40这类低透明度高亮适合做背景强调配合circle/box做主标注可在同一页面形成主次分明的信息层级。多轮点击呈现不同标注一个元素上同时叠加多个v-mark实例分别绑定不同at值与不同颜色/类型可以在一次演示中分阶段“换一种画法”。如果你希望查看该指令在当前仓库中的真实产出可运行官方 starter demoslidev demo/starter详见 demo/starter/slides.md其中一段围绕v-mark.red7、v-mark.circle.orange8、v-mark.underline.orange展开实际体验点击后手绘标注逐步出现的效果。更系统的点击动画总览可参阅 docs/guide/animations.md若还想了解另一种更精细的点击高亮方案在点击到具体行时以不同颜色/动画区分当前与已读行可参阅 docs/features/click-marker.md。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考