# @djangocfg/widget-ogimage 中文文档

规范地址：https://npmcn.com/package/%40djangocfg/widget-ogimage/

版本：0\.1\.23
npm 元数据更新时间：2026-11-05T01:09:28.834Z
中文译文更新时间：2026-11-14T16:39:20.077Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/widget-ogimage
原文对照：https://npmcn.com/package/%40djangocfg/widget-ogimage/?lang=original
项目主页：https://djangocfg.com/
源码仓库：https://github.com/markolofsen/django-cfg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：145 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：next \>=15\.0\.0，react ^19\.0\.0
- 首次发布：2026-09-03T06:12:44.825Z
- 最新版本发布：2026-11-05T01:09:28.639Z
- 近 30 天下载量：1976（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

为 Next.js 应用程序打开图形卡:一个Satori 渲染器,销售Plus Jakarta Sans,品牌/内容卡布料每一次开页图像路由调用

## 安装

```sh
npm install @djangocfg/widget-ogimage
```

也可以使用：`pnpm add @djangocfg/widget-ogimage`、`yarn add @djangocfg/widget-ogimage`、`bun add @djangocfg/widget-ogimage`

## README

# 翻译:

为 Next.js 应用程序打开图形卡 。 何等的连结 **变成** 当有人粘贴时 它进入WhatsApp,Telegram,Slack,iMessage或Facebook——常常是唯一的部分 在决定是否打开网页之前.

1个佐藤里出品人, 卖家加雅加达桑斯和2个卡片 "布料"每个 `opengraph-image.tsx` 打电话 品牌身份被约束一次 app,因此本软件包上的两个应用程序从相同的布局中抽取,仍读作 两种产品.

## 快开始

```tsx
// app/_lib/og.tsx — bind the identity once
import { createOgCards, domainFromEnv } from '@djangocfg/widget-ogimage';
import { settings } from '@core/settings';

export const { size, contentType, brandCard, contentCard } = createOgCards({
  name: settings.app.name,
  description: settings.app.description,
  tagline: 'Run on one machine. Coordinate many.',
  domain: domainFromEnv({ fallback: settings.app.siteUrl }),
  siteUrl: settings.app.siteUrl,
  accentColor: '#61B8FF',
  mark: <svg …/>, // inline SVG only — see below
});
```

```tsx
// app/opengraph-image.tsx — the brand card: home, and the fallback everywhere
import { brandCard, contentType, size } from '@lib/og';

export const runtime = 'nodejs';
export const alt = 'CMDOP — run commands across your machines';
export { size, contentType };

export default async function OpengraphImage() {
  return brandCard('Skills & MCP servers', 'Browse, search, and install.');
}
```

```tsx
// app/skills/[slug]/opengraph-image.tsx — one entity
import { contentCard, contentType, size } from '@lib/og';
import { getSkill } from '@lib/api';

export const runtime = 'nodejs';
export { size, contentType };

export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const skill = await getSkill(slug).catch(() => null); // never throw — see rules

  return contentCard({
    title: skill?.seoTitle || skill?.name, // empty → brand card
    eyebrow: 'Skill',
    description: skill?.seoDescription,
    footer: 'Marketplace · Skills',
    image: skill?.cover, // absolute URL, root-relative path, or data URI
  });
}
```

通过将片段附加到任何页面路径来检查本地性 : `/opengraph-image`, (中文(简体) ), `/skills/<slug>/opengraph-image`两者都归还1200×630 PNG.

## 三条

**`runtime = 'nodejs'` 在每一个路线.** 字体解码器使用 `Buffer`,哪个 边缘运行时间不提供.

**别扔了.** 在爬行者等待时,卡片会制作 一条500多条的路 聊天线上赤灰色的矩形——严格说来比通用品牌差 纸牌。 每一次都一样 `.catch(() => null)`,以及 `contentCard` 倒计时 `brandCard` 当标题为空.

**没有 `openGraph.images` 在一张卡片上方.** 下一个文件公约只适用 在没有明确的情况下 `images` 和明确条目 _赢_。 。 。 . 一个 `images` 在布局中阵列不补充其下方的牌, 它 沉默地禁用它们——根版式可以压制应用程序中的每张卡片 一次 一次吗. `withoutOgImages(metadata)` 从生成的元数据中剥离它们.

## API 密码

