Packages > @fluidframework/tree > TreeView

TreeView Interface

An editable view of a (version control style) branch of a shared tree based on some schema.

This schema–known as the view schema–may or may not align the stored schema of the document. Information about discrepancies between the two schemas is available via compatibility .

Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and choose a schema compatibility policy that aligns with their application’s needs.

Signature

/** @sealed */
export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable

Extends: IDisposable

Type Parameters

Parameter Constraint Description
TSchema ImplicitFieldSchema

Properties

Property Modifiers Type Description
compatibility readonly SchemaCompatibilityStatus

Description of the current compatibility status between the view schema and stored schema.

schemaChanged() is fired when the compatibility status changes.

events readonly Listenable<TreeViewEvents> Events for the tree.
root TreeFieldFromImplicitField<TSchema>

The current root of the tree.

If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility's canView before using.

To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback).

To get notified about changes to stored schema (which may affect compatibility between this view's schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).

Methods

Method Return Type Description
initialize(content) void

Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.

Only valid to call when this view's canInitialize is true.

Applications should typically call this function before attaching a SharedTree.

upgradeSchema() void When the schemas are not an exact match and canUpgrade is true, this can be used to modify the stored schema to make it match the view schema. This will update the compatibility state, and allow access to root. Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!

Property Details

compatibility

Description of the current compatibility status between the view schema and stored schema.

schemaChanged() is fired when the compatibility status changes.

Signature

readonly compatibility: SchemaCompatibilityStatus;

Type: SchemaCompatibilityStatus

events

Events for the tree.

Signature

readonly events: Listenable<TreeViewEvents>;

Type: Listenable <TreeViewEvents >

root

The current root of the tree.

If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility ’s canView before using.

To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback).

To get notified about changes to stored schema (which may affect compatibility between this view’s schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).

Signature

get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);

Type: TreeFieldFromImplicitField <TSchema>

Method Details

initialize

Initialize the tree, setting the stored schema to match this view’s schema and setting the tree content.

Only valid to call when this view’s canInitialize is true.

Applications should typically call this function before attaching a SharedTree.

Signature

initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;

Parameters

Parameter Type Description
content InsertableTreeFieldFromImplicitField<TSchema> The content to initialize the tree with.

upgradeSchema

When the schemas are not an exact match and canUpgrade is true, this can be used to modify the stored schema to make it match the view schema. This will update the compatibility state, and allow access to root. Beware that this may impact other clients’ ability to view the document depending on the application’s schema compatibility policy!

Signature

upgradeSchema(): void;

Remarks

It is an error to call this when canUpgrade is false, and a no-op when the stored and view schema are already an exact match.