html2figma v1.0.3

JSON 与公共类型

了解文档结构、校验方法与公共类型入口。

校验输入 JSON

TYPESCRIPT

import { parseDocumentJson, isHtml2FigmaDocument } from 'html2figma';

const json = '{ /* converted document */ }';
const documentAst = parseDocumentJson(json);
const unknownValue: unknown = documentAst;
if (isHtml2FigmaDocument(unknownValue)) console.log(unknownValue.root);

parseDocumentJson(value: string): Html2FigmaDocument 解析并校验 JSON 字符串。语法无效时抛出 JSON could not be parsed.，结构无效时抛出 JSON is not a valid html2figma document.。用真实 JSON 替换占位内容。

isHtml2FigmaDocument(value: unknown): value is Html2FigmaDocument 校验已解析值，对于普通的无效 JSON 数据返回 false。

校验覆盖字段类型、有限数值、数值范围、节点与资源 ID 唯一性，以及资源引用类型。它不会加载图片、检查已安装字体或证明视觉还原度。应用应自行限制输入大小。

文档结构

字段	含义
`version`	AST 格式版本，目前为字面量 `1`，与库版本 `1.0.3` 不同。
`root`	根 `Html2FigmaNode`。
`resources`	图片或 SVG 资源。
`warnings`	汇总的转换诊断。
`metadata`	可选来源 URL、视口尺寸和创建时间。

节点类型

Html2FigmaNode 为 frame、rectangle、text、image、svg 的可辨识联合类型。每个节点包含 ID、名称、测量尺寸、样式、来源、警告和子节点。文本节点增加 text，图片与 SVG 增加 resourceId，图片还可携带 alt。

AstBounds 包含 x、y、width、height。AstStyle 包含可选的透明度、填充、描边、圆角、阴影、排版和支持的 Flex 布局信息。这些字段描述受支持的输出，不是完整 CSS 模型。

根入口类型

类型	用途
`Html2FigmaDocument`、`Html2FigmaNode`	文档与节点联合类型。
`AstBounds`、`AstStyle`	几何信息与样式。
`ConvertOptions`	浏览器遍历选项。
`ConvertWarning`、`RenderWarning`	诊断信息，渲染警告沿用转换警告结构。
`ResourceRef`	ID、图片/SVG 类型、来源，以及可选数据与 MIME 类型。
`RenderOptions<Parent>`、`RenderResult<Node>`	可移植渲染泛型。

安装包中的 TypeScript 声明提供完整嵌套字段与字面量联合类型，可通过 IDE 查看。使用公共入口，不要直接导入私有 dist 文件。

资源可移植性

只有引用资源也可访问时，JSON 才能完整传递。Playground 图片可使用公开 URL 和 data URL，Gallery 案例已内嵌图片。字体文件和浏览器登录态不会写入 JSON。

TYPESCRIPT

type NodeId = string;
interface AstBounds {
    x: number;
    y: number;
    width: number;
    height: number;
}
interface Rgb {
    r: number;
    g: number;
    b: number;
}
interface SolidFill {
    type: "solid";
    color: Rgb;
    opacity: number;
}
interface ImageFill {
    type: "image";
    resourceId: string;
    opacity: number;
    scaleMode: "fill" | "fit" | "crop" | "tile";
}
type AstFill = SolidFill | ImageFill;
interface AstStroke {
    color: Rgb;
    opacity: number;
    weight: number;
    align: "inside" | "center" | "outside";
}
interface AstShadow {
    type: "drop-shadow";
    color: Rgb;
    opacity: number;
    offsetX: number;
    offsetY: number;
    blur: number;
    spread: number;
}
interface AstTextStyle {
    fontFamily: string;
    fontSize: number;
    fontWeight: number;
    fontStyle?: "normal" | "italic";
    lineHeight?: number;
    letterSpacing?: number;
    textAlign?: "left" | "center" | "right" | "justified";
    textDecoration?: "none" | "underline" | "strikethrough";
    textCase?: "upper" | "lower" | "title";
    color?: Rgb;
}
interface AstFlexLayout {
    mode: "horizontal" | "vertical";
    gap: number;
    /** Content insets from the frame edge, including CSS border widths. */
    padding: {
        top: number;
        right: number;
        bottom: number;
        left: number;
    };
    primaryAxisAlignItems: "min" | "center" | "max" | "space-between";
    counterAxisAlignItems: "min" | "center" | "max";
    wraps: boolean;
}
interface AstStyle {
    opacity?: number;
    fills?: AstFill[];
    strokes?: AstStroke[];
    cornerRadius?: {
        topLeft: number;
        topRight: number;
        bottomRight: number;
        bottomLeft: number;
    };
    effects?: AstShadow[];
    text?: AstTextStyle;
    layout?: AstFlexLayout;
}
type WarningSeverity = "info" | "warning" | "error";
interface ConvertWarning {
    code: string;
    message: string;
    severity: WarningSeverity;
    nodeId?: NodeId;
    cssProperty?: string;
    source?: string;
}
type RenderWarning = ConvertWarning;
interface ResourceRef {
    id: string;
    type: "image" | "svg";
    source: string;
    data?: string;
    mimeType?: string;
}
interface AstSource {
    tagName: string;
    path: string;
}
interface BaseAstNode {
    id: NodeId;
    name: string;
    bounds: AstBounds;
    style: AstStyle;
    source: AstSource;
    warnings: ConvertWarning[];
    children: Html2FigmaNode[];
}
interface FrameAstNode extends BaseAstNode {
    type: "frame";
}
interface TextAstNode extends BaseAstNode {
    type: "text";
    text: string;
}
interface RectangleAstNode extends BaseAstNode {
    type: "rectangle";
}
interface ImageAstNode extends BaseAstNode {
    type: "image";
    resourceId: string;
    alt?: string;
}
interface SvgAstNode extends BaseAstNode {
    type: "svg";
    resourceId: string;
}
type Html2FigmaNode = FrameAstNode | TextAstNode | RectangleAstNode | ImageAstNode | SvgAstNode;
interface Html2FigmaDocument {
    version: 1;
    root: Html2FigmaNode;
    resources: ResourceRef[];
    /** Aggregate of node diagnostics; node.warnings retains the local view. */
    warnings: ConvertWarning[];
    metadata: {
        sourceUrl?: string;
        viewport: {
            width: number;
            height: number;
        };
        createdAt: string;
    };
}
interface ConvertOptions {
    includeHidden?: boolean;
    maxDepth?: number;
}
/** Platform-neutral options; use html2figma/render for Figma-specialized types. */
interface RenderOptions<Parent = unknown> {
    parent?: Parent;
    x?: number;
    y?: number;
    loadFonts?: boolean;
}
interface RenderResult<Node = unknown> {
    root: Node;
    nodes: Node[];
    warnings: RenderWarning[];
}

export type { AstBounds as A, ConvertOptions as C, Html2FigmaDocument as H, RenderOptions as R, AstStyle as a, ConvertWarning as b, Html2FigmaNode as c, RenderResult as d, RenderWarning as e, ResourceRef as f };

在 Playground 中体验 ↗反馈文档问题 ↗