| 导出 | 作用 |
| --- | --- |
| `createOgCards(config)` | 捆绑身份 – `{ size, contentType, brandCard, contentCard }`建议的切入点. |
| `fitDescription(title, text)` | 将预算描述为标题长度的函数;在单词边界上修剪. |
| `ogFooter(...parts)` | 将事实与 `·`丢掉缺席的. |
| `ogImageUrl(path, siteUrl)` | 绝对 URL 或 `undefined` ——佐藤取出图像本身. |
| `domainFromEnv` • 妇女 `siteUrlFromEnv` • 妇女 `metadataBaseFromEnv` • 妇女 `resolvePublicUrl` | 网站来源 `NEXT_PUBLIC_SITE_URL` 有个应用公司的倒闭. |
| `withoutOgImages(metadata)` | 条纹 `openGraph.images` 编号 : `twitter.images` 所以一个部分的卡适用. |
| `renderOgImage(options, fonts)` • 妇女 `OG_SIZE` • 妇女 `OG_CONTENT_TYPE` • 妇女 `DEFAULT_OG_THEME` | 直接画出一张牌. |
| `loadOgFonts()` | 供应商的打字机,每个流程一次解码. |
| `loadImageDataUri(path, mime)` | 本地文件作为数据 URI(一个带有应用程序的出船相片). |

### `OgCardsConfig`

| 外地 | 页:1 |
| --- | --- |
| `name` | 品牌牌标题; 内容牌上的文字标记 |
| `description?` • 妇女 `tagline?` | 品牌牌描述和页脚 |
| `domain?` | 右下打印 |
| `siteUrl?` | 解决根关系 `image` 路径 |
| `accentColor?` • 妇女 `theme?` | 调色板; `theme.footer` 默认重音 |
| `mark?` | 内置 SVG 。 Satori 无法装入带有 CSS 的 React 图标组件, 以及一个 `<img>` 到远程标志使每张卡都依赖于一个在爬行者等待时可能失败的获取. |
| `loadFonts?` | 交换打字面 |

## 版式

相框为1200×630而佐藤里不剪接:一个标题足够长来包装 推入脚而去取取取出. `titleSizeFor` 步骤标题 通过 84 ~ 66 ~ 52px 的34和58个字符,以及 `fitDescription` 预算 对应这些步骤的描述(150 ~ 92 ~ 0个字符),所以两个字符 移动在一起。 换个,换个.

一张相片上,两道相片将左半边暗出,使拷贝能活下来 无论图像发生什么, 复制栏缩小 停留在 地上被打乱了 这些数字是通过渲染得到的;如果你改变它们, 做一个,看看它.

## 字体

`src/fonts/index.ts` 实值 **生成** ——三个 `.woff` 旁边的文件 真理的来源。 佐藤无法使用 `next/font` (woff2, 返回类) 名称)且不能读取 `.woff` 在生产建筑的路线旁(无) 追踪到输出中, 因此字节被插入到模块中 图. ~64KB 来源,在构建时支付,从未被发送到浏览器.

```bash
pnpm fonts   # node scripts/generate-fonts.mjs
```

加上雅加达桑斯,SIL开放字体许可证1.1.

## 元数据

页次 `Metadata` (标题模板、警语、hreflang、静态品牌图像) `@djangocfg/nextjs/og-image`是因为 `makeMetadataFactory`它没有“放弃” 卡片"故意的大小写:上面的文件常规通过设计凌驾元数据, 因此,支持两者将是两个机制竞相设置同一标记.

## 常见问题

### @djangocfg/widget-ogimage 是什么？

为 Next\.js 应用程序打开图形卡:一个Satori 渲染器,销售Plus Jakarta Sans,品牌/内容卡布料每一次开页图像路由调用

### 如何安装 @djangocfg/widget-ogimage？

在项目目录运行 npm install @djangocfg/widget-ogimage，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=15\.0\.0）、react（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @djangocfg/widget-ogimage 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @djangocfg/widget-ogimage 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @djangocfg/widget-ogimage 可以商用吗？

@djangocfg/widget-ogimage 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @djangocfg/widget-ogimage 的下载量有多少？

根据 npm 官方下载统计，@djangocfg/widget-ogimage 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,976 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @djangocfg/widget-ogimage 还在维护吗？

最新版本 0\.1\.23 发布于 2026/11/05（9 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/09/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。