image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@json-render/image

Image renderer that converts JSON specs into SVG and PNG images using Satori.

使用Satori将JSON规范转换为SVG和PNG图像的图像渲染器。

Quick Start

快速开始

typescript

import { renderToPng } from "@json-render/image/render";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "frame",
  elements: {
    frame: {
      type: "Frame",
      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
      children: ["heading"],
    },
    heading: {
      type: "Heading",
      props: { text: "Hello World", level: "h1", color: "#ffffff" },
      children: [],
    },
  },
};

const png = await renderToPng(spec, {
  fonts: [{ name: "Inter", data: fontData, weight: 400, style: "normal" }],
});

typescript

import { renderToPng } from "@json-render/image/render";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "frame",
  elements: {
    frame: {
      type: "Frame",
      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
      children: ["heading"],
    },
    heading: {
      type: "Heading",
      props: { text: "Hello World", level: "h1", color: "#ffffff" },
      children: [],
    },
  },
};

const png = await renderToPng(spec, {
  fonts: [{ name: "Inter", data: fontData, weight: 400, style: "normal" }],
});

Using Standard Components

使用标准组件

typescript

import { defineCatalog } from "@json-render/core";
import { schema, standardComponentDefinitions } from "@json-render/image";

export const imageCatalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
});

typescript

import { defineCatalog } from "@json-render/core";
import { schema, standardComponentDefinitions } from "@json-render/image";

export const imageCatalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
});

Adding Custom Components

添加自定义组件

typescript

import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({ label: z.string(), color: z.string().nullable() }),
      slots: [],
      description: "A colored badge label",
    },
  },
});

typescript

import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({ label: z.string(), color: z.string().nullable() }),
      slots: [],
      description: "A colored badge label",
    },
  },
});

Standard Components

标准组件

Component	Category	Description
`Frame`	Root	Root container. Defines width, height, background. Must be root.
`Box`	Layout	Container with padding, margin, border, absolute positioning
`Row`	Layout	Horizontal flex layout
`Column`	Layout	Vertical flex layout
`Heading`	Content	h1-h4 heading text
`Text`	Content	Body text with full styling
`Image`	Content	Image from URL
`Divider`	Decorative	Horizontal line separator
`Spacer`	Decorative	Empty vertical space

组件	分类	描述
`Frame`	根容器	根容器，定义宽度、高度、背景，必须作为根元素
`Box`	布局	支持内边距、外边距、边框、绝对定位的容器
`Row`	布局	水平弹性布局
`Column`	布局	垂直弹性布局
`Heading`	内容	h1-h4级标题文本
`Text`	内容	支持完整样式的正文文本
`Image`	内容	来自URL的图像
`Divider`	装饰元素	水平分割线
`Spacer`	装饰元素	空白垂直占位空间

Key Exports

核心导出

Export	Purpose
`renderToSvg`	Render spec to SVG string
`renderToPng`	Render spec to PNG buffer (requires `@resvg/resvg-js` )
`schema`	Image element schema
`standardComponents`	Pre-built component registry
`standardComponentDefinitions`	Catalog definitions for AI prompts

导出项	用途
`renderToSvg`	将规范渲染为SVG字符串
`renderToPng`	将规范渲染为PNG缓冲区（依赖 `@resvg/resvg-js` ）
`schema`	图像元素Schema
`standardComponents`	预构建的组件注册中心
`standardComponentDefinitions`	适用于AI提示词的目录定义

Sub-path Exports

子路径导出

Export	Description
`@json-render/image`	Full package: schema, components, render functions
`@json-render/image/server`	Schema and catalog definitions only (no React/Satori)
`@json-render/image/catalog`	Standard component definitions and types
`@json-render/image/render`	Render functions only

导出路径	描述
`@json-render/image`	完整包：包含schema、组件、渲染函数
`@json-render/image/server`	仅包含schema和目录定义（无React/Satori依赖）
`@json-render/image/catalog`	标准组件定义和类型
`@json-render/image/render`	仅包含渲染函数