Text

创建和管理文本节点。

Type reference

// depth: omit → id+name stubs | 0 → props + child stubs | N → recurse N | -1 → full tree
// fields: whitelist e.g. ["fills","opacity"] — id, name, type always included. Pass ["*"] for all.
// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL — how the node sizes within auto-layout.
// Colors: fillVariableName/strokeVariableName bind by name — preferred over raw color values.
// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.
//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).
// ---
// visible: false hides the node. Omitted from response when true (the default).
// locked: true prevents editing in Figma UI. Omitted when false (the default).
// rotation: degrees (0-360). Omitted when 0.
// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).
// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).
// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.
// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.
// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".
// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.
// properties: escape hatch — set any Figma node property directly. Use only when no dedicated field exists.
interface Node {
  id: string; name: string; type: string;
  visible?: boolean;       // omitted when true
  locked?: boolean;        // omitted when false
  opacity?: number;        // omitted when 1
  rotation?: number;       // omitted when 0
  blendMode?: string;      // omitted when PASS_THROUGH
  layoutPositioning?: "AUTO" | "ABSOLUTE";
  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";
  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";
  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;
  absoluteBoundingBox: { x: number; y: number; width: number; height: number };
  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}
  strokes?: Paint[];
  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR
  children?: NodeStub[];   // stubs: {id, name, type} — use depth to expand
}
// PatchItem uses flat params matching create shape — no nested sub-objects.
// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.
// Unknown keys produce a warning, preventing silent failures.
// Text nodes display text content with typography styling. They inherit node methods (get, list, update, delete, clone, reparent).
// textAutoResize: NONE (fixed box), WIDTH_AND_HEIGHT (grow both), HEIGHT (fixed width, auto height), TRUNCATE (fixed + ellipsis).
// Prefer textStyleName for typography, fontColorVariableName/fontColorStyleName for color.
// Aliases: fillColor → fontColor, fillVariableName → fontColorVariableName, fillStyleName → fontColorStyleName (consistent with frames API).
// ---
// Smart defaults inside auto-layout parent: layoutSizingHorizontal defaults to FILL, layoutSizingVertical to HUG, textAutoResize to HEIGHT.
//   Text fills parent width and wraps automatically. Override with explicit values if needed.
// fontStyle vs fontWeight: fontStyle is a named variant like "Bold", "Italic", "SemiBold". When set, fontWeight is ignored.
//   Use fonts.list to find available fontFamily + fontStyle combinations.
// scan: finds all text nodes in a subtree. path (when includePath:true) shows the layer hierarchy e.g. "Frame > Card > Label".
// ScanResult (per-item): { nodeId, count, truncated, textNodes: [{ id, name, characters, fontSize, fontFamily, fontStyle, path?, depth?, absoluteX?, absoluteY?, width?, height? }] }

10 methods available.

get

readinherited

Get serialized node data

Parameter	Type	Required	Description
id	string	✓	Node ID
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.
verbose	boolean	✗	Include all properties (bounding box, constraints, text style details). Default false — returns slim, actionable output.

Response

Serialized node tree. Shape depends on depth parameter.

Field	Type	Description
results	object[]	Serialized node trees
_truncated	boolean	True when node budget exceeded
_notice	string	Human-readable truncation notice

list

readinherited

Search for nodes (returns stubs only — use get with depth for full properties)

Parameter	Type	Required	Description
query	string	✗	Name search query (case-insensitive substring match)
types	string[]	✗	Filter by node types (e.g. ["FRAME", "TEXT"])
parentId	string	✗	Search only within this subtree
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
offset	number	✗	Skip N items for pagination (default 0) (default: 0)
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Paginated node search results (uses results not items)

Field	Type	Description
totalCount	number	Total matching nodes
returned	number	Nodes in this page
offset	number
limit	number
results	object[]	Matching node stubs
↳ id	string
↳ name	string
↳ type	string
↳ parentId	string
↳ parentName	string
↳ bounds	object
↳ x	number
↳ y	number
↳ width	number
↳ height	number

update

editinherited

