An image-like control that has different display options for representing images, initials, and icons.
The Avatar
control allows the usage of different content, shapes, and sizes depending on the use case.
The content types that can be displayed are either images, icons, or initials. The shape can be circular or square. There are several predefined sizes, as well as an option to set a custom size.
Up to two Latin letters can be displayed as initials in an Avatar
. If there are more than two letters, or if there's a non-Latin character present, a default image placeholder will be created.
There are two options for how the displayed image can fit inside the available area:
Avatar
, you have to choose the Custom
value for the displaySize
property. Then, you have to set both the customDisplaySize
and customFontSize
properties.
Constructor for a new Avatar
.
Accepts an object literal mSettings
that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.
new sap.m.Avatar(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | ID for the new control, generated automatically if no ID is given |
|
mSettings? | object | Initial settings for the new control |
Name | Type | Default Value | Description |
---|---|---|---|
backgroundColor | sap.m.AvatarColor | Accent6 | Determines the background color of the control. Visibility: public |
badgeIcon | sap.ui.core.URI | empty string | Defines what type of icon is displayed as visual affordance. It can be predefined or custom. The predefined icons are recommended for:
Since: 1.77.Visibility: public |
badgeTooltip | string | Defines a custom tooltip for the If not set, default tooltips are used as follows:
Since: 1.77.Visibility: public |
|
customDisplaySize | sap.ui.core.CSSSize | 3rem | Specifies custom display size of the Note: It takes effect if the |
customFontSize | sap.ui.core.CSSSize | 1.125rem | Specifies custom font size of the Note: It takes effect if the |
displayShape | sap.m.AvatarShape | Circle | Defines the shape of the |
displaySize | sap.m.AvatarSize | S | Sets a predefined display size of the |
fallbackIcon | string | Defines the fallback icon displayed in case of wrong image src and no initials set. Notes:
|
|
imageFitType | sap.m.AvatarImageFitType | Cover | Specifies how an image would fit in the |
initials | string | Defines the displayed initials. Visibility: public |
|
showBorder | boolean | false | Determines whether the control is displayed with border. Visibility: public |
src | sap.ui.core.URI | Determines the path to the desired image or icon. Visibility: public |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
_badge | 0..1 | sap.ui.core.Icon |
A |
_icon | 0..1 | sap.ui.core.Icon |
A |
detailBox | 0..1 | sap.m.LightBox |
A The |
Name | Cardinality | Type | Description |
---|---|---|---|
ariaDescribedBy | 0..n | sap.ui.core.Control |
Association to controls / ids which describe this control (see WAI-ARIA attribute aria-describedby). |
ariaLabelledBy | 0..n | sap.ui.core.Control |
Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledBy). |
Method | Description |
---|---|
addAriaDescribedBy |
Adds some ariaDescribedBy into the association ariaDescribedBy. |
addAriaLabelledBy |
Adds some ariaLabelledBy into the association ariaLabelledBy. |
attachPress |
Attaches event handler When called, the context of the event handler (its Fired when the user selects the control. |
bindDetailBox |
Binds aggregation detailBox to model data. See ManagedObject.bindAggregation for a detailed description of the possible properties of |
destroyDetailBox |
Destroys the detailBox in the aggregation detailBox. |
detachPress |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.Avatar.extend |
Creates a new subclass of class sap.m.Avatar with name
|
firePress |
Fires event press to attached listeners. |
getAriaDescribedBy |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy. |
getAriaLabelledBy |
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy. |
getBackgroundColor |
Gets current value of property backgroundColor. Determines the background color of the control. Default value is |
getBadgeIcon |
Gets current value of property badgeIcon. Defines what type of icon is displayed as visual affordance. It can be predefined or custom. The predefined icons are recommended for:
Default value is |
getBadgeTooltip |
Gets current value of property badgeTooltip. Defines a custom tooltip for the If not set, default tooltips are used as follows:
|
getCustomDisplaySize |
Gets current value of property customDisplaySize. Specifies custom display size of the Note: It takes effect if the Default value is |
getCustomFontSize |
Gets current value of property customFontSize. Specifies custom font size of the Note: It takes effect if the Default value is |
getDetailBox |
Gets content of aggregation detailBox. A The |
getDisplayShape |
Gets current value of property displayShape. Defines the shape of the Default value is |
getDisplaySize |
Gets current value of property displaySize. Sets a predefined display size of the Default value is |
getFallbackIcon |
Gets current value of property fallbackIcon. Defines the fallback icon displayed in case of wrong image src and no initials set. Notes:
|
getImageFitType |
Gets current value of property imageFitType. Specifies how an image would fit in the Default value is |
getInitials |
Gets current value of property initials. Defines the displayed initials. |
sap.m.Avatar.getMetadata |
Returns a metadata object for class sap.m.Avatar. |
getShowBorder |
Gets current value of property showBorder. Determines whether the control is displayed with border. Default value is |
getSrc |
Gets current value of property src. Determines the path to the desired image or icon. |
removeAllAriaDescribedBy |
Removes all the controls in the association named ariaDescribedBy. |
removeAllAriaLabelledBy |
Removes all the controls in the association named ariaLabelledBy. |
removeAriaDescribedBy |
Removes an ariaDescribedBy from the association named ariaDescribedBy. |
removeAriaLabelledBy |
Removes an ariaLabelledBy from the association named ariaLabelledBy. |
setBackgroundColor |
Sets a new value for property backgroundColor. Determines the background color of the control. When called with a value of Default value is |
setBadgeIcon |
Sets a new value for property badgeIcon. Defines what type of icon is displayed as visual affordance. It can be predefined or custom. The predefined icons are recommended for:
When called with a value of Default value is |
setBadgeTooltip |
Sets a new value for property badgeTooltip. Defines a custom tooltip for the If not set, default tooltips are used as follows:
When called with a value of |
setCustomDisplaySize |
Sets a new value for property customDisplaySize. Specifies custom display size of the Note: It takes effect if the When called with a value of Default value is |
setCustomFontSize |
Sets a new value for property customFontSize. Specifies custom font size of the Note: It takes effect if the When called with a value of Default value is |
setDetailBox |
Sets the |
setDisplayShape |
Sets a new value for property displayShape. Defines the shape of the When called with a value of Default value is |
setDisplaySize |
Sets a new value for property displaySize. Sets a predefined display size of the When called with a value of Default value is |
setFallbackIcon |
Sets a new value for property fallbackIcon. Defines the fallback icon displayed in case of wrong image src and no initials set. Notes:
When called with a value of |
setImageFitType |
Sets a new value for property imageFitType. Specifies how an image would fit in the When called with a value of Default value is |
setInitials |
Sets a new value for property initials. Defines the displayed initials. When called with a value of |
setShowBorder |
Sets a new value for property showBorder. Determines whether the control is displayed with border. When called with a value of Default value is |
setSrc |
Sets a new value for property src. Determines the path to the desired image or icon. When called with a value of |
unbindDetailBox |
Unbinds aggregation detailBox from model data. |
Adds some ariaDescribedBy into the association ariaDescribedBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaDescribedBy | sap.ui.core.ID sap.ui.core.Control |
The ariaDescribedBy to add; if empty, nothing is inserted |
Adds some ariaLabelledBy into the association ariaLabelledBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaLabelledBy | sap.ui.core.ID sap.ui.core.Control |
The ariaLabelledBy to add; if empty, nothing is inserted |
Attaches event handler fnFunction
to the press event of this sap.m.Avatar
.
When called, the context of the event handler (its this
) will be bound to oListener
if specified, otherwise it will be bound to this sap.m.Avatar
itself.
Fired when the user selects the control.
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to this |
Binds aggregation detailBox to model data.
See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oBindingInfo | sap.ui.base.ManagedObject.AggregationBindingInfo |
The binding information |
Detaches event handler fnFunction
from the press event of this sap.m.Avatar
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called, when the event occurs |
|
oListener | object |
Context object on which the given function had to be called |
Creates a new subclass of class sap.m.Avatar with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.ui.core.Control.extend.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
Name of the class being created |
|
oClassInfo | object |
Object literal with information about the class |
|
FNMetaImpl | function |
Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class |
Fires event press to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Gets current value of property backgroundColor.
Determines the background color of the control.
Default value is Accent6
.
Gets current value of property badgeIcon.
Defines what type of icon is displayed as visual affordance. It can be predefined or custom.
The predefined icons are recommended for:
sap-icon://zoom-in
sap-icon://camera
sap-icon://edit
Default value is empty string
.
Gets current value of property badgeTooltip.
Defines a custom tooltip for the badgeIcon
. If set, it overrides the available default values.
If not set, default tooltips are used as follows:
badgeIcons
.Gets current value of property customDisplaySize.
Specifies custom display size of the Avatar
.
Note: It takes effect if the displaySize
property is set to Custom
.
Default value is "3rem"
.
Gets current value of property customFontSize.
Specifies custom font size of the Avatar
.
Note: It takes effect if the displaySize
property is set to Custom
.
Default value is "1.125rem"
.
Gets content of aggregation detailBox.
A sap.m.LightBox
instance, that will be opened automatically when the user interacts with the Avatar
control.
The press
event will still be fired.
Gets current value of property displayShape.
Defines the shape of the Avatar
.
Default value is Circle
.
Gets current value of property displaySize.
Sets a predefined display size of the Avatar
.
Default value is S
.
Gets current value of property fallbackIcon.
Defines the fallback icon displayed in case of wrong image src and no initials set.
Notes:
displayShape
property.Gets current value of property imageFitType.
Specifies how an image would fit in the Avatar
.
Default value is Cover
.
Gets current value of property showBorder.
Determines whether the control is displayed with border.
Default value is false
.
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaDescribedBy | int sap.ui.core.ID sap.ui.core.Control |
The ariaDescribedBy to be removed or its index or ID |
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaLabelledBy | int sap.ui.core.ID sap.ui.core.Control |
The ariaLabelledBy to be removed or its index or ID |
Sets a new value for property backgroundColor.
Determines the background color of the control.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Accent6
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sBackgroundColor | sap.m.AvatarColor | Accent6 |
New value for property |
Sets a new value for property badgeIcon.
Defines what type of icon is displayed as visual affordance. It can be predefined or custom.
The predefined icons are recommended for:
sap-icon://zoom-in
sap-icon://camera
sap-icon://edit
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is empty string
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sBadgeIcon | sap.ui.core.URI | "" |
New value for property |
Sets a new value for property badgeTooltip.
Defines a custom tooltip for the badgeIcon
. If set, it overrides the available default values.
If not set, default tooltips are used as follows:
badgeIcons
.When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sBadgeTooltip | string |
New value for property |
Sets a new value for property customDisplaySize.
Specifies custom display size of the Avatar
.
Note: It takes effect if the displaySize
property is set to Custom
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is "3rem"
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sCustomDisplaySize | sap.ui.core.CSSSize | "3rem" |
New value for property |
Sets a new value for property customFontSize.
Specifies custom font size of the Avatar
.
Note: It takes effect if the displaySize
property is set to Custom
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is "1.125rem"
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sCustomFontSize | sap.ui.core.CSSSize | "1.125rem" |
New value for property |
Sets the detailBox
aggregation.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLightBox | sap.m.LightBox undefined |
Instance of the |
Sets a new value for property displayShape.
Defines the shape of the Avatar
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Circle
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDisplayShape | sap.m.AvatarShape | Circle |
New value for property |
Sets a new value for property displaySize.
Sets a predefined display size of the Avatar
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is S
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDisplaySize | sap.m.AvatarSize | S |
New value for property |
Sets a new value for property fallbackIcon.
Defines the fallback icon displayed in case of wrong image src and no initials set.
Notes:
displayShape
property.When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sFallbackIcon | string |
New value for property |
Sets a new value for property imageFitType.
Specifies how an image would fit in the Avatar
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Cover
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sImageFitType | sap.m.AvatarImageFitType | Cover |
New value for property |
Sets a new value for property initials.
Defines the displayed initials.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sInitials | string |
New value for property |
Sets a new value for property showBorder.
Determines whether the control is displayed with border.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is false
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bShowBorder | boolean | false |
New value for property |
Sets a new value for property src.
Determines the path to the desired image or icon.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSrc | sap.ui.core.URI |
New value for property |