Tiptap Twitch 扩展tiptap/extension-twitch使用指南嵌入视频、直播频道与剪辑的完整方案【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptaptiptap/extension-twitch是 Tiptap 官方提供的无头headless节点扩展用于在富文本编辑器中内嵌 Twitch 直播流、点播视频VOD与剪辑Clip支持自动播放、静音、起始播放时间等可定制参数并允许通过节点属性实现单条嵌入覆盖全局配置。阅读完本文你将掌握该扩展的安装配置、URL 解析规则、嵌入渲染与回读机制以及如何在 React / Vue 工程中通过setTwitchVideo命令与粘贴规则真正落地使用。本扩展从属于 Tiptap 3.x 系列当前仓库版本为 3.30.3其发布与修复历史完整记录在 packages/extension-twitch/CHANGELOG.md3.0.0 首次发布3.14.0 作为 Minor Change 引入完整能力见 twitch.ts 与 utils.ts3.23.2 修复了 Twitch/YouTube 嵌入在 HTML 回载时丢失原始视频、剪辑、频道或播放列表 URL 的问题其余版本均为随 tiptap/core 的依赖同步升级Patch Changes。安装与依赖该扩展作为独立 npm 包发布包元数据见 package.json。它采用 ESM 优先的模块格式同时导出 CJS 与类型声明main/module/types与exports映射均已配置。tiptap/core同时出现在peerDependencies与devDependenciesworkspace 引用因此你的项目中需先安装与扩展同版本的 core# 使用与 tiptap/core 相匹配的版本 pnpm add tiptap/extension-twitch # 或 npm / yarn 等任意包管理器扩展本身没有运行时外部依赖渲染时生成的iframe直接指向 Twitch 官方播放器player.twitch.tv/clips.twitch.tv/embed无需申请 API Key。快速上手在编辑器中加入 Twitch 节点安装后将Twitch加入扩展列表并用parent选项指定承载页面的域名即可工作。以 React 为例完整可运行示例见 demos/src/Nodes/Twitch/React/index.jsximport { EditorContent, useEditor } from tiptap/react import StarterKit from tiptap/starter-kit import Twitch from tiptap/extension-twitch const editor useEditor({ extensions: [ StarterKit, Twitch.configure({ // 当前页面域名Twitch 官方要求 parent 必须匹配 iframe 宿主域名 parent: window.location.hostname, allowFullscreen: true, }), ], content: div>editor.commands.setTwitchVideo({ src: https://www.twitch.tv/videos/1234567890, width: 800, height: 450, autoplay: true, muted: true, time: 1h2m3s, // 仅对点播视频生效 })命令返回booleanURL 非法时返回false且不产生任何内容变更。真实演示React/Vue 双实现里用输入框控制宽高并调用该命令demo 源码 中做了Math.max(320, width)、Math.max(180, height)这类下限约束可作参考。支持的 Twitch URL 类型与解析扩展围绕三类 Twitch 内容工作其 URL 匹配规则由 utils.ts 中的TWITCH_REGEX定义类型支持的 URL 形态说明点播视频 VODhttps://twitch.tv/videos/1234567890、https://www.twitch.tv/videos/1234567890匹配/videos/数字ID剪辑 Cliphttps://twitch.tv/某频道/clip/ClipName-123、https://clips.twitch.tv/ClipName含www.前缀频道内剪辑与clips.twitch.tv短链直播频道 Channelhttps://twitch.tv/某频道、https://www.twitch.tv/某频道形如LofiGirl的频道名正则同样允许 URL 携带任意 query 参数(\?.*)?结尾因此在粘贴/插入?filterarchivessorttime这类带查询串的链接时扩展会安全剔除多余参数、只保留嵌入所需的标识信息详见下文渲染与测试。从源码结构可以推断URL 到“类型 ID”的映射由工具函数getTwitchIdentifier统一完成getTwitchIdentifier(https://www.twitch.tv/videos/1234567890) // { type: video, id: 1234567890 } getTwitchIdentifier(https://www.twitch.tv/examplechannel/clip/ExampleClipName-ABC123) // { type: clip, id: ExampleClipName-ABC123 } getTwitchIdentifier(https://www.twitch.tv/examplechannel) // { type: channel, id: examplechannel }这些函数与正则均从 packages/extension-twitch/src/index.ts 对外导出可在编辑器之外的场景直接复用例如表单预校验、播放链接转换。配置选项Options详解Twitch节点通过Node.createTwitchOptions定义全部选项的默认值见 twitch.ts 的addOptions()选项类型默认值作用addPasteHandlerbooleantrue是否启用粘贴/拖入 Twitch URL 自动转为嵌入节点的规则allowFullscreenbooleantrue是否允许播放器全屏渲染为 iframe 的allowfullscreen与播放器 query 参数autoplaybooleanfalse是否自动播放mutedbooleanfalse是否默认静音浏览器自动播放策略下通常需要与 autoplay 搭配timestring \| undefinedundefined起始播放时间格式形如1h2m3s仅对点播视频生效不适用于剪辑与频道parentstringlocalhost承载嵌入的父级域名Twitch 官方要求必填且需与页面域名一致生产环境必须显式配置为你的域名heightnumber480iframe 高度像素widthnumber640iframe 宽度像素HTMLAttributesRecordstring, any{}附加到 iframe 上的 HTML 属性例如{ class: foo }inlinebooleanfalse节点是否作为行内元素。为false时节点组为block为true时组为inline配置示例Twitch.configure({ parent: example.com, // 必须替换为实际部署域名 allowFullscreen: true, autoplay: true, muted: true, // 自动播放策略通常要求同时开启 width: 1280, height: 720, HTMLAttributes: { class: twitch-embed }, })选项与属性的优先级per-embed 覆盖3.14.0 引入的“属性级覆盖”attribute-level overrides是这套配置体系的关键设计autoplay、muted、time以及width、height同时既可以是全局选项也可以是单个节点的attrs。渲染时按“节点属性优先于全局选项”合并见 twitch.ts 的renderHTML中HTMLAttributes.autoplay ?? this.options.autoplay这类表达式。即全局默认全自动播放时某个具体视频节点仍可通过自己的autoplay: false关闭。从 URL 到 iframe嵌入渲染原理Twitch节点把“用户友好的分享链接”转换渲染为“Twitch 官方播放器嵌入地址”核心链路为用户URL → getTwitchIdentifier(识别类型ID) → getEmbedUrlFromTwitchUrl(组装 player.twitch.tv / clips.twitch.tv/embed) → renderHTML 输出 div>div>Twitch.configure({ parent: example.com, addPasteHandler: false, })测试与行为保障扩展的行为有较完整的自动化测试覆盖packages/extension-twitch/tests/twitch.spec.ts可以作为使用时理解行为边界的“活的文档”安全校验javascript:scheme 与仿冒域名twitch.google.com、twitch.com.bad、twtich.tv拼写错误不会被输出为可点击/可嵌入的 HTML三类 URL 渲染视频、剪辑、频道分别断言了生成的 iframe 指向player.twitch.tv或clips.twitch.tv/embed且携带parent选项生效allowFullscreen、自定义宽高、muted、视频time1h2m3s均能在输出 HTML 中体现属性覆盖全局autoplay: true 节点autoplay: false时最终输出不含autoplaytruetime同理以节点属性为准如全局1h0m0s被节点2h30m15s覆盖来回往返视频/剪辑/频道三种 URL 经getHTML()后再载回编辑器getJSON()中的src保持原始链接对应 3.23.2 修复的回归测试容错宽高为100%/auto时不会产生NaN属性getParsedDimension兜底为null非法 src 回载不抛错并输出Invalid Twitch URL畸形 embed 标识如videoabc、含非法字符的 clip返回null。版本演进一览结合 CHANGELOG.md 可看到清晰的演进脉络3.0.0MajorTwitch 扩展首次发布3.14.0Minor引入视频、剪辑、直播频道三种嵌入能力支持autoplay、muted、起始时间等可定制参数并支持单节点属性级覆盖commit 5717dcf3.23.2Patch修复 HTML 回载时 Twitch/YouTube 嵌入丢失原始视频/剪辑/频道/播放列表 URL 的问题commit 79fc8b7与getAttributesFromTwitchEmbedUrl反哺解析机制直接相关3.22.4Patch修复包升级后 peer dependency 解析冲突导致的依赖安装问题commit 27ea931其余 Patch均随tiptap/core版本同步升级始终要求与 core 保持同版本避免类型与行为错位。当前仓库内扩展版本为 3.30.3其 peer 依赖为tiptap/core3.30.3安装时请注意保持版本一致。【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考