Patch node properties

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, ...properties} to patch
↳ fills	array	✗	Fill paints array — e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
↳ fillColor	string	✗	Shorthand — sets a single solid fill (auto-binds to matching variable/style)
↳ fillStyleName	string	✗	Paint style name for fill
↳ fillVariableName	string	✗	Color variable by name e.g. 'bg/primary'
↳ strokes	array	✗	Stroke paints array — e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
↳ strokeColor	string	✗	Shorthand — sets a single solid stroke (auto-binds to matching variable/style)
↳ strokeStyleName	string	✗	Paint style name for stroke
↳ strokeVariableName	string	✗	Color variable by name for stroke
↳ strokeWeight	token	✗	All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
↳ strokeTopWeight	token	✗
↳ strokeBottomWeight	token	✗
↳ strokeLeftWeight	token	✗
↳ strokeRightWeight	token	✗
↳ strokeAlign	"INSIDE" | "OUTSIDE" | "CENTER"	✗	Stroke position (default: INSIDE)
↳ cornerRadius	token	✗	All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
↳ topLeftRadius	token	✗
↳ topRightRadius	token	✗
↳ bottomRightRadius	token	✗
↳ bottomLeftRadius	token	✗
↳ visible	boolean	✗	Show/hide (default true)
↳ locked	boolean	✗	Lock/unlock (default false)
↳ opacity	token	✗	Opacity (0-1) or variable name
↳ blendMode	"PASS_THROUGH" | "NORMAL" | "DARKEN" | "MULTIPLY" | "LINEAR_BURN" | "COLOR_BURN" | "LIGHTEN" | "SCREEN" | "LINEAR_DODGE" | "COLOR_DODGE" | "OVERLAY" | "SOFT_LIGHT" | "HARD_LIGHT" | "DIFFERENCE" | "EXCLUSION" | "HUE" | "SATURATION" | "COLOR" | "LUMINOSITY"	✗
↳ effectStyleName	string	✗	Effect style name (e.g. 'Shadow/Card') for shadows, blurs
↳ layoutMode	"NONE" | "HORIZONTAL" | "VERTICAL"	✗	Layout direction (default: NONE)
↳ layoutWrap	"NO_WRAP" | "WRAP"	✗	Wrap children to new rows (HORIZONTAL layout only — Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
↳ padding	token	✗	All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
↳ paddingTop	token	✗
↳ paddingRight	token	✗
↳ paddingBottom	token	✗
↳ paddingLeft	token	✗
↳ primaryAxisAlignItems	"MIN" | "MAX" | "CENTER" | "SPACE_BETWEEN"	✗
↳ counterAxisAlignItems	"MIN" | "MAX" | "CENTER" | "BASELINE"	✗
↳ itemSpacing	token	✗	Spacing between children (number or variable name string, default: 0)
↳ counterAxisSpacing	token	✗	Gap between wrapped rows (requires layoutWrap: WRAP)
↳ strokesIncludedInLayout	boolean	✗	Include stroke width in layout measurements (default: false)
↳ layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
↳ layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
↳ layoutPositioning	"AUTO" | "ABSOLUTE"	✗	ABSOLUTE = floating inside auto-layout parent
↳ minWidth	number	✗	Min width for responsive auto-layout
↳ maxWidth	number	✗	Max width for responsive auto-layout
↳ minHeight	number	✗	Min height for responsive auto-layout
↳ maxHeight	number	✗	Max height for responsive auto-layout
↳ fontSize	number	✗	Font size
↳ fontFamily	string	✗	Font family
↳ fontStyle	string	✗	Font variant e.g. "Bold", "Italic" — overrides fontWeight
↳ fontWeight	number	✗	100-900. Ignored when fontStyle is set.
↳ lineHeight	any	✗	number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}
↳ letterSpacing	any	✗	number | {value, unit: "PIXELS"|"PERCENT"}
↳ textCase	"ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED"	✗
↳ textDecoration	"NONE" | "UNDERLINE" | "STRIKETHROUGH"	✗
↳ fontColor	string	✗	Shorthand — sets text color (auto-binds to matching variable/style)
↳ fontColorVariableName	string	✗	Bind color variable by name e.g. 'text/primary'
↳ fontColorStyleName	string	✗	Apply paint style — overrides fontColor
↳ textStyleId	string	✗	Apply text style by ID — overrides fontSize/fontWeight
↳ textStyleName	string	✗	Text style by name (case-insensitive)
↳ textAlignHorizontal	"LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED"	✗
↳ textAlignVertical	"TOP" | "CENTER" | "BOTTOM"	✗
↳ textAutoResize	"NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT" | "TRUNCATE"	✗
↳ id	string	✓
↳ name	string	✗	Rename node
↳ rotation	number	✗	Degrees (0-360)
↳ x	number	✗
↳ y	number	✗
↳ width	number	✗
↳ height	number	✗
↳ clearFill	boolean	✗	Remove all fills
↳ imageUrl	string	✗	Image source — 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
↳ imageScaleMode	"FILL" | "FIT" | "CROP" | "TILE"	✗	How the image is scaled within the frame (default: FILL)
↳ effects	object[]	✗	Effect array (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR)
↳ overflowDirection	"NONE" | "HORIZONTAL" | "VERTICAL" | "BOTH"	✗	Scroll overflow in prototype (default: NONE)
↳ constraints	object	✗
↳ horizontal	"MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE"	✗
↳ vertical	"MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE"	✗
↳ bindings	object[]	✗	Bind variables to properties. field path examples: 'fills/0/color', 'strokes/0/color', 'opacity', 'width', 'cornerRadius', 'itemSpacing'.
↳ field	string	✓
↳ variableName	string	✗
↳ variableId	string	✗
↳ explicitMode	object	✗	Pin variable mode — use { collectionName, modeName } (preferred) or { collectionId, modeId }
↳ exportSettings	object[]	✗	Export settings
↳ annotations	object[]	✗	Set annotations — [{label?, labelMarkdown?, properties?, categoryId?}]. Properties are validated per node type.
↳ properties	object	✗	Direct Figma API props (escape hatch)

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

delete

editinherited

Delete nodes

Parameter	Type	Required	Description
id	string	✗	Single node ID
items	object[]	✗	Batch: [{id}, ...]
↳ id	string	✗

Response

Field	Type	Description
results	string[]	Array of "ok" per item

clone

createinherited

Duplicate nodes — produces a same-type copy (frame→frame, instance→instance, component→component). Instance clones reference the same source component; they do not duplicate the component definition.

Parameter	Type	Required	Description
id	string	✗	Node ID
name	string	✗	Rename the clone (set before appending to parent — required when cloning a variant into its component set to avoid duplicate names)
parentId	string	✗	Parent node ID. Omit to place at current page root.
x	number	✗	X position (default: 0)
y	number	✗	Y position (default: 0)
items	object[]	✗	Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.
↳ id	string	✓	Node ID to clone
↳ name	string	✗	Rename the clone
↳ parentId	string	✗	Target parent
↳ x	number	✗
↳ y	number	✗
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string

audit

readinherited

Run lint on a node — returns severity-ranked findings

Parameter	Type	Required	Description
id	string	✓	Node ID to audit
rules	string[]	✗	Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".
maxDepth	number	✗	Max tree depth (default: 10)
maxFindings	number	✗	Max findings (default: 50)
minSeverity	"error" | "unsafe" | "heuristic" | "style" | "verbose"	✗	Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
skipInstances	boolean	✗	Skip instance internals — findings inside instances are owned by the component (default: true)

Response

Field	Type	Description
nodeId	string
nodeName	string
categories	array	Sorted by severity (error > unsafe > heuristic > style)

reparent

editinherited

Move nodes into a new parent

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, parentId, index?}
↳ id	string	✓
↳ parentId	string	✓
↳ index	number	✗

Response

Field	Type	Description
results	string[]	Array of "ok" per item

create

create

Create text nodes

Parameter	Type	Required	Description
items	object[]	✓	Array of text items to create
↳ text	string	✗	Text content
↳ name	string	✗	Layer name
↳ x	number	✗
↳ y	number	✗
↳ width	number	✗	Fixed width in px — implies layoutSizingHorizontal: FIXED and textAutoResize: HEIGHT
↳ parentId	string	✗	Parent node ID. Omit to place at current page root.
↳ fontFamily	string	✗	Font family (default: Inter). Use fonts.list to find installed fonts.
↳ fontStyle	string	✗	Font variant e.g. "Bold", "Italic" — overrides fontWeight
↳ fontSize	number	✗	Font size (default: 14)
↳ fontWeight	number	✗	100-900 (default: 400). Ignored when fontStyle is set.
↳ lineHeight	any	✗	number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}
↳ letterSpacing	any	✗	number | {value, unit: "PIXELS"|"PERCENT"}
↳ textCase	"ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED"	✗
↳ textDecoration	"NONE" | "UNDERLINE" | "STRIKETHROUGH"	✗
↳ fills	array	✗	Text color paints — e.g. [{type: 'SOLID', color: '#hex'}]. Same as node fills.
↳ fontColor	string	✗	Shorthand — sets text color (auto-binds to matching variable/style)
↳ fontColorVariableName	string	✗	Bind color variable by name e.g. 'text/primary'
↳ fontColorStyleName	string	✗	Apply paint style — overrides fontColor
↳ textStyleId	string	✗	Text style ID or name (case-insensitive) — overrides fontSize/fontWeight
↳ textStyleName	string	✗	Alias for textStyleId — accepts name (case-insensitive)
↳ textAlignHorizontal	"LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED"	✗
↳ textAlignVertical	"TOP" | "CENTER" | "BOTTOM"	✗
↳ layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
↳ layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
↳ textAutoResize	"NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT" | "TRUNCATE"	✗	NONE (fixed box), WIDTH_AND_HEIGHT (grow both), HEIGHT (fixed width, auto height), TRUNCATE (fixed + ellipsis)
↳ componentPropertyName	string	✗	Bind to a component TEXT property by name. Walks up ancestors to find the nearest component, or targets the component specified by componentId. For deeply nested text, consider using components(method:'create', type:'from_node') with exposeText:true instead — it auto-discovers and binds all text nodes.
↳ componentId	string	✗	Target component ID for componentPropertyName binding. When omitted, walks up ancestors to find the nearest COMPONENT or COMPONENT_SET.
↳ annotations	object[]	✗	Annotations — [{label?, labelMarkdown?, properties?, categoryId?}]
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string

set_content

edit

Replace text content on existing text nodes

Parameter	Type	Required	Description
items	object[]	✓	Array of {nodeId, text}
↳ nodeId	string	✓	Text node ID
↳ text	string	✓	New text content
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

Field	Type	Description
results	string[]	Array of "ok" per item

scan

read

Scan all text nodes within a subtree

Parameter	Type	Required	Description
items	object[]	✓	Array of subtrees to scan

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item