diff --git a/Libraries/StyleSheet/StyleSheet.js b/Libraries/StyleSheet/StyleSheet.js index 5b75649db..95000b4ca 100644 --- a/Libraries/StyleSheet/StyleSheet.js +++ b/Libraries/StyleSheet/StyleSheet.js @@ -86,6 +86,45 @@ module.exports = { */ hairlineWidth, + /** + * Flattens an array of style objects, into one aggregated style object. + * Alternatively, this method can be used to lookup IDs, returned by + * StyleSheet.register. + * + * > **NOTE**: Exercise caution as abusing this can tax you in terms of + * > optimizations. + * > + * > IDs enable optimizations through the bridge and memory in general. Refering + * > to style objects directly will deprive you of these optimizations. + * + * Example: + * ``` + * var styles = StyleSheet.create({ + * listItem: { + * flex: 1, + * fontSize: 16, + * color: 'white' + * }, + * selectedListItem: { + * color: 'green' + * } + * }); + * + * StyleSheet.flatten([styles.listItem, styles.selectedListItem] + * // returns { flex: 1, fontSize: 16, color: 'green' } + * ``` + * Alternative use: + * ``` + * StyleSheet.flatten(styles.listItem); + * // return { flex: 1, fontSize: 16, color: 'white' } + * // Simply styles.listItem would return its ID (number) + * ``` + * This method internally uses `StyleSheetRegistry.getStyleByID(style)` + * to resolve style objects represented by IDs. Thus, an array of style + * objects (instances of StyleSheet.create), are individually resolved to, + * their respective objects, merged as one and then returned. This also explains + * the alternative use. + */ flatten, /**