Skip to content

Commit 2e8235d

Browse files
rigor789rigor789
committed
docs: document Frame
1 parent b9a2c12 commit 2e8235d

File tree

2 files changed

+234
-1
lines changed

2 files changed

+234
-1
lines changed

‎content/ui/frame.md

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: Frame
3+
description: UI component for displaying and navigating between Pages.
4+
contributors:
5+
- rigor789
6+
---
7+
8+
`<Frame>` is a UI component used to display and navigate between [Pages](/ui/page). A NativeScript app can have multiple Frames, or none - most apps will have at least a single Frame often set as the the root view (or inside a [RootLayout](/ui/root-layout)).
9+
10+
## Examples
11+
12+
### A single root Frame
13+
14+
This example shows a single root frame that navigates to the `main-page` by default, and allows the user to navigate further within this frame (spanning the full-screen).
15+
16+
```xml
17+
<!-- app-root -->
18+
<Frame defaultPage="main-page"/>
19+
```
20+
21+
### A global menu bar and a Frame
22+
23+
This example shows an always visible menu bar stacked above a Frame that allows the user to navigate further.
24+
25+
```xml
26+
<GridLayout rows="auto, *">
27+
<Label row="0" text="Example Menu Bar"/>
28+
<ContentView row="1">
29+
<Frame defaultPage="mainPage"/>
30+
</ContentView>
31+
</GridLayout>
32+
```
33+
34+
::: info Note
35+
We have wrapped the Frame inside a ContentView because on iOS a frame always spans the full height of it's parent container, so we wouldn't be able to resize it without the additional ContentView.
36+
:::
37+
38+
### Multiple root Frames
39+
40+
This pseudo example shows two Frames side-by-side, the frame on the left represents a list of conversations, and the Frame on the right represents the details of the currently selected conversation.
41+
42+
The idea of using a Frame on the left is to allow navigating to a different Page while keeping the conversation-details open on the right.
43+
44+
```xml
45+
<GridLayout columns="300, *">
46+
<ContentView col="0">
47+
<Frame defaultPage="conversation-list" />
48+
</ContentView>
49+
<ContentView col="1">
50+
<Frame defaultPage="conversation-details" />
51+
</ContentView>
52+
</GridLayout>
53+
```
54+
55+
::: info Note
56+
This is a simplified example to convey the possibilities, in a real app implementation there would be nuances specific to the app.
57+
:::
58+
59+
## Props
60+
61+
### actionBarVisibility
62+
63+
```ts
64+
actionBarVisibility: 'auto' | 'always' | 'never'
65+
```
66+
67+
Used to control the visibility the Navigation Bar in iOS and the Action Bar in Android for all Pages within this Frame.
68+
69+
### animated
70+
71+
```ts
72+
animated: boolean
73+
```
74+
75+
Gets or sets if navigation transitions within this Frame should be animated.
76+
77+
### backStack
78+
79+
```ts
80+
backStack: BackstackEntry[]
81+
```
82+
83+
**Readonly** list of backstack entries.
84+
85+
See [BackstackEntry](/api/interface/BackstackEntry).
86+
87+
### currentEntry
88+
89+
```ts
90+
currentEntry: NavigationEntry
91+
```
92+
93+
**Readonly**. The current NavigationEntry the Frame is navigated to.
94+
95+
See [NavigationEntry](/api/interface/NavigationEntry).
96+
97+
### currentPage
98+
99+
```ts
100+
currentPage: Page
101+
```
102+
103+
**Readonly**. The current Page the Frame is navigated to.
104+
105+
See [Page](/ui/Page).
106+
107+
### transition
108+
109+
```ts
110+
transition: NavigationTransition
111+
```
112+
113+
Gets or sets the default navigation transition for this Frame.
114+
115+
See [NavigationTransition](/api/interface/NavigationTransition).
116+
117+
### defaultAnimatedNavigation
118+
119+
```ts
120+
defaultAnimatedNavigation: boolean
121+
```
122+
123+
**Static**. Gets or sets if navigation transitions should be animated globally.
124+
125+
### defaultTransition
126+
127+
```ts
128+
defaultTransition: NavigationTransition
129+
```
130+
131+
**Static**. Gets or sets the default NavigationTransition for all frames across the app.
132+
133+
See [NavigationTransition](/api/interface/NavigationTransition).
134+
135+
### ...Inherited
136+
137+
For additional inherited properties, refer to the [API Reference](/api/class/Frame).
138+
139+
## Methods
140+
141+
### canGoBack()
142+
143+
```ts
144+
canGoBack(): boolean
145+
```
146+
147+
Returns wether or not this Frame can navigate back (there are entries in the backstack).
148+
149+
### goBack()
150+
151+
```ts
152+
goBack(to?: BackstackEntry): void
153+
```
154+
155+
Navigates to the previous entry (or `to`) in the backstack.
156+
157+
See [BackstackEntry](/api/interface/BackstackEntry).
158+
159+
### navigate()
160+
161+
```ts
162+
navigate(pageModuleName: string): void
163+
// or
164+
navigate(create: () => Page): void
165+
// or
166+
naviage(entry: NavigationEntry): void
167+
```
168+
169+
Navigates to a Page.
170+
171+
See [Frame.navigate Reference](/api/class/Frame#navigate), [Page](/ui/page), [NavigationEntry](/api/interface/NavigationEntry).
172+
173+
### getFrameById()
174+
175+
```ts
176+
getFrameById(id: string): Frame
177+
```
178+
179+
**Static**. Returns a Frame by it's `id` if found.
180+
181+
See [Frame](/ui/frame).
182+
183+
### topmost()
184+
185+
```ts
186+
topmost(): Frame
187+
```
188+
189+
**Static**. Returns the topmost frame.
190+
191+
See [Frame](/ui/frame).
192+
193+
## Events
194+
195+
### navigatingTo
196+
197+
```ts
198+
on('navigatingTo', (args: NavigationData) => {
199+
const frame = args.object as Frame
200+
const entry = args.entry as BackstackEntry
201+
const page = entry.resolvedPage as Page
202+
})
203+
```
204+
205+
Emitted when the Frame is navigating to a new Page.
206+
207+
### navigatedTo
208+
209+
```ts
210+
on('navigatedTo', (args: NavigationData) => {
211+
const frame = args.object as Frame
212+
const entry = args.entry as BackstackEntry
213+
const page = entry.resolvedPage as Page
214+
})
215+
```
216+
217+
Emitted when the Frame has navigated to a new Page.
218+
219+
## Native component
220+
221+
| Android | iOS |
222+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
223+
| [`org.nativescript.widgets.ContentLayout`](https://github.com/NativeScript/tns-core-modules-widgets/blob/master/android/widgets/src/main/java/org/nativescript/widgets/ContentLayout.java) | [`UINavigationController`](https://developer.apple.com/documentation/uikit/uinavigationcontroller) |

‎content/ui/sidebar.ts

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,19 @@ export default [
2626
text: 'Navigation Components',
2727
link: '/ui/#navigation-containers',
2828
items: [
29-
// { text: 'Frame', link: '//#' },
29+
{ text: 'Frame', link: '/ui/frame' },
3030
{ text: 'Page', link: '/ui/page' },
3131
{ text: 'ActionBar', link: '/ui/action-bar' },
32+
{
33+
text: 'ActionItem',
34+
link: '/ui/action-bar#action-item',
35+
visible: false, // only shown in the index/reference
36+
},
37+
{
38+
text: 'NavigationButton',
39+
link: '/ui/action-bar#navigation-button',
40+
visible: false, // only shown in the index/reference
41+
},
3242
],
3343
},
3444
{

0 commit comments

Comments
 (0)