Attributes

A collection of named attribute dictionaries attached to a model or entity.

Attributes let extensions store custom key-value data on models, faces, components, tags, and more. Data is organized into named dictionaries — one per extension namespace. Use getValue() to read a specific value, or allDictionaries to see everything stored on the object.

To write or delete attributes, use op.modelSetAttribute() or op.entitySetAttribute() inside a performOperation.

Example

let model = await SketchUpApi.getActiveModel();

// Create a door group and store its price as an attribute
await model.performOperation(op => {
  const groupRef = op.createGroup(model);
  op.groupSetName(groupRef, 'Door');
  op.createFace(groupRef, [
    [0,0,0],[36,0,0],
    [36,0,84],[0,0,84],
  ]);
  // Use a unique namespace to avoid collisions
  // with other extensions
  op.entitySetAttribute(
    groupRef, 'MyPricingExtension', 'price', 299
  );
}, 'Create $299 door');

// Read the price back
let groups = await model.entities.get({
  filterBy: { types: ['Group'] },
});
let door = groups.find(g => g.name === 'Door');
let attrs = door.attributes;
console.log(
  attrs.findValue('MyPricingExtension', 'price')
);
// => 299

See

Accessors

dictionaries

Get Signature

get dictionaries(): readonly AttributeDictionary[]

All dictionaries attached to this object. May contain duplicates when a model has been imported from another model.

Since

SDK 2.35.0

Returns

readonly AttributeDictionary[]

Methods

findDictionary()

findDictionary(name): AttributeDictionary | undefined

Finds a dictionary by name, returns undefined if not found

Parameters

Parameter	Type	Description
`name`	`string`	dictionary name to find

Returns

AttributeDictionary | undefined

Since

SDK 2.35.0

findValue()

findValue<T>(dictOrPath, key, options?): T

Finds the value at the dictOrPath with the given key

Type Parameters

Type Parameter	Description
`T` extends `AttributeValue`	the expected return type — not verified at runtime

Parameters

Parameter	Type	Description
`dictOrPath`	`string` \| `string`[]	the dictionary name or a path to a dictionary
`key`	`string`	the key
`options?`	{ `default`: `NoInfer`<`T`>; }	allows to define a default value, stops this from throwing when the dictionary or key is not found
`options.default?`	`NoInfer`<`T`>	‐

Returns

T

Example

let model = await SketchUpApi.getActiveModel();
let georeferenced = model.attributes.findValue('GeoReference','UsesGeoReferencing');
// true
console.log(georeferenced);

let someNested = model.attributes.findValue(['Example', 'Nested'], 'Dictionary', {default: 123});
// Default values
console.log(someNested);

// error without default
model.attributes.findValue(['Example', 'Nested'], 'Dictionary');

Throws

Error if a default value is not supplied

hasValue()

hasValue(dict, key): boolean

Determines if the dictionary and attribute key exist in this attributes object

Parameters

Parameter	Type	Description
`dict`	`string` \| `string`[]	the name or path of the dictionary
`key`	`string`	the attribute key

Returns

boolean

true if the dictionary exists and the dictionary contains an attribute with the key

toString()

toString(): string

Returns

string

Show Deprecated

Deprecated

allDictionaries

Get Signature

get allDictionaries(): readonly AttributeDictionary[]

All dictionaries attached to this object. May contain duplicates when a model has been imported from another model.

Returns

readonly AttributeDictionary[]

getAttributesOfDictionary()

getAttributesOfDictionary(dict): Attributes | undefined

Returns the nested Attributes of the named dictionary, or undefined if the dictionary does not exist or has no nested attributes.

Parameters

Parameter	Type
`dict`	`string`

Returns

Attributes | undefined

getValue()

getValue<T>(dict, key): T

Returns the value for the given dictionary and key. Use getValueOrDefault if you want a fallback instead of an exception when the key is missing.

Type Parameters

Type Parameter	Description
`T` extends `AttributeValue`	the expected return type — not verified at runtime

Parameters

Parameter	Type	Description
`dict`	`string`	the name of the dictionary
`key`	`string`	the attribute key

Returns

T

Throws

if the dictionary or key do not exist

getValueOrDefault()

getValueOrDefault<T>(dict, key, defaultValue): T

Returns the value for the given dictionary and key, or defaultValue if the dictionary or key does not exist.

Type Parameters

Type Parameter	Description
`T` extends `AttributeValue`	the expected return type — not verified at runtime

Parameters

Parameter	Type	Description
`dict`	`string`	the name of the dictionary
`key`	`string`	the attribute key
`defaultValue`	`NoInfer`<`T`>	returned when the key is not found

Returns

T

getValueWithPath()

getValueWithPath<T>(path, key): T

Returns the value found by traversing a path of nested dictionaries. Use when attributes are nested inside other dictionaries.

Type Parameters

Type Parameter	Description
`T` extends `AttributeValue`	the expected return type — not verified at runtime

Parameters

Parameter	Type	Description
`path`	`string`[]	non-empty list of dictionary names to traverse
`key`	`string`	the attribute key at the final dictionary

Returns

T

Throws

if any dictionary in the path or the key does not exist

getValueWithPathOrDefault()

getValueWithPathOrDefault<T>(path, key, defaultValue): T

Returns the value found by traversing a path of nested dictionaries, or defaultValue if any step in the path or the key does not exist.

Type Parameters

Type Parameter	Description
`T` extends `AttributeValue`	the expected return type — not verified at runtime

Parameters

Parameter	Type	Description
`path`	`string`[]	non-empty list of dictionary names to traverse
`key`	`string`	the attribute key at the final dictionary
`defaultValue`	`NoInfer`<`T`>	returned when the path or key is not found

Returns

T

hasValueWithPath()

hasValueWithPath(path, key): boolean

Determines if all dictionaries in the path and the attribute key exist.

Parameters

Parameter	Type	Description
`path`	`string`[]	a non-empty list of dictionary names to traverse
`key`	`string`	the attribute key

Returns

boolean

true if the full path resolves and the key exists