Skip to content

Commit a30d49c

Browse files
rigor789rigor789
committed
docs: cleanup Image
1 parent e229826 commit a30d49c

File tree

1 file changed

+54
-252
lines changed

1 file changed

+54
-252
lines changed

‎content/ui/image.md

Lines changed: 54 additions & 252 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
---
22
title: Image
3+
description: UI component for rendering images
4+
contributors:
5+
- rigor789
6+
- Ombuweb
37
---
48

5-
`<Image>` is a UI component that shows an image from an [ImageSource](https://docs.nativescript.org/api-reference/classes/imagesource) or from a URL.
9+
`<Image>` is a UI component for rendering images. Images can be referenced by URL, resource URL (`res://`), base64 string, font resource (`font://`), [ImageSource](/api/class/ImageSource), and [ImageAsset](/api/class/ImageAsset).
610

7-
<!-- TODO: fix links -->
8-
<!-- TODO: add flavors -->
9-
10-
::: tip
11+
<!-- ::: tip
1112
When working with images, consider following [the best practices](/performance.html#image-optimizations).
12-
:::
13-
14-
---
13+
::: -->
1514

1615
<DeviceFrame type="ios">
1716
<img src="https://raw.githubusercontent.com/nativescript-vue/nativescript-vue-ui-tests/master/screenshots/ios-simulator103iPhone6/Image.png"/>
@@ -20,318 +19,121 @@ When working with images, consider following [the best practices](/performance.h
2019
<img src="https://raw.githubusercontent.com/nativescript-vue/nativescript-vue-ui-tests/master/screenshots/android23/Image.png" />
2120
</DeviceFrame>
2221

23-
### Displaying an image from `App_Resources`
24-
25-
<!-- /// flavor plain -->
26-
27-
```xml
28-
<Image src="res://icon" stretch="aspectFill" />
29-
```
30-
31-
<!-- ///
32-
33-
/// flavor angular
34-
35-
```xml
36-
<Image src="res://icon" stretch="aspectFill"> </image>
37-
```
38-
39-
///
40-
41-
/// flavor react
42-
43-
```tsx
44-
<Image src="res://icon" stretch="aspectFill" />
45-
```
46-
47-
///
48-
49-
/// flavor vue
22+
## Examples
5023

51-
```xml
52-
<Image src="res://icon" stretch="aspectFill" />
53-
```
54-
55-
///
56-
57-
/// flavor svelte
58-
59-
```xml
60-
<Image src="res://icon" stretch="aspectFill" />
61-
```
62-
63-
/// -->
64-
65-
### Displaying an image relative to the `app` directory
24+
### Displaying images from App_Resources
6625

67-
<!-- /// flavor plain -->
26+
To display images from platform specific locations (`App_Resources/Android/drawable-XXX/`, or `App_Resources/iOS/`) prefix the source with `res://`.
6827

6928
```xml
70-
<Image src="~/logo.png" stretch="aspectFill" />
71-
```
72-
73-
<!-- ///
74-
75-
/// flavor angular
76-
77-
```xml
78-
<Image src="~/logo.png" stretch="aspectFill"></image>
79-
```
80-
81-
///
82-
83-
/// flavor react
84-
85-
```tsx
86-
<Image src="~/logo.png" stretch="aspectFill" />
87-
```
88-
89-
///
90-
91-
/// flavor vue
92-
93-
```xml
94-
<Image src="~/logo.png" stretch="aspectFill" />
95-
```
96-
97-
///
98-
99-
/// flavor svelte
100-
101-
```xml
102-
<Image src="~/logo.png" stretch="aspectFill" />
103-
```
104-
105-
/// -->
106-
107-
### Displaying an image from a URL
108-
109-
:::tip Note
110-
111-
Setting `loadMode` to `async` will prevent freezing the UI on Android when loading photos async (e.g. from online API)
112-
113-
:::
114-
115-
<!-- /// flavor plain -->
116-
117-
```xml
118-
<Image
119-
src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
120-
stretch="aspectFill"
121-
/>
122-
```
123-
124-
<!-- ///
125-
126-
/// flavor angular
127-
128-
```xml
129-
<Image
130-
src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
131-
stretch="aspectFill"
132-
>
133-
</image>
134-
```
135-
136-
///
137-
138-
/// flavor react
139-
140-
```tsx
141-
<Image
142-
src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
143-
stretch="aspectFill"
144-
/>
29+
<Image src="res://icon" />
14530
```
14631

147-
///
32+
### Displaying images from the src/assets directory
14833

149-
/// flavor vue
34+
By default all assets placed in the `src/assets` directory (create the directory if it's not present) will be copied to the correct native platform location to be bundled with the app. To reference these images, prefix them with the `~` character, which is an alias pointing to the `src` folder.
15035

15136
```xml
152-
<Image
153-
src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
154-
stretch="aspectFill"
155-
/>
37+
<Image src="~/assets/logo.png" />
15638
```
15739

158-
///
40+
### Displaying images from URLs
15941

160-
/// flavor svelte
42+
Images can be displayed from remote URLs. Depending on the software version of the device, insecure URLs may be blocked (`http://`), it's recommended to always use secure URLs (`https://`).
16143

16244
```xml
16345
<Image
16446
src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
165-
stretch="aspectFill"
16647
/>
16748
```
16849

169-
/// -->
170-
171-
### Displaying a `base64`-encoded image
172-
173-
<!-- /// flavor plain -->
174-
175-
```xml
176-
<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />
177-
```
178-
179-
<!--
180-
///
181-
182-
/// flavor angular
183-
184-
```xml
185-
<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill"></image>
186-
```
187-
188-
///
189-
190-
/// flavor react
191-
192-
```tsx
193-
<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />
194-
```
195-
196-
///
197-
198-
/// flavor vue
199-
200-
```xml
201-
<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />
202-
```
203-
204-
///
205-
206-
/// flavor svelte
207-
208-
```xml
209-
<Image src="data:Image/png;base64,iVBORw..." stretch="aspectFill" />
210-
```
211-
212-
/// -->
213-
214-
### Rendering a font icon as image
50+
### Displaying `base64`-encoded images
21551

216-
<!-- /// flavor plain -->
52+
Images can be displayed from `base64` encoded strings.
21753

21854
```xml
219-
<Image src="font://&#xf004;" class="fas" />
55+
<Image src="data:Image/png;base64,iVBORw..." />
22056
```
22157

222-
<!--
223-
///
58+
### Rendering font icons as images
22459

225-
/// flavor angular
60+
Font symbols can be rendered as an image by prefixing the source with `font://` and setting the correct `font-family` via eg. a CSS class:
22661

22762
```xml
228-
<Image src="font://&#xf004;" class="fas"></image>
229-
```
230-
231-
///
232-
233-
/// flavor react
234-
235-
```tsx
23663
<Image src="font://&#xf004;" class="fas" />
23764
```
23865

239-
///
240-
241-
/// flavor vue
242-
243-
```xml
244-
<Image src.decode="font://&#xf004;" class="fas" />
245-
```
246-
247-
:::warning Note
248-
249-
In NativeScript-Vue, `.decode` is required for parsing properties that have HTML entities in them.
250-
251-
:::
252-
253-
///
254-
255-
/// flavor svelte
256-
257-
```xml
258-
<Image src="font://&#xf004;" class="fas" />
66+
```css
67+
.fas {
68+
font-family: 'Font Awesome';
69+
/* ... */
70+
}
25971
```
26072

261-
/// -->
262-
26373
## Props
26474

26575
### src
26676

267-
```xml
268-
<Image src="{{ src }}" />
269-
270-
<Image src="font://&#xf004;" />
271-
272-
<Image src="~/assets/images/cat.jpeg" />
273-
```
274-
27577
```ts
276-
export class HelloWorldModel extends Observable {
277-
src: string | ImageSource | ImageAsset = '~/assets/images/cat.jpeg'
278-
}
78+
src: string | ImageSource | ImageAsset
27979
```
28080

281-
Gets or sets the source([`ImageSource`](https://docs.nativescript.org/api-reference/classes/imagesource) | [`ImageAsset`](/api-reference/classes/imageasset)) of the image.
81+
Gets or sets the source.
28282

283-
---
83+
A string can be a `http://`, `https://`, `res://`, `font://` or an absolute path (eg. `~/assets/image.png`).
84+
85+
See [`ImageSource`](/api/class/ImageSource) and [`ImageAsset`](/api/class/ImageAsset).
28486

28587
### imageSource
28688

28789
```ts
288-
ImageSource.fromUrl(url)
289-
.then((imageSource: ImageSource) => {
290-
image.imageSource = imageSource
291-
})
292-
.catch((error) => {
293-
// handle errror
294-
})
90+
imageSource: ImageSource
29591
```
29692

93+
Gets or sets the source from an `ImageSource` instance.
94+
95+
See [`ImageSource`](/api/class/ImageSource).
96+
29797
### tintColor
29898

299-
```xml
300-
<Image src="{{ src }}" tintColor="#ff00ffaa"/>
99+
```ts
100+
tintColor: Color | string
301101
```
302102

303-
Sets a color to tint template images.
103+
Sets a color to tint the image.
304104

305-
---
105+
See [`Color`](/api/class/Color).
306106

307107
### stretch
308108

309-
```xml
310-
<Image src="{{ src }}" class="fas" stretch="aspectFill"/>
109+
```ts
110+
stretch: ImageStretchType // "none" | "aspectFill" | "aspectFit" | "fill"
311111
```
312112

313-
Gets or sets the way the image is resized to fill its allocated space. For valid values, see [ImageStretch](https://docs.nativescript.org/api-reference/modules/coretypes.imagestretch).
113+
Gets or sets the way the image is resized to fill its allocated space.
314114

315-
---
115+
See [`ImageStretchType`](/api/namespace/CoreTypes#imagestretchtype)
316116

317117
### loadMode
318118

319-
```xml
320-
<Image src="{{ src }}" loadMode="sync"/>
321-
119+
```ts
120+
loadMode: 'sync' | 'async'
322121
```
323122

324-
Gets or sets the loading strategy for the images on the local file system.
123+
Gets or sets the loading strategy for the images.
124+
125+
Default value: `async`.
126+
325127
Valid values:
326128

327-
- `sync` - blocks the UI if necessary to display immediately. Only recommeded for small icons.
328-
- `async` (`default`) - will load in the background, may appear with short delay, good for large images. When loading images from web they are always loaded async no regardless `loadMode` value.
129+
- `sync` - blocks the UI if necessary to display immediately. Only recommeded for small images like icons.
130+
- `async` - loads in the background, the image may appear with a short delay, good for large images.
329131

330-
---
132+
**Note:** When loading images from the web, they are always loaded `async`.
331133

332134
### ...Inherited
333135

334-
For additional inherited properties, refer to the [API Reference](https://docs.nativescript.org/api-reference/classes/image).
136+
For additional inherited properties, refer to the [API Reference](/api/class/Image).
335137

336138
## Native component
337139

0 commit comments

Comments
 (0)