---
title: 图像
description: >-
了解 Jamdesk 如何处理图像尺寸、说明文字、明暗主题变体和支持的格式，让文档视觉内容清晰易读。
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
Jamdesk 会为图像添加圆角并保持统一间距。将文件放入 `/images` 目录，然后使用标准 Markdown 引用。
屏幕截图显示的是英文界面。
## 标准 Markdown
使用熟悉的 `` 语法：
```markdown
```
路径从项目根目录开始。例如，位于 `your-docs/images/screenshot.webp` 的图像应引用为 `/images/screenshot.webp`。
## 图像尺寸
在图像 URL 后追加 `=WIDTHxHEIGHT`（中间用空格分隔）即可控制尺寸：
```markdown
```
只设置一个尺寸，另一个尺寸会按比例缩放：
```markdown
```
如果你希望同一列中的屏幕截图具有一致宽度，或需要将高分辨率图像缩小到合理的显示尺寸，这种方式会很有用。
## 说明文字
将图像包裹在 `` 组件中，即可为其添加边框和底部说明文字：
```mdx
```
`Frame` 会在图像周围绘制细边框，并将说明文字放在下方。它不仅适用于图像，也适用于其中的任何内容。
## 明暗主题
文档网站通常需要为每种配色方案使用不同的图像变体：白色背景上的徽标在深色模式下看起来不协调。
### `srcDark` 属性
最简单的方法。Jamdesk 会根据当前主题切换图像源：
```mdx
```
浏览器只会加载与当前配色方案匹配的图像。
### HTML `` 元素
如果你需要在 Jamdesk 之外也能使用的标准 HTML，可以结合媒体查询使用 ``：
```mdx
```
`` 方式会遵循操作系统的配色方案设置。`srcDark` 属性则响应 Jamdesk 的主题切换按钮，这通常更适合文档网站。
## 支持的格式
| 格式 | 适用场景 | 备注 |
|--------|----------|-------|
| PNG | 屏幕截图、UI 捕获 | 无损质量，支持透明度。文件较大。 |
| JPEG | 照片 | 压缩效果好，不支持透明度。 |
| SVG | 图标、图表、徽标 | 矢量格式，可缩放到任意尺寸且不会损失质量。文件极小。 |
| GIF | 简单动画 | 文件可能迅速变大。超过几帧时，可考虑使用较短的 `.mp4` 循环。 |
| WebP | 通用场景 | 在相近质量下比 PNG 和 JPEG 更小。所有现代浏览器均支持。 |
对于大多数文档图像，WebP 能提供最佳的大小与质量平衡。如果需要透明度，WebP 同样支持，因此无需使用 PNG。
## 最佳实践
替代文本有两个作用：屏幕阅读器使用它来提供无障碍支持，图像加载失败时它会作为占位文本显示。请描述图像实际展示的内容。
```markdown
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
```
对于不包含额外信息的装饰性图像（背景图案、分隔线），请使用空替代文本：``。
较大的图像会拖慢页面加载速度，尤其是在移动网络连接下。建议使用以下大小：
- **屏幕截图/UI：** PNG 或 WebP，小于 500KB
- **照片：** JPEG 或 WebP，小于 200KB
- **图标和图表：** 尽可能使用 SVG
[Squoosh](https://squoosh.app) 和 [TinyPNG](https://tinypng.com) 可以在不造成明显质量损失的情况下压缩图像。提交前，请使用其中一个工具处理屏幕截图。
也可以让 Jamdesk 在构建时处理图像。在 `docs.json` 中启用[自动 WebP 转换](/cn/builds/image-optimization)，这样你提交的任何 PNG 或 JPG 都会在每次构建时得到优化。
宽度不断变化的屏幕截图看起来会比较杂乱。请选择一个标准捕获宽度（1200px 效果良好），并在整个文档中使用该宽度。Jamdesk 会自动缩放图像以适应内容区域，因此统一的源尺寸会带来一致的渲染效果。
Jamdesk 会为每个页面自动生成带品牌标识的 1200×630 社交卡片，你也可以在 frontmatter 中使用 `og:image` 为单个页面覆盖该设置。构建后，将页面 URL 输入免费的 [OpenGraph Preview](https://jamdesk.com/utilities/opengraph-preview) 工具，即可查看卡片在 X、Facebook、LinkedIn、Slack、Discord 等平台上的呈现效果。完整设置请参阅 [SEO 优化](/cn/content/seo)。
## 文件组织
将图像分组到与内容结构对应的子目录中。这样，随着文档不断增长，文件仍然易于查找：
```bash
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
```
使用从项目根目录开始的完整路径引用它们：
```markdown
```
避免在图像文件名中使用空格。请改用连字符：`api-response.webp`，而不是 `api response.webp`。
## 接下来做什么？
嵌入 YouTube 视频和 Shorts
本地 MP4 和 WebM 文件
Vimeo、CodePen、Figma 等
