YouTube 嵌入
在文档中嵌入 YouTube 视频和 Shorts。支持延迟加载播放器、自定义起始时间以及竖屏 9:16 Shorts。
<YouTube> 组件可嵌入视频，支持延迟加载、圆角显示，并且不会显示相关视频等多余内容。页面加载时，它会显示缩略图和播放按钮，点击后才会加载完整的 YouTube 播放器。
嵌入 YouTube 视频
将视频 ID 作为 id 属性传入：
<YouTube id="dQw4w9WgXcQ" />在观众点击播放之前，不会加载任何 iframe。该组件使用 lite-youtube-embed：只需一张缩略图和几 KB 的 CSS，而不是 800KB 以上的 YouTube iframe 资源包。
Props
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
id | string | 无 | 必填。 YouTube 视频 ID。 |
title | string | "Play" / "YouTube Short" | 嵌入内容的无障碍标签。屏幕阅读器会朗读此文本。 |
start | number | 0 | 从视频的第几秒开始播放。 |
short | boolean | false | 以竖屏 9:16 的 YouTube Shorts 形式渲染，而不是 16:9 的普通视频。 |
从指定时间开始播放
start 属性可在播放开始时跳转到指定时间点（以秒为单位）：
<YouTube id="dQw4w9WgXcQ" start={60} />播放将从第 1 分钟处开始。小数值会向下取整为整秒。
查找视频 ID
视频 ID 是 YouTube URL 中 v= 之后的字符串。
youtube.com/watch?v=dQw4w9WgXcQ→ ID 为dQw4w9WgXcQyoutu.be/dQw4w9WgXcQ→ ID 为dQw4w9WgXcQ
请复制 ID，而不是完整的 URL。
YouTube Shorts
YouTube Shorts 是宽高比为 9:16 的竖屏视频。如果将 Short 嵌入标准的 16:9 播放器，两侧会出现较宽的黑边。
short 属性可以解决这个问题。它会以 9:16 的比例渲染嵌入内容，在页面中居中显示，宽度为 360px，并带有圆角。效果与 Shorts 在移动端的显示方式一致。
如何嵌入 Short
<YouTube id="_6HzLIJPH2A" short />查找 Short ID
Short ID 是 URL 中 /shorts/ 之后的路径片段：
youtube.com/shorts/_6HzLIJPH2A→ ID 为_6HzLIJPH2A
这些 ID 与普通 YouTube 视频一样，为 11 个字符的格式。如果不使用 short，<YouTube> 组件会以 16:9 渲染 Short，并显示黑边。
渲染详情
| 细节 | 渲染方式 |
|---|---|
| 宽度 | 最大为 360px，并居中显示（与 YouTube 自身移动端 Shorts 播放器的宽度一致） |
| 宽高比 | 通过 CSS aspect-ratio 设置为 9:16，因此容器可在较小屏幕上平滑缩放 |
| 圆角 | 使用 border-radius 设置圆角，与 Jamdesk 其他媒体嵌入保持一致 |
| 相关视频 | 通过 rel=0 禁用，与标准嵌入相同 |
性能差异
标准 YouTube 嵌入使用 lite-youtube-embed。它不会预先加载任何 YouTube JavaScript，页面只显示缩略图。只有在观众点击播放时，才会加载完整的播放器 iframe。
lite-youtube-embed 无法渲染竖屏宽高比，因此 Shorts 改用带有 loading="lazy" 的直接 <iframe>。浏览器会延迟加载，直到 iframe 滚动到视口附近。当 iframe 可见时，完整的 YouTube 播放器（包括脚本、样式等全部内容）才会初始化。
一个或两个 Shorts 对页面的影响微乎其微。但如果页面中包含大量 Shorts，额外的 iframe 会增加页面负担。当页面中的 Shorts 超过三四个时，可以改为链接到它们，或放在标签页后面。这样可以保持初始加载的轻量化。
直接使用 iFrame
如需完全控制嵌入参数，可以使用原始 iframe：
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/><YouTube> 组件是更好的默认选择。它会延迟加载播放器、去除相关视频，并以 9:16 渲染 Shorts。只有当你需要组件未提供的嵌入参数时，才使用原始 iframe。