Location Ref

PreviousNext

API reference for location references in Plate.

Location references are objects that keep specific locations (paths, points, or ranges) in a document synced over time as new operations are applied to the editor. You can access their current property at any time for the up-to-date location value. You can access their current property at any time for the up-to-date location value.

Types

PathRef

Path reference objects keep a specific path in a document synced over time. Created using editor.api.pathRef.

Attributes

  • current Path | null

    The current path value, updated as operations are applied.

  • affinity 'forward' | 'backward' | null

    The direction to prefer when transforming the path:

    • 'forward': Prefer the position after inserted content
    • 'backward': Prefer the position before inserted content
    • null: No preference

  • unref() () => Path | null

    Call this when you no longer need to sync this path. Returns the final path value.

PointRef

Point reference objects keep a specific point in a document synced over time. Created using editor.api.pointRef.

Attributes

Collapse all

  • current Point | null

    The current point value, updated as operations are applied.

  • affinity 'forward' | 'backward' | null

    The direction to prefer when transforming the point:

    • 'forward': Prefer the position after inserted content
    • 'backward': Prefer the position before inserted content
    • null: No preference

  • unref() () => Point | null

    Call this when you no longer need to sync this point. Returns the final point value.

RangeRef

Range reference objects keep a specific range in a document synced over time. Created using editor.api.rangeRef.

Attributes

Collapse all

  • current TRange | null

    The current range value, updated as operations are applied.

  • affinity 'forward' | 'backward' | 'inward' | 'outward' | null

    The direction to prefer when transforming the range:

    • 'forward': Both points prefer after inserted content
    • 'backward': Both points prefer before inserted content
    • 'inward': Range tends to stay same size when content is inserted at edges
    • 'outward': Range tends to grow when content is inserted at edges
    • null: No preference

  • unref() () => TRange | null

    Call this when you no longer need to sync this range. Returns the final range value.

Example usage of a RangeRef:

const selectionRef = editor.api.rangeRef(editor.selection, {
  affinity: 'inward',
})
// Operations that might change the selection
Transforms.unwrapNodes(editor)
// Restore the selection using the ref
Transforms.select(editor, selectionRef.unref())

PathRefApi

transform

Transform a path reference by an operation.

Parameters

Collapse all

  • ref PathRef

    The path reference to transform.

  • op Operation

    The operation to apply. The editor calls this automatically as needed.

PointRefApi

transform

Transform a point reference by an operation.

Parameters

Collapse all

  • ref PointRef

    The point reference to transform.

  • op Operation

    The operation to apply. The editor calls this automatically as needed.

RangeRefApi

transform

Transform a range reference by an operation.

Parameters

Collapse all

  • ref RangeRef

    The range reference to transform.

  • op Operation

    The operation to apply. The editor calls this automatically as needed.

位置引用位置(Location)