mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
5a3d1ddabb
* docs: sync es/fr/zh translations with recent English updates * docs: tighten descriptions and replace HTML entities with real quotes --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
231 lines
6.0 KiB
Plaintext
231 lines
6.0 KiB
Plaintext
---
|
||
title: "图片与嵌入"
|
||
description: "在 MDX 页面中添加图片、嵌入 YouTube 视频和 iframe，以视觉和互动内容丰富文档。"
|
||
keywords: ["images", "videos", "iframes", "media", "svg"]
|
||
---
|
||
|
||
在文档中添加图片、嵌入视频，并通过 iframes 引入交互式内容。
|
||
|
||
<Frame>
|
||
<img className="rounded-xl" src="https://mintlify-assets.b-cdn.net/bigbend.jpg" alt="一张风景照片：前景为紫色花朵，远处是群山，天空湛蓝，点缀着零散白云。" />
|
||
</Frame>
|
||
|
||
<div id="images">
|
||
## 图像
|
||
</div>
|
||
|
||
在文档中添加图像，以提供可视化的 context、示例或装饰。
|
||
|
||
<div id="basic-image-syntax">
|
||
### 基本图像语法
|
||
</div>
|
||
|
||
使用 [Markdown 语法](https://www.markdownguide.org/basic-syntax/#images)向文档中添加图像：
|
||
|
||
```mdx
|
||
|
||
```
|
||
|
||
图像路径相对于文档仓库的根目录。例如，如果你的图像位于仓库中的 `images/screenshot.png`，则路径为 `/images/screenshot.png`。不支持相对路径（例如 `./screenshot.png`）。
|
||
|
||
<Tip>
|
||
请务必包含具有描述性的 alt 文本，以提升可访问性和 SEO（搜索引擎优化）。alt 文本应清晰说明图像所呈现的内容。
|
||
</Tip>
|
||
|
||
图像文件必须小于 20 MB。对于更大的文件，请将其托管在 [Amazon S3](https://aws.amazon.com/s3) 或 [Cloudinary](https://cloudinary.com) 等 CDN 服务上。
|
||
|
||
<div id="html-image-embeds">
|
||
### HTML 图像嵌入
|
||
</div>
|
||
|
||
若需更精准地控制图像显示，请使用 HTML 的 `<img>` 标签：
|
||
|
||
```jsx
|
||
<img
|
||
src="/images/dashboard.png"
|
||
alt="主控制台界面"
|
||
style={{height: "300px", width: "400px"}}
|
||
className="rounded-lg"
|
||
/>
|
||
```
|
||
|
||
<div id="resize-images-with-inline-styles">
|
||
#### 使用内联样式调整图片尺寸
|
||
</div>
|
||
|
||
使用 `style` 属性在 JSX 中编写内联样式来调整图片尺寸：
|
||
|
||
```jsx
|
||
<img
|
||
src="/images/architecture.png"
|
||
style={{width: "450px", height: "auto"}}
|
||
alt="系统架构图"
|
||
/>
|
||
```
|
||
|
||
<div id="disable-image-zoom">
|
||
#### 禁用图片缩放
|
||
</div>
|
||
|
||
要禁用图片点击时的默认缩放，请添加 `noZoom` 属性：
|
||
|
||
```html highlight="4"
|
||
<img
|
||
src="/images/screenshot.png"
|
||
alt="描述性替代文本"
|
||
noZoom
|
||
/>
|
||
```
|
||
|
||
|
||
<div id="link-images">
|
||
#### 链接图片
|
||
</div>
|
||
|
||
要让图片可点击并指向链接，请将图片包裹在 a（锚点）标签中，并添加 `noZoom` 属性：
|
||
|
||
```html
|
||
<a href="https://mintlify.com" target="_blank">
|
||
<img
|
||
src="/images/logo.png"
|
||
alt="Mintlify 徽标"
|
||
noZoom
|
||
/>
|
||
</a>
|
||
```
|
||
|
||
<Note>
|
||
位于锚点标签内的图像会自动显示指针光标，表示它们可点击。
|
||
</Note>
|
||
|
||
<div id="light-and-dark-mode-images">
|
||
#### 明暗模式的图像
|
||
</div>
|
||
|
||
要在浅色和深色主题下显示不同的图像，请使用 Tailwind CSS 类：
|
||
|
||
```html
|
||
<!-- 浅色模式图片 -->
|
||
<img
|
||
className="block dark:hidden"
|
||
src="/images/light-mode.png"
|
||
alt="浅色模式界面"
|
||
/>
|
||
|
||
<!-- 深色模式图片 -->
|
||
<img
|
||
className="hidden dark:block"
|
||
src="/images/dark-mode.png"
|
||
alt="深色模式界面"
|
||
/>
|
||
```
|
||
|
||
<div id="svg-images">
|
||
### SVG 图像
|
||
</div>
|
||
|
||
在包含 `foreignObject` 元素的 SVG 文件中，生产环境下的渲染效果会和本地开发环境不同。出于安全考虑，Mintlify 的图像 CDN 会从 SVG 中移除 `foreignObject`，这可能会截断或隐藏文本以及其他嵌入的 HTML 内容。
|
||
|
||
这通常会影响从诸如 [draw.io](https://www.drawio.com) 等工具导出的 SVG，尤其是在启用了 HTML 文本格式或自动换行时。要解决这个问题，请在导出 SVG 之前，关闭图中所有标签的 **Formatted Text** 和 **Word Wrap** 选项。更多有关 SVG 导出的信息，请参阅 [draw.io 文档](https://www.drawio.com/doc/faq/svg-export-text-problems)。
|
||
|
||
<div id="videos">
|
||
## 视频
|
||
</div>
|
||
|
||
Mintlify 支持在 Markdown 中使用 [HTML 标签](https://www.markdownguide.org/basic-syntax/#html)，让你能更灵活地创建丰富内容。
|
||
|
||
<Tip>
|
||
请务必在 video 元素内提供备用文本内容，以便在不支持视频播放的浏览器中显示。
|
||
</Tip>
|
||
|
||
<div id="youtube-embeds">
|
||
### 嵌入 YouTube 视频
|
||
</div>
|
||
|
||
使用 iframe 元素嵌入 YouTube 视频：
|
||
|
||
```html
|
||
<iframe
|
||
className="w-full aspect-video rounded-xl"
|
||
src="https://www.youtube.com/embed/4KzFe50RQkQ"
|
||
title="YouTube 视频播放器"
|
||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||
allowFullScreen
|
||
></iframe>
|
||
```
|
||
|
||
<Frame>
|
||
<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/4KzFe50RQkQ" title="YouTube 视频播放器" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
|
||
</Frame>
|
||
|
||
|
||
<div id="self-hosted-videos">
|
||
### 自托管视频
|
||
</div>
|
||
|
||
对于自托管视频对象，请使用 HTML `<video>` 元素：
|
||
|
||
```html
|
||
<video
|
||
controls
|
||
className="w-full aspect-video rounded-xl"
|
||
src="您的视频链接.com"
|
||
></video>
|
||
```
|
||
|
||
<div id="autoplay-videos">
|
||
### 自动播放视频
|
||
</div>
|
||
|
||
要让视频自动播放，请使用：
|
||
|
||
```html
|
||
<video
|
||
autoPlay
|
||
muted
|
||
loop
|
||
playsInline
|
||
className="w-full aspect-video rounded-xl"
|
||
src="/videos/demo.mp4"
|
||
></video>
|
||
```
|
||
|
||
<Note>
|
||
使用 JSX 语法时，将由两个单词组成的属性写成驼峰命名（camelCase）：`autoPlay`、`playsInline`、`allowFullScreen`。
|
||
</Note>
|
||
|
||
<div id="iframes">
|
||
## Iframe
|
||
</div>
|
||
|
||
使用 iframe 元素嵌入外部内容：
|
||
|
||
```html
|
||
<iframe
|
||
src="https://example.com/embed"
|
||
title="嵌入式内容"
|
||
className="w-full h-96 rounded-xl"
|
||
></iframe>
|
||
```
|
||
|
||
<Tip>
|
||
将 iframe 包裹在 [frame](/zh/components/frames) 组件中，可使其保持在文本列宽内并避免溢出。
|
||
|
||
```html
|
||
<Frame>
|
||
<iframe
|
||
src="https://example.com/embed"
|
||
title="嵌入式内容"
|
||
className="w-full h-96 rounded-xl"
|
||
></iframe>
|
||
</Frame>
|
||
```
|
||
</Tip>
|
||
|
||
<div id="related-resources">
|
||
## 相关资源
|
||
</div>
|
||
|
||
<Card title="Frame 组件参考" icon="frame" horizontal href="/zh/components/frames">
|
||
了解如何使用 Frame 组件来呈现图像。
|
||
</Card> |