FieldRun Class @beta
A Run that displays the formatted value of a property of some Element.
When a TextBlock containing a FieldRun is written into the iModel as an ITextAnnotation element,
a dependency is established between the two elements via the ElementDrivesTextAnnotation relationship such that
whenever the source element specified by propertyHost is modified or the ITextAnnotation element is inserted or updated in the iModel,
the field(s) in the ITextAnnotation element are automatically
recalculated, causing their cachedContent to update. If the field's display string cannot be evaluated (for example, because the specified element or
property does not exist), then its cached content is set to invalidContentIndicator.
A FieldRun displays its cachedContent in the same way that TextRuns display their content, including word wrapping where appropriate.
Extends
Methods
| Name | Description | |
|---|---|---|
| clone(): FieldRun | Create a deep copy of this FieldRun. | |
| equals(other: TextBlockComponent): boolean | Returns true if this is equivalent to other. |
|
| stringify(): string | Convert this FieldRun to a simple string representation. | |
| toJSON(): FieldRunProps | Convert the FieldRun to its JSON representation. | |
| create(props: Omit<FieldRunProps, "type">): FieldRun Static | Create a FieldRun from its JSON representation. |
Inherited methods
| Name | Inherited from | Description |
|---|---|---|
| clearStyleOverrides(_options?: ClearTextStyleOptions): void Inherited | TextBlockComponent | Reset any styleOverrides applied to this component. |
Properties
| Name | Type | Description | |
|---|---|---|---|
| cachedContent Accessor ReadOnly | string | The field's most recently evaluated display string. | |
| formatOptions | FieldFormatOptions | undefined | Specifies how to format the property value obtained from propertyPath into a string to be stored in cachedContent. | |
| invalidContentIndicator Static | string | Display string used to signal an error in computing the field's value. | |
| isEmpty Accessor ReadOnly | boolean | Returns true if this component has no content or children. | |
| propertyHost | FieldPropertyHost | The element and BIS class containing the property described by propertyPath. | |
| propertyPath | FieldPropertyPath | Describes how to obtain the property value from propertyHost. | |
| type Readonly | "field" | Discriminator field for the Run union. |
Inherited properties
| Name | Type | Inherited from | Description |
|---|---|---|---|
| isWhitespace Accessor Inherited ReadOnly | boolean | TextBlockComponent | Returns true if the string representation of this component consists only of whitespace characters. Useful for checking if the component is visually empty (producing no graphics) or contains only spaces, tabs, or line breaks. |
| overridesStyle Accessor Inherited ReadOnly | boolean | TextBlockComponent | Returns true if styleOverrides specifies any deviations from the TextBlock's AnnotationTextStyle. |
| styleOverrides Accessor Inherited | TextStyleSettingsProps | TextBlockComponent | Deviations in individual properties of the TextStyleSettings in the AnnotationTextStyle. For example, if the style uses the "Arial" font, you can override that by settings styleOverrides.font.name to "Comic Sans". |
Defined in
Last Updated: 07 October, 2025