BnImage
Namespace: BlazorNative.Components
An image loaded from a URL. Renders as a native ImageView on Android
and as BnImageView on iOS, a UIImageView subclass that carries
the decoded bytes' own pixel size for measurement. The platform fetches,
decodes and measures the bytes — your code only names the source. The rest
of its surface is
BnView's flex item surface (BnLayoutItem.Grow,
BnLayoutItem.Shrink, BnLayoutItem.Basis,
BnLayoutItem.AlignSelf, the box, BnLayoutItem.Margin,
BnLayoutItem.Position).
public sealed class BnImage : BnLayoutItem, Microsoft.AspNetCore.Components.IComponent, Microsoft.AspNetCore.Components.IHandleEvent, Microsoft.AspNetCore.Components.IHandleAfterRender
Inheritance Object → ComponentBase → BnLayoutItem → BnImage
Implements IComponent, IHandleEvent, IHandleAfterRender
Attributes NullableContextAttribute, NullableAttribute
Remarks:
Sizing is the decision this component's shape makes. Set
BnLayoutItem.WidthandBnLayoutItem.Height and the frame is exactly
those numbers, always — the bytes never move it, so nothing below it ever
reflows. Set NEITHER and the image is intrinsic: it measures
0 × 0 until its bytes arrive and its natural pixel size (in dp
or pt) afterwards, at which point the layout re-solves and its siblings below
move down. Exactly one reflow, never two.
On failure the node stays 0 × 0: it reserves no space, and it
does not retry. Changing BnImage.Src, or removing the image, cancels the
in-flight request, so a late arrival can never paint into something you have
replaced. Setting to null clears the image and
re-solves: an intrinsic image collapses back to 0 × 0 and its siblings
move back up. That is the same reflow in the other direction, and it
is part of the contract rather than an accident.
Not a flex container, and not a container at all. There is no
Direction, Justify, Align, Wrap, Gap,
Padding — and no ChildContent. An image is a leaf: it has
no Yoga children for any of them to arrange. To overlay content on an image,
compose (a BnView parent with an absolutely positioned child).
Nothing else here changes the sizing rules above.BnImage.PlaceholderColor never measures, BnImage.OnError never changes measurement, and BnImage.ContentMode is paint-only. Whatever you set among those three, the frame is the one the two paragraphs above describe.
Properties
Src
The image URL. The platform fetches it — you cannot hand this component bytes.
Null = no source: nothing is fetched, and the node keeps measuring
0 × 0 unless BnLayoutItem.Width and
BnLayoutItem.Height say otherwise. Changing it cancels any
request still in flight for this image.
Setting it back to null is a real change, not a no-op: the
image is cleared, and an intrinsic node collapses to 0 × 0 so its
siblings move back up.
public string? Src { get; set; }
Property Value
PlaceholderColor
A colour to paint while the image is loading — a hex string, not content and not a second image. It stays as the visible state if the load fails, and is cleared once the real bytes paint. Null = no placeholder.
It never measures and never reflows: it paints inside
whatever box the layout already gave the node. That means an
intrinsic image's placeholder is invisible — a 0 × 0 box
paints nothing — so give the image a size if you want a placeholder to
show. Letterbox bars show BnLayoutItem.BackgroundColor, never
this.
public string? PlaceholderColor { get; set; }
Property Value
ContentMode
How the pixels are painted inside the box the layout gave this image. Paint-only: the mode never changes measurement, so every frame is identical under all four modes and the paint never escapes the box — both platforms clip it.
Null leaves the platform default, which is Contain
(aspect-fit). Clearing the parameter restores that default. See
ImageContentMode for the four modes.
public ImageContentMode? ContentMode { get; set; }
Property Value
OnError
Raised when the image fails to load. The arguments carry the failed URL and nothing else. Optional: nothing is attached to the native control unless you supply a handler.
Failure never changes measurement: a declared box keeps its
size, an intrinsic node stays 0 × 0. The platform will not
substitute anything of its own — a fallback is whatever you render from
this handler (swap the BnImage.Src, unmount the image, show a
message).
It fires at most once per request, and only for the request that is still current: cancelling — changing BnImage.Src, setting it to null, or removing the image — is not a failure and raises nothing. There is no matching success event.
public EventCallback<BnImageErrorEventArgs> OnError { get; set; }
Property Value
EventCallback<BnImageErrorEventArgs>
BackgroundColor
Fill colour behind the component. Null leaves it transparent.
public string? BackgroundColor { get; set; }
Property Value
Margin
Space outside the component, between it and its siblings. Null = none.
public BnAutoLength? Margin { get; set; }
Property Value
Remarks:
auto is legal here and absorbs free space, which re-centres the node.
AlignSelf
Cross-axis alignment for this item alone, overriding the parent's. Null = inherit.
public FlexAlign? AlignSelf { get; set; }
Property Value
Grow
Share of leftover space this item takes (unitless ratio). Null = Yoga's default (0).
public float? Grow { get; set; }
Property Value
Shrink
Share of overflow this item gives up (unitless ratio). Null = Yoga's default (1).
public float? Shrink { get; set; }
Property Value
Basis
Starting main-axis size before grow/shrink. Null = auto.
public BnAutoLength? Basis { get; set; }
Property Value
Width
Box width. Null = auto.
public BnAutoLength? Width { get; set; }
Property Value
Height
Box height. Null = auto.
public BnAutoLength? Height { get; set; }
Property Value
MinWidth
Lower bound on width. Null = unset.
public BnLength? MinWidth { get; set; }
Property Value
MaxWidth
Upper bound on width. Null = unset.
public BnLength? MaxWidth { get; set; }
Property Value
MinHeight
Lower bound on height. Null = unset.
public BnLength? MinHeight { get; set; }
Property Value
MaxHeight
Upper bound on height. Null = unset.
public BnLength? MaxHeight { get; set; }
Property Value
Position
Positioning scheme. Null = Yoga's default (relative).
public FlexPosition? Position { get; set; }
Property Value
Top
Top inset. Null = unset.
public BnLength? Top { get; set; }
Property Value
Right
Right inset. Null = unset.
public BnLength? Right { get; set; }
Property Value
Bottom
Bottom inset. Null = unset.
public BnLength? Bottom { get; set; }
Property Value
Left
Left inset. Null = unset.
public BnLength? Left { get; set; }
Property Value
Constructors
BnImage()
public BnImage()