Skip to content

Commit 6b7014a

Browse files
ayushjainrkshfacebook-github-bot
ayushjainrksh
authored and
facebook-github-bot
committed
Update the documentation of the Button component (#29155)
Summary: Fixes MLH-Fellowship#33 The PR is part of an effort to update the code comments to match the current documentation on the React Native website. The project is a part of MLH fellowship program and involves automatic generation of the website docs from code comments and flow types as the end result. To learn more about the project you can visit the project wiki: - [Project details](https://github.com/MLH-Fellowship/0.4.x-projects/wiki/React-Native-Flowtype-API-Docs-Generator) - [RN Docs Standards](https://github.com/MLH-Fellowship/react-native/wiki/RN-Docs-standards) Link to the documentation(the source of truth): - [button.md](https://github.com/MLH-Fellowship/react-native-website/blob/master/docs/button.md) ## Changes * Update the title and prop description from docs. * Remove unnecessary `*` from the code comments. * Add default value to props. * Specify the default value of a prop in the code comments with `default` annotation. * For multiple defaults (different devices) use `default {platform android/ios}`. * Update platforms in props. * Use comma separated string with `platform` decorator. * Add Snack player example specified in the docs to the code comments with `example` annotation. ## Changelog [Internal] Pull Request resolved: #29155 Test Plan: All changes are made to the code comments and thus there is no need for testing. [Reviewed by jevakallio](MLH-Fellowship#18) Reviewed By: cpojer Differential Revision: D22767877 Pulled By: motiz88 fbshipit-source-id: ccad8d58dc2888d44d34fdbb94b3c187542e9f2b
1 parent 2258495 commit 6b7014a

1 file changed

Lines changed: 168 additions & 49 deletions

File tree

‎Libraries/Components/Button.js‎

Lines changed: 168 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
*
77
* @format
88
* @flow
9+
* @generate-docs
910
*/
1011

1112
'use strict';
@@ -25,107 +26,225 @@ import type {ColorValue} from '../StyleSheet/StyleSheet';
2526

2627
type ButtonProps = $ReadOnly<{|
2728
/**
28-
* Text to display inside the button
29+
Text to display inside the button. On Android the given title will be
30+
converted to the uppercased form.
2931
*/
3032
title: string,
3133

3234
/**
33-
* Handler to be called when the user taps the button
35+
Handler to be called when the user taps the button. The first function
36+
argument is an event in form of [PressEvent](pressevent).
3437
*/
3538
onPress: (event?: PressEvent) => mixed,
3639

3740
/**
38-
* If true, doesn't play system sound on touch (Android Only)
39-
**/
41+
If `true`, doesn't play system sound on touch.
42+
43+
@platform android
44+
45+
@default false
46+
*/
4047
touchSoundDisabled?: ?boolean,
4148

4249
/**
43-
* Color of the text (iOS), or background color of the button (Android)
50+
Color of the text (iOS), or background color of the button (Android).
51+
52+
@default {@platform android} '#2196F3'
53+
@default {@platform ios} '#007AFF'
4454
*/
4555
color?: ?ColorValue,
4656

4757
/**
48-
* TV preferred focus (see documentation for the View component).
58+
TV preferred focus.
59+
60+
@platform tv
61+
62+
@default false
4963
*/
5064
hasTVPreferredFocus?: ?boolean,
5165

5266
/**
53-
* TV next focus down (see documentation for the View component).
54-
*
55-
* @platform android
67+
Designates the next view to receive focus when the user navigates down. See
68+
the [Android documentation][android:nextFocusDown].
69+
70+
[android:nextFocusDown]:
71+
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown
72+
73+
@platform android, tv
5674
*/
5775
nextFocusDown?: ?number,
5876

5977
/**
60-
* TV next focus forward (see documentation for the View component).
61-
*
62-
* @platform android
78+
Designates the next view to receive focus when the user navigates forward.
79+
See the [Android documentation][android:nextFocusForward].
80+
81+
[android:nextFocusForward]:
82+
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward
83+
84+
@platform android, tv
6385
*/
6486
nextFocusForward?: ?number,
6587

6688
/**
67-
* TV next focus left (see documentation for the View component).
68-
*
69-
* @platform android
89+
Designates the next view to receive focus when the user navigates left. See
90+
the [Android documentation][android:nextFocusLeft].
91+
92+
[android:nextFocusLeft]:
93+
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft
94+
95+
@platform android, tv
7096
*/
7197
nextFocusLeft?: ?number,
7298

7399
/**
74-
* TV next focus right (see documentation for the View component).
75-
*
76-
* @platform android
100+
Designates the next view to receive focus when the user navigates right. See
101+
the [Android documentation][android:nextFocusRight].
102+
103+
[android:nextFocusRight]:
104+
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight
105+
106+
@platform android, tv
77107
*/
78108
nextFocusRight?: ?number,
79109

80110
/**
81-
* TV next focus up (see documentation for the View component).
82-
*
83-
* @platform android
111+
Designates the next view to receive focus when the user navigates up. See
112+
the [Android documentation][android:nextFocusUp].
113+
114+
[android:nextFocusUp]:
115+
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp
116+
117+
@platform android, tv
84118
*/
85119
nextFocusUp?: ?number,
86120

87121
/**
88-
* Text to display for blindness accessibility features
122+
Text to display for blindness accessibility features.
89123
*/
90124
accessibilityLabel?: ?string,
91125

92126
/**
93-
* If true, disable all interactions for this component.
127+
If `true`, disable all interactions for this component.
128+
129+
@default false
94130
*/
95131
disabled?: ?boolean,
96132

97133
/**
98-
* Used to locate this view in end-to-end tests.
134+
Used to locate this view in end-to-end tests.
99135
*/
100136
testID?: ?string,
101137
|}>;
102138

103139
/**
104-
* A basic button component that should render nicely on any platform. Supports
105-
* a minimal level of customization.
106-
*
107-
* <center><img src="img/buttonExample.png"></img></center>
108-
*
109-
* If this button doesn't look right for your app, you can build your own
110-
* button using [TouchableOpacity](docs/touchableopacity.html)
111-
* or [TouchableNativeFeedback](docs/touchablenativefeedback.html).
112-
* For inspiration, look at the [source code for this button component](https://github.com/facebook/react-native/blob/master/Libraries/Components/Button.js).
113-
* Or, take a look at the [wide variety of button components built by the community](https://js.coach/react-native?search=button).
114-
*
115-
* Example usage:
116-
*
117-
* ```
118-
* import { Button } from 'react-native';
119-
* ...
120-
*
121-
* <Button
122-
* onPress={onPressLearnMore}
123-
* title="Learn More"
124-
* color="#841584"
125-
* accessibilityLabel="Learn more about this purple button"
126-
* />
127-
* ```
128-
*
140+
A basic button component that should render nicely on any platform. Supports a
141+
minimal level of customization.
142+
143+
If this button doesn't look right for your app, you can build your own button
144+
using [TouchableOpacity](touchableopacity) or
145+
[TouchableWithoutFeedback](touchablewithoutfeedback). For inspiration, look at
146+
the [source code for this button component][button:source]. Or, take a look at
147+
the [wide variety of button components built by the community]
148+
[button:examples].
149+
150+
[button:source]:
151+
https://github.com/facebook/react-native/blob/master/Libraries/Components/Button.js
152+
153+
[button:examples]:
154+
https://js.coach/?menu%5Bcollections%5D=React%20Native&page=1&query=button
155+
156+
```jsx
157+
<Button
158+
onPress={onPressLearnMore}
159+
title="Learn More"
160+
color="#841584"
161+
accessibilityLabel="Learn more about this purple button"
162+
/>
163+
```
164+
165+
```SnackPlayer name=Button%20Example
166+
import React from 'react';
167+
import { StyleSheet, Button, View, SafeAreaView, Text, Alert } from 'react-native';
168+
169+
const Separator = () => (
170+
<View style={styles.separator} />
171+
);
172+
173+
const App = () => (
174+
<SafeAreaView style={styles.container}>
175+
<View>
176+
<Text style={styles.title}>
177+
The title and onPress handler are required. It is recommended to set accessibilityLabel to help make your app usable by everyone.
178+
</Text>
179+
<Button
180+
title="Press me"
181+
onPress={() => Alert.alert('Simple Button pressed')}
182+
/>
183+
</View>
184+
<Separator />
185+
<View>
186+
<Text style={styles.title}>
187+
Adjust the color in a way that looks standard on each platform. On iOS, the color prop controls the color of the text. On Android, the color adjusts the background color of the button.
188+
</Text>
189+
<Button
190+
title="Press me"
191+
color="#f194ff"
192+
onPress={() => Alert.alert('Button with adjusted color pressed')}
193+
/>
194+
</View>
195+
<Separator />
196+
<View>
197+
<Text style={styles.title}>
198+
All interaction for the component are disabled.
199+
</Text>
200+
<Button
201+
title="Press me"
202+
disabled
203+
onPress={() => Alert.alert('Cannot press this one')}
204+
/>
205+
</View>
206+
<Separator />
207+
<View>
208+
<Text style={styles.title}>
209+
This layout strategy lets the title define the width of the button.
210+
</Text>
211+
<View style={styles.fixToText}>
212+
<Button
213+
title="Left button"
214+
onPress={() => Alert.alert('Left button pressed')}
215+
/>
216+
<Button
217+
title="Right button"
218+
onPress={() => Alert.alert('Right button pressed')}
219+
/>
220+
</View>
221+
</View>
222+
</SafeAreaView>
223+
);
224+
225+
const styles = StyleSheet.create({
226+
container: {
227+
flex: 1,
228+
justifyContent: 'center',
229+
marginHorizontal: 16,
230+
},
231+
title: {
232+
textAlign: 'center',
233+
marginVertical: 8,
234+
},
235+
fixToText: {
236+
flexDirection: 'row',
237+
justifyContent: 'space-between',
238+
},
239+
separator: {
240+
marginVertical: 8,
241+
borderBottomColor: '#737373',
242+
borderBottomWidth: StyleSheet.hairlineWidth,
243+
},
244+
});
245+
246+
export default App;
247+
```
129248
*/
130249

131250
class Button extends React.Component<ButtonProps> {

0 commit comments

Comments
 (0)