From 2bb35329386cf68d25703d283ffd7ac9b654392b Mon Sep 17 00:00:00 2001 From: Devin Abbott Date: Thu, 23 Jun 2016 08:56:01 -0700 Subject: [PATCH] Add docs pages for basics: Dimensions and Layout --- docs/Basics-Component-ListView.md | 2 +- docs/Basics-Dimensions.md | 63 ++++++++++++++++++ docs/Basics-Layout.md | 104 ++++++++++++++++++++++++++++++ 3 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 docs/Basics-Dimensions.md create mode 100644 docs/Basics-Layout.md diff --git a/docs/Basics-Component-ListView.md b/docs/Basics-Component-ListView.md index 10df49a6a48578..d15cdec341ecaf 100644 --- a/docs/Basics-Component-ListView.md +++ b/docs/Basics-Component-ListView.md @@ -4,7 +4,7 @@ title: ListView layout: docs category: The Basics permalink: docs/basics-component-listview.html -next: basics-network +next: basics-dimensions --- On mobile devices, lists are a core element in many applications. The [`ListView`](/react-native/docs/listview.html#content) component is a special type of [`View`](/react-native/docs/basics-component-view.html) that displays a *vertically* scrolling list of changing, but similarly structured, data. diff --git a/docs/Basics-Dimensions.md b/docs/Basics-Dimensions.md new file mode 100644 index 00000000000000..3003c02faaf973 --- /dev/null +++ b/docs/Basics-Dimensions.md @@ -0,0 +1,63 @@ +--- +id: basics-dimensions +title: Dimensions +layout: docs +category: The Basics +permalink: docs/basics-dimensions.html +next: basics-layout +--- + +A component's dimensions determine its size on the screen. + +#### Fixed Dimensions + +The simplest way to set the dimensions of a component is by adding a fixed `width` and `height` to style. All dimensions in React Native are unitless, and represent density-independent pixels. + +```ReactNativeWebPlayer +import React from 'react'; +import { AppRegistry, View } from 'react-native'; + +class AwesomeProject { + render() { + return ( + + + + + + ); + } +}; + +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); +``` + +Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions. + +#### Flex Dimensions + +Use `flex` in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use `flex: 1`, which tells a component to fill all available space, shared evenly amongst each other component with the same parent. The larger the `flex` given, the higher the ratio of space a component will take compared to its siblings. + +> A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed `width` and `height` or `flex`, the parent will have dimensions of 0 and the `flex` children will not be visible. + +```ReactNativeWebPlayer +import React from 'react'; +import { AppRegistry, View } from 'react-native'; + +class AwesomeProject { + render() { + return ( + // Try removing the `flex: 1` on the parent View. + // The parent will not have dimensions, so the children can't expand. + // What if you add `height: 300` instead of `flex: 1`? + + + + + + ); + } +}; + +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); +``` diff --git a/docs/Basics-Layout.md b/docs/Basics-Layout.md new file mode 100644 index 00000000000000..767917563b2a16 --- /dev/null +++ b/docs/Basics-Layout.md @@ -0,0 +1,104 @@ +--- +id: basics-layout +title: Layout +layout: docs +category: The Basics +permalink: docs/basics-layout.html +next: basics-network +--- + +A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes. + +You will normally use a combination of `flexDirection`, `alignItems`, and `justifyContent` to achieve the right layout. + +> Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The most notable one: the defaults are different, with `flexDirection` defaulting to `column` instead of `row`, and `alignItems` defaulting to `stretch` instead of `flex-start`. + +#### Flex Direction + +Adding `flexDirection` to a component's `style` determines the **primary axis** of its layout. Should the children be organized horizontally (`row`) or vertically (`column`)? The default is `column`. + +```ReactNativeWebPlayer +import React from 'react'; +import { AppRegistry, View } from 'react-native'; + +class AwesomeProject { + render() { + return ( + // Try setting `flexDirection` to `column`. + + + + + + ); + } +}; + +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); +``` + +#### Justify Content + +Adding `justifyContent` to a component's style determines the **distribution** of children along the **primary axis**. Should children be distributed at the start, the center, the end, or spaced evenly? Available options are `flex-start`, `center`, `flex-end`, `space-around`, and `space-between`. + +```ReactNativeWebPlayer +import React from 'react'; +import { AppRegistry, View } from 'react-native'; + +class AwesomeProject { + render() { + return ( + // Try setting `justifyContent` to `center`. + // Try setting `flexDirection` to `row`. + + + + + + ); + } +}; + +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); +``` + +#### Align Items + +Adding `alignItems` to a component's style determines the **alignment** of children along the **secondary axis** (if the primary axis is `row`, then the secondary is `column`, and vice versa). Should children be aligned at the start, the center, the end, or stretched to fill? Available options are `flex-start`, `center`, `flex-end`, and `stretch`. + +> For `stretch` to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting `alignItems: stretch` does nothing until the `width: 50` is removed from the children. + +```ReactNativeWebPlayer +import React from 'react'; +import { AppRegistry, View } from 'react-native'; + +class AwesomeProject { + render() { + return ( + // Try setting `alignItems` to 'flex-start' + // Try setting `justifyContent` to `flex-end`. + // Try setting `flexDirection` to `row`. + + + + + + ); + } +}; + +AppRegistry.registerComponent('AwesomeProject', () => AwesomeProject); +``` + +#### API Reference + +We've covered the basics, but there are many other styles you may need for layouts. The full list is available [here](./docs/flexbox.html).