From aca701eea9cd5ae89066f0f483edddcc6dba7995 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 5 Feb 2020 19:57:23 +0000 Subject: [PATCH 01/14] Add experimental script to sync API docs from code --- .gitignore | 1 + website/package.json | 6 +- .../scripts/sync-api-docs/generateMarkdown.js | 146 ++++++++++++++++++ website/scripts/sync-api-docs/magic.js | 25 +++ website/scripts/sync-api-docs/platforms.js | 22 +++ .../preprocessGeneratedApiDocs.js | 52 +++++++ .../scripts/sync-api-docs/sync-api-docs.js | 78 ++++++++++ website/scripts/sync-api-docs/titleToId.js | 12 ++ website/yarn.lock | 34 ++++ 9 files changed, 375 insertions(+), 1 deletion(-) create mode 100644 website/scripts/sync-api-docs/generateMarkdown.js create mode 100644 website/scripts/sync-api-docs/magic.js create mode 100644 website/scripts/sync-api-docs/platforms.js create mode 100644 website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js create mode 100644 website/scripts/sync-api-docs/sync-api-docs.js create mode 100644 website/scripts/sync-api-docs/titleToId.js diff --git a/.gitignore b/.gitignore index 659430d31dd..a15db39de1a 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ website/i18n/* !website/i18n/en.json .nvmrc +website/scripts/sync-api-docs/generatedComponentApiDocs.js diff --git a/website/package.json b/website/package.json index 858891ba457..1901063d870 100644 --- a/website/package.json +++ b/website/package.json @@ -44,14 +44,18 @@ "remarkable": "^2.0.0" }, "devDependencies": { + "comment-parser": "^0.7.2", "front-matter": "^2.3.0", "fs-extra": "^5.0.0", "glob": "^7.1.2", "glob-promise": "^3.3.0", + "he": "^1.2.0", "husky": "^1.3.1", "node-fetch": "^2.3.0", "path": "^0.12.7", "prettier": "1.16.4", - "pretty-quick": "^1.10.0" + "pretty-quick": "^1.10.0", + "react-docgen-markdown-renderer": "^2.1.3", + "tokenize-comment": "^3.0.1" } } diff --git a/website/scripts/sync-api-docs/generateMarkdown.js b/website/scripts/sync-api-docs/generateMarkdown.js new file mode 100644 index 00000000000..2066e132951 --- /dev/null +++ b/website/scripts/sync-api-docs/generateMarkdown.js @@ -0,0 +1,146 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const he = require('he'); +const magic = require('./magic'); +const {formatPlatformName} = require('./platforms'); + +// Formats an array of rows as a Markdown table +function generateTable(rows) { + const colWidths = new Map(); + for (const row of rows) { + for (const col of Object.keys(row)) { + colWidths.set( + col, + Math.max(colWidths.get(col) || col.length, String(row[col]).length) + ); + } + } + let header = '|', + divider = '|'; + for (const [col, width] of colWidths) { + header += ' ' + col.padEnd(width + 1) + '|'; + divider += ' ' + '-'.repeat(width) + ' ' + '|'; + } + + let result = header + '\n' + divider + '\n'; + for (const row of rows) { + result += '|'; + for (const [col, width] of colWidths) { + result += ' ' + String(row[col] || '').padEnd(width + 1) + '|'; + } + result += '\n'; + } + return result; +} + +// Wraps a string in an inline code block in a way that is safe to include in a +// table cell, by wrapping it as HTML if necessary. +function stringToInlineCodeForTable(str) { + let useHtml = /[`|]/.test(str); + str = str.replace(/\n/g, ' '); + if (useHtml) { + return '' + he.encode(str).replace(/\|/g, '|') + ''; + } + return '`' + str + '`'; +} + +// Formats information about a prop +function generateProp(propName, prop) { + const infoTable = generateTable([ + { + Type: prop.flowType ? maybeLinkifyType(prop.flowType) : '', + Required: prop.required ? 'Yes' : 'No', + ...(prop.rnTags && prop.rnTags.platform + ? {Platform: formatPlatformName(prop.rnTags.platform)} + : {}), + }, + ]); + + return ( + '### `' + + propName + + '`' + + '\n' + + '\n' + + (prop.description ? prop.description + '\n\n' : '') + + infoTable + ); +} + +function maybeLinkifyType(flowType) { + let url, text; + if (Object.hasOwnProperty.call(magic.linkableTypeAliases, flowType.name)) { + ({url, text} = magic.linkableTypeAliases[flowType.name]); + } + if (!text) { + text = stringToInlineCodeForTable(flowType.raw || flowType.name); + } + if (url) { + return `[${text}](${url})`; + } + return text; +} + +function maybeLinkifyTypeName(name) { + let url, text; + if (Object.hasOwnProperty.call(magic.linkableTypeAliases, name)) { + ({url, text} = magic.linkableTypeAliases[name]); + } + if (!text) { + text = stringToInlineCodeForTable(name); + } + if (url) { + return `[${text}](${url})`; + } + return text; +} + +// Formats information about props +function generateProps({props, composes}) { + const title = 'Props'; + + return ( + '## ' + + title + + '\n' + + '\n' + + (composes && composes.length + ? composes + .map(parent => 'Inherits ' + maybeLinkifyTypeName(parent) + '.') + .join('\n\n') + '\n\n' + : '') + + Object.keys(props) + .sort() + .map(function(propName) { + return generateProp(propName, props[propName]); + }) + .join('\n---\n\n') + ); +} + +// Generates a Docusaurus header for a component page +function generateHeader({id, title}) { + return ( + '---' + '\n' + 'id: ' + id + '\n' + 'title: ' + title + '\n' + '---' + '\n' + ); +} + +function generateMarkdown({id, title}, reactAPI) { + const markdownString = + generateHeader({id, title}) + + '\n' + + reactAPI.description + + '\n\n' + + '---\n\n' + + '# Reference\n\n' + + generateProps(reactAPI); + + return markdownString; +} + +module.exports = generateMarkdown; diff --git a/website/scripts/sync-api-docs/magic.js b/website/scripts/sync-api-docs/magic.js new file mode 100644 index 00000000000..fb0d0694be5 --- /dev/null +++ b/website/scripts/sync-api-docs/magic.js @@ -0,0 +1,25 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +// Hard-coded knowledge about the React Native codebase and how to document it, +// beyond what is explicitly encoded in the react-docgen artifact +// (generatedComponentApiDocs.js) + +// Ideally this file should go away. + +module.exports = { + linkableTypeAliases: { + ColorValue: { + text: 'color', + url: 'colors.md', + }, + ViewProps: { + text: 'View Props', + url: 'view.md#props', + }, + }, +}; diff --git a/website/scripts/sync-api-docs/platforms.js b/website/scripts/sync-api-docs/platforms.js new file mode 100644 index 00000000000..462ef947b45 --- /dev/null +++ b/website/scripts/sync-api-docs/platforms.js @@ -0,0 +1,22 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +'use strict'; + +function formatPlatformName(platform) { + switch (platform.toLowerCase()) { + case 'ios': + return 'iOS'; + case 'android': + return 'Android'; + } + return platform; +} + +module.exports = { + formatPlatformName, +}; diff --git a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js new file mode 100644 index 00000000000..ceee91f0e38 --- /dev/null +++ b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js @@ -0,0 +1,52 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +'use strict'; + +// Preprocess the react-docgen artifact before rendering it to Markdown. +// This file may end up in the React Native repo, as part of the +// `generate-api-docs` script. + +const parseDocComment = require('comment-parser'); +const tokenizeComment = require('tokenize-comment'); + +function joinDescriptionAndExamples(tokenized) { + let sections = []; + if (tokenized.description) { + sections.push(tokenized.description); + } + for (const {raw} of tokenized.examples) { + sections.push(raw); + } + if (tokenized.footer) { + sections.push(tokenized.footer); + } + return sections.join('\n\n'); +} + +// NOTE: This function mutates `docs`. +function preprocessGeneratedApiDocs(docs) { + for (const doc of docs) { + if (doc.props) { + for (const [key, prop] of Object.entries(doc.props)) { + if (prop.description) { + const descriptionTokenized = tokenizeComment(prop.description); + prop.description = joinDescriptionAndExamples(descriptionTokenized); + prop.rnTags = {}; + const platformTag = descriptionTokenized.tags.find( + ({key}) => key === 'platform' + ); + if (platformTag) { + prop.rnTags.platform = platformTag.value; + } + } + } + } + } +} + +module.exports = preprocessGeneratedApiDocs; diff --git a/website/scripts/sync-api-docs/sync-api-docs.js b/website/scripts/sync-api-docs/sync-api-docs.js new file mode 100644 index 00000000000..f29c5809b9b --- /dev/null +++ b/website/scripts/sync-api-docs/sync-api-docs.js @@ -0,0 +1,78 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +// ***** EXPERIMENTAL ***** +// Updates the API docs from the React Native source code. + +'use strict'; + +const process = require('process'); +const fetch = require('node-fetch'); +const fs = require('fs-extra'); +const path = require('path'); + +const preprocessGeneratedApiDocs = require('./preprocessGeneratedApiDocs'); +const generateMarkdown = require('./generateMarkdown'); +const titleToId = require('./titleToId'); + +const DOCS_ROOT_DIR = path.resolve(__dirname, '..', '..', '..', 'docs'); + +const API_DOCS_ARTIFACT_URL = + 'https://raw.githubusercontent.com/facebook/react-native/master/docs/generatedComponentApiDocs.js'; +const API_DOCS_ARTIFACT_LOCAL_PATH = path.join( + __dirname, + 'generatedComponentApiDocs.js' +); + +async function downloadApiDocs(urlOrPath) { + if (await fs.exists(urlOrPath)) { + await fs.copyFile(urlOrPath, API_DOCS_ARTIFACT_LOCAL_PATH); + return; + } + const res = await fetch(API_DOCS_ARTIFACT_URL); + if (!res.ok) { + throw new Error(res.statusText); + } + const apiDocsJs = await res.text(); + await fs.writeFile(API_DOCS_ARTIFACT_LOCAL_PATH, apiDocsJs, 'utf8'); +} + +async function generateApiDocs() { + const apiDocs = require(API_DOCS_ARTIFACT_LOCAL_PATH); + preprocessGeneratedApiDocs(apiDocs); + await Promise.all( + apiDocs.map(async (page, pageIndex) => { + if (!page.displayName) { + console.log( + 'react-docgen data at index ' + + pageIndex + + ' was malformed, skipping.' + ); + return; + } + const id = titleToId(page.displayName); + const pageMarkdown = generateMarkdown( + {title: page.displayName, id: id}, + page + ); + const outFile = path.join(DOCS_ROOT_DIR, id + '.md'); + console.log('Generated ' + outFile); + await fs.writeFile(outFile, pageMarkdown, 'utf8'); + }) + ); +} + +async function syncApiDocs(urlOrPath) { + await downloadApiDocs(urlOrPath || API_DOCS_ARTIFACT_URL); + await generateApiDocs(); +} + +async function main(args) { + await syncApiDocs(args[0]); +} + +main(process.argv.slice(2)); diff --git a/website/scripts/sync-api-docs/titleToId.js b/website/scripts/sync-api-docs/titleToId.js new file mode 100644 index 00000000000..254bc16e335 --- /dev/null +++ b/website/scripts/sync-api-docs/titleToId.js @@ -0,0 +1,12 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +function titleToId(title) { + return title.toLowerCase().replace(/[^a-z]+/g, '-'); +} + +module.exports = titleToId; diff --git a/website/yarn.lock b/website/yarn.lock index fa1392fc890..0c4f2178b0a 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -1749,6 +1749,11 @@ commander@~2.8.1: dependencies: graceful-readlink ">= 1.0.0" +comment-parser@^0.7.2: + version "0.7.2" + resolved "https://registry.npmjs.org/comment-parser/-/comment-parser-0.7.2.tgz#baf6d99b42038678b81096f15b630d18142f4b8a" + integrity sha512-4Rjb1FnxtOcv9qsfuaNuVsmmVn4ooVoBHzYfyKteiXwIU84PClyGA5jASoFMwPV93+FPh9spwueXauxFJZkGAg== + commondir@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/commondir/-/commondir-1.0.1.tgz#ddd800da0c66127393cca5950ea968a3aaf1253b" @@ -3621,6 +3626,11 @@ hastscript@^5.0.0: property-information "^5.0.1" space-separated-tokens "^1.0.0" +he@^1.2.0: + version "1.2.0" + resolved "https://registry.npmjs.org/he/-/he-1.2.0.tgz#84ae65fa7eafb165fddb61566ae14baf05664f0f" + integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw== + hex-color-regex@^1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/hex-color-regex/-/hex-color-regex-1.1.0.tgz#4c06fccb4602fe2602b3c93df82d7e7dbf1a8a8e" @@ -6314,6 +6324,18 @@ react-dev-utils@^9.1.0: strip-ansi "5.2.0" text-table "0.2.0" +react-docgen-markdown-renderer@^2.1.3: + version "2.1.3" + resolved "https://registry.npmjs.org/react-docgen-markdown-renderer/-/react-docgen-markdown-renderer-2.1.3.tgz#b9278c0a288e46bf682cc53b6a4e5464789600d0" + integrity sha512-583Phg6Pep09XwklAVEf/+v4XrohYfjFMHA5XXmT2Bm+Xao+46ECkJl3pJb+K0GZN5oaxZcGis2cgQpaKqmd2A== + dependencies: + react-docgen-renderer-template "^0.1.0" + +react-docgen-renderer-template@^0.1.0: + version "0.1.0" + resolved "https://registry.npmjs.org/react-docgen-renderer-template/-/react-docgen-renderer-template-0.1.0.tgz#29340c947ab42b0060aa8e1c64e379a822e2733e" + integrity sha512-3GyuFI9pBf3E2lW6oX6j3DvTQv55Wc9pWNKwDVcUFf8kDfpDyWmTeAYWPxoSEhSZxhEP+LV/1Tr4DLwE4CULQQ== + react-dom@^16.8.4: version "16.12.0" resolved "https://registry.yarnpkg.com/react-dom/-/react-dom-16.12.0.tgz#0da4b714b8d13c2038c9396b54a92baea633fe11" @@ -6988,6 +7010,11 @@ sliced@^1.0.1: resolved "https://registry.yarnpkg.com/sliced/-/sliced-1.0.1.tgz#0b3a662b5d04c3177b1926bea82b03f837a2ef41" integrity sha1-CzpmK10Ewxd7GSa+qCsD+Dei70E= +snapdragon-lexer@^4.0.0: + version "4.0.0" + resolved "https://registry.npmjs.org/snapdragon-lexer/-/snapdragon-lexer-4.0.0.tgz#86e2fb96931e12060839000995b00d3551658292" + integrity sha512-ddXT9cpKI0PUrs3xeoQVKEjequr0UyW9w281dzu8RTgWtqdIGZSvoWDsnIMPCc8Fupk4dByatSodhwYEGgrdSg== + snapdragon-node@^2.0.1: version "2.1.1" resolved "https://registry.yarnpkg.com/snapdragon-node/-/snapdragon-node-2.1.1.tgz#6c175f86ff14bdb0724563e8f3c1b021a286853b" @@ -7586,6 +7613,13 @@ toidentifier@1.0.0: resolved "https://registry.yarnpkg.com/toidentifier/-/toidentifier-1.0.0.tgz#7e1be3470f1e77948bc43d94a3c8f4d7752ba553" integrity sha512-yaOH/Pk/VEhBWWTlhI+qXxDFXlejDGcQipMlyxda9nthulaxLZUNcUqFxokp0vcYnvteJln5FNQDRrxj3YcbVw== +tokenize-comment@^3.0.1: + version "3.0.1" + resolved "https://registry.npmjs.org/tokenize-comment/-/tokenize-comment-3.0.1.tgz#deeffcd57714e6097182a39e032e4ff861c60a1a" + integrity sha512-of5j9zCooBZxcE1EQ9PCjXcuFUPU/h8GxhWqF86cQ3muHQQreIWgY40ZNfuPQUSXyTa6i7oAWqWX4QivzZh26Q== + dependencies: + snapdragon-lexer "^4.0.0" + toml@^2.3.2: version "2.3.6" resolved "https://registry.yarnpkg.com/toml/-/toml-2.3.6.tgz#25b0866483a9722474895559088b436fd11f861b" From e221ea0ef7057dd8a2d96613c189cf80f88bfd40 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Thu, 6 Feb 2020 13:04:26 +0000 Subject: [PATCH 02/14] sync-api-docs: Support methods --- .../scripts/sync-api-docs/generateMarkdown.js | 58 +++++++++++++++++-- .../preprocessGeneratedApiDocs.js | 31 ++++++---- 2 files changed, 72 insertions(+), 17 deletions(-) diff --git a/website/scripts/sync-api-docs/generateMarkdown.js b/website/scripts/sync-api-docs/generateMarkdown.js index 2066e132951..8715648a64e 100644 --- a/website/scripts/sync-api-docs/generateMarkdown.js +++ b/website/scripts/sync-api-docs/generateMarkdown.js @@ -20,6 +20,9 @@ function generateTable(rows) { ); } } + if (!colWidths.size) { + return ''; + } let header = '|', divider = '|'; for (const [col, width] of colWidths) { @@ -72,6 +75,27 @@ function generateProp(propName, prop) { ); } +// Formats information about a prop +function generateMethod(method) { + const infoTable = generateTable([ + { + ...(method.rnTags && method.rnTags.platform + ? {Platform: formatPlatformName(method.rnTags.platform)} + : {}), + }, + ]); + + return ( + '### `' + + method.name + + '`' + + '\n' + + '\n' + + (method.description ? method.description + '\n\n' : '') + + infoTable + ).trim(); +} + function maybeLinkifyType(flowType) { let url, text; if (Object.hasOwnProperty.call(magic.linkableTypeAliases, flowType.name)) { @@ -102,11 +126,12 @@ function maybeLinkifyTypeName(name) { // Formats information about props function generateProps({props, composes}) { - const title = 'Props'; + if (!props || !Object.keys(props).length) { + return ''; + } return ( - '## ' + - title + + '## Props' + '\n' + '\n' + (composes && composes.length @@ -119,7 +144,29 @@ function generateProps({props, composes}) { .map(function(propName) { return generateProp(propName, props[propName]); }) - .join('\n---\n\n') + .join('\n\n---\n\n') + ); +} + +function generateMethods({methods}) { + if (!methods || !methods.length) { + return ''; + } + + return ( + '## Methods' + + '\n' + + '\n' + + [...methods] + .sort((a, b) => + a.name.localeCompare( + b.name /* TODO @nocommit what's a neutral locale */ + ) + ) + .map(function(method) { + return generateMethod(method); + }) + .join('\n\n---\n\n') ); } @@ -138,7 +185,8 @@ function generateMarkdown({id, title}, reactAPI) { '\n\n' + '---\n\n' + '# Reference\n\n' + - generateProps(reactAPI); + generateProps(reactAPI) + + generateMethods(reactAPI); return markdownString; } diff --git a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js index ceee91f0e38..2442489f608 100644 --- a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js +++ b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js @@ -28,22 +28,29 @@ function joinDescriptionAndExamples(tokenized) { return sections.join('\n\n'); } +function preprocessTagsInDescription(obj) { + if (obj && obj.description) { + const descriptionTokenized = tokenizeComment(obj.description); + obj.description = joinDescriptionAndExamples(descriptionTokenized); + obj.rnTags = {}; + const platformTag = descriptionTokenized.tags.find( + ({key}) => key === 'platform' + ); + if (platformTag) { + obj.rnTags.platform = platformTag.value; + } + } +} + // NOTE: This function mutates `docs`. function preprocessGeneratedApiDocs(docs) { for (const doc of docs) { if (doc.props) { - for (const [key, prop] of Object.entries(doc.props)) { - if (prop.description) { - const descriptionTokenized = tokenizeComment(prop.description); - prop.description = joinDescriptionAndExamples(descriptionTokenized); - prop.rnTags = {}; - const platformTag = descriptionTokenized.tags.find( - ({key}) => key === 'platform' - ); - if (platformTag) { - prop.rnTags.platform = platformTag.value; - } - } + for (const prop of Object.values(doc.props)) { + preprocessTagsInDescription(prop); + } + for (const prop of doc.methods) { + preprocessTagsInDescription(prop); } } } From 694dfd9c45adc6426d806de0426fd4b2b87c2c8c Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Thu, 6 Feb 2020 15:35:49 +0000 Subject: [PATCH 03/14] [remove before merging] Sync some API docs --- docs/activityindicator.md | 58 +++++-------- docs/button.md | 126 ++++++++++++++-------------- docs/drawerlayoutandroid.md | 161 ++++++++++++++++++++++-------------- docs/switch.md | 67 ++++++--------- 4 files changed, 211 insertions(+), 201 deletions(-) diff --git a/docs/activityindicator.md b/docs/activityindicator.md index 816c95fcad8..97c9d25e169 100644 --- a/docs/activityindicator.md +++ b/docs/activityindicator.md @@ -3,30 +3,6 @@ id: activityindicator title: ActivityIndicator --- -Displays a circular loading indicator. - -### Example - -```SnackPlayer name=ActivityIndicator -import React from 'react'; -import { ActivityIndicator, StyleSheet, View } from 'react-native'; - -export default App = () => ( - - - - -); - -const styles = StyleSheet.create({ - container: { - flex: 1, - flexDirection: 'row', - justifyContent: 'space-around' - } -}); -``` - --- # Reference @@ -39,19 +15,23 @@ Inherits [View Props](view.md#props). Whether to show the indicator (true, the default) or hide it (false). -| Type | Required | -| ---- | -------- | -| bool | No | +See http://facebook.github.io/react-native/docs/activityindicator.html#animating + +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- ### `color` -The foreground color of the spinner (default is gray on iOS and dark cyan on Android). +The foreground color of the spinner (default is gray). + +See http://facebook.github.io/react-native/docs/activityindicator.html#color -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| -------- | -------- | +| `string` | No | --- @@ -59,9 +39,11 @@ The foreground color of the spinner (default is gray on iOS and dark cyan on And Whether the indicator should hide when not animating (true by default). -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +See http://facebook.github.io/react-native/docs/activityindicator.html#hideswhenstopped + +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- @@ -69,6 +51,8 @@ Whether the indicator should hide when not animating (true by default). Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android. -| Type | Required | -| ------------------------------ | -------- | -| enum('small', 'large'), number | No | +See http://facebook.github.io/react-native/docs/activityindicator.html#size + +| Type | Required | +| --------------------------------------------------------------------- | -------- | +| number | 'small' | 'large' | No | diff --git a/docs/button.md b/docs/button.md index cdfdf33e302..7c8e4d6e830 100644 --- a/docs/button.md +++ b/docs/button.md @@ -110,128 +110,130 @@ const styles = StyleSheet.create({ ## Props -### `onPress` +### `accessibilityLabel` -Handler to be called when the user taps the button +Text to display for blindness accessibility features | Type | Required | | -------- | -------- | -| function | Yes | +| `string` | No | --- -### `title` +### `color` -Text to display inside the button +Color of the text (iOS), or background color of the button (Android) -| Type | Required | -| ------ | -------- | -| string | Yes | +| Type | Required | +| -------- | -------- | +| `string` | No | --- -### `accessibilityLabel` +### `disabled` -Text to display for blindness accessibility features +If true, disable all interactions for this component. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- -### `color` +### `hasTVPreferredFocus` -Color of the text (iOS), or background color of the button (Android) +TV preferred focus (see documentation for the View component). -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- -### `disabled` +### `nextFocusDown` -If true, disable all interactions for this component. +TV next focus down (see documentation for the View component). -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | --- -### `testID` +### `nextFocusForward` -Used to locate this view in end-to-end tests. +TV next focus forward (see documentation for the View component). -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | --- -### `hasTVPreferredFocus` +### `nextFocusLeft` -_(Apple TV only)_ TV preferred focus (see documentation for the View component). +TV next focus left (see documentation for the View component). -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | -### `nextFocusDown` +--- -Designates the next view to receive focus when the user navigates down. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown). +### `nextFocusRight` -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +TV next focus right (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | --- -### `nextFocusForward` +### `nextFocusUp` -Designates the next view to receive focus when the user navigates forward. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward). +TV next focus up (see documentation for the View component). -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | --- -### `nextFocusLeft` +### `onPress` -Designates the next view to receive focus when the user navigates left. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft). +Handler to be called when the user taps the button -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | +| ------------------------------- | -------- | +| `(event?: PressEvent) => mixed` | Yes | --- -### `nextFocusRight` +### `testID` -Designates the next view to receive focus when the user navigates right. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight). +Used to locate this view in end-to-end tests. -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | +| -------- | -------- | +| `string` | No | --- -### `nextFocusUp` +### `title` -Designates the next view to receive focus when the user navigates up. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp). +Text to display inside the button -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | +| -------- | -------- | +| `string` | Yes | --- ### `touchSoundDisabled` -If true, doesn't play system sound on touch. +If true, doesn't play system sound on touch (Android Only) -| Type | Required | Platform | -| ------- | -------- | -------- | -| boolean | No | Android | +| Type | Required | +| --------- | -------- | +| `boolean` | No | diff --git a/docs/drawerlayoutandroid.md b/docs/drawerlayoutandroid.md index 84733ebd9ef..25a1b7ed5e2 100644 --- a/docs/drawerlayoutandroid.md +++ b/docs/drawerlayoutandroid.md @@ -7,7 +7,7 @@ React component that wraps the platform `DrawerLayout` (Android only). The Drawe Example: -```jsx +``` render: function() { var navigationView = ( @@ -17,7 +17,7 @@ render: function() { return ( navigationView}> Hello @@ -34,25 +34,42 @@ render: function() { ## Props -Inherits [View Props](view.md#props). +### `children` -### `renderNavigationView` +| Type | Required | +| ------------ | -------- | +| `React.Node` | No | -The navigation view that will be rendered to the side of the screen and can be pulled in. +--- -| Type | Required | -| -------- | -------- | -| function | Yes | +### `drawerBackgroundColor` + +Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example: + +``` +return ( + + +); +``` + +| Type | Required | +| ------------------ | -------- | +| [color](colors.md) | No | --- -### `onDrawerClose` +### `drawerLockMode` -Function called whenever the navigation view has been closed. +Specifies the lock mode of the drawer. The drawer can be locked in 3 states: -| Type | Required | -| -------- | -------- | -| function | No | +- unlocked (default), meaning that the drawer will respond (open/close) to touch gestures. +- locked-closed, meaning that the drawer will stay closed and not respond to gestures. +- locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (`openDrawer`/`closeDrawer`). + +| Type | Required | +| ------------------------------------------------------------------------------------------------- | -------- | +| 'unlocked' | 'locked-closed' | 'locked-open' | No | --- @@ -60,9 +77,9 @@ Function called whenever the navigation view has been closed. Specifies the side of the screen from which the drawer will slide in. -| Type | Required | -| ------------------------------------------------------------------------- | -------- | -| enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right) | No | +| Type | Required | +| ------------------------------------------------------ | -------- | +| 'left' | 'right' | Yes | --- @@ -70,9 +87,9 @@ Specifies the side of the screen from which the drawer will slide in. Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window. -| Type | Required | -| ------ | -------- | -| number | No | +| Type | Required | +| -------- | -------- | +| `number` | No | --- @@ -83,23 +100,19 @@ Determines whether the keyboard gets dismissed in response to a drag. - 'none' (the default), drags do not dismiss the keyboard. - 'on-drag', the keyboard is dismissed when a drag begins. -| Type | Required | -| ----------------------- | -------- | -| enum('none', 'on-drag') | No | +| Type | Required | +| -------------------------------------------------------- | -------- | +| 'none' | 'on-drag' | No | --- -### `drawerLockMode` - -Specifies the lock mode of the drawer. The drawer can be locked in 3 states: +### `onDrawerClose` -- unlocked (default), meaning that the drawer will respond (open/close) to touch gestures. -- locked-closed, meaning that the drawer will stay closed and not respond to gestures. -- locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (`openDrawer`/`closeDrawer`). +Function called whenever the navigation view has been closed. -| Type | Required | -| ------------------------------------------------ | -------- | -| enum('unlocked', 'locked-closed', 'locked-open') | No | +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | --- @@ -107,9 +120,9 @@ Specifies the lock mode of the drawer. The drawer can be locked in 3 states: Function called whenever the navigation view has been opened. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | --- @@ -117,9 +130,9 @@ Function called whenever the navigation view has been opened. Function called whenever there is an interaction with the navigation view. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| -------------------------------------- | -------- | +| `DirectEventHandler` | No | --- @@ -127,27 +140,23 @@ Function called whenever there is an interaction with the navigation view. Function called when the drawer state has changed. The drawer can be in 3 states: -- idle, meaning there is no interaction with the navigation view happening at the time -- dragging, meaning there is currently an interaction with the navigation view -- settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation +- Idle, meaning there is no interaction with the navigation view happening at the time +- Dragging, meaning there is currently an interaction with the navigation view +- Settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| -------------------------------- | -------- | +| `(state: DrawerStates) => mixed` | No | --- -### `drawerBackgroundColor` - -Specifies the background color of the drawer. The default value is `white`. If you want to set the opacity of the drawer, use rgba. Example: +### `renderNavigationView` -```jsx -return ; -``` +The navigation view that will be rendered to the side of the screen and can be pulled in. -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| -------------------------- | -------- | +| `() => React.Element` | Yes | --- @@ -159,22 +168,52 @@ Make the drawer take the entire screen and draw the background of the status bar | ------------------ | -------- | | [color](colors.md) | No | +--- + +### `style` + +| Type | Required | +| --------------- | -------- | +| `ViewStyleProp` | No | + ## Methods -### `openDrawer()` +### `blur` -```jsx -openDrawer(); -``` +Native methods + +--- + +### `closeDrawer` + +Closes the drawer. + +--- + +### `focus` + +--- + +### `measure` + +--- + +### `measureInWindow` + +--- + +### `measureLayout` + +--- + +### `openDrawer` Opens the drawer. --- -### `closeDrawer()` +### `positions` -```jsx -closeDrawer(); -``` +--- -Closes the drawer. +### `setNativeProps` diff --git a/docs/switch.md b/docs/switch.md index 4cf6a3419a0..5ff0d195653 100644 --- a/docs/switch.md +++ b/docs/switch.md @@ -3,29 +3,10 @@ id: switch title: Switch --- -Renders a boolean input. +A visual toggle between two mutually exclusive states. This is a controlled component that requires an `onValueChange` callback that updates the `value` prop in order for the component to reflect user actions. If the `value` prop is not updated, the component will continue to render the supplied `value` prop instead of the expected result of any user actions. -```SnackPlayer name=switch -import React, { useState } from 'react'; -import { Text, View, Switch } from 'react-native'; - -export default function App() { - const [value, setValue] = useState(false); - return ( - - { - setValue(v); - }} - /> - - ); -} -``` - --- # Reference @@ -36,11 +17,11 @@ Inherits [View Props](view.md#props). ### `disabled` -If true the user won't be able to toggle the switch. Default value is false. +Whether the switch is disabled. Defaults to false. -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- @@ -56,27 +37,31 @@ On iOS, custom color for the background. This background color can be seen eithe ### `onChange` -Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use `onValueChange` instead. +Called when the user tries to change the value of the switch. + +Receives the change event as an argument. If you want to only receive the new value, use `onValueChange` instead. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------------------------------------------------------------- | -------- | +| (event: SwitchChangeEvent) => Promise<void> | void | No | --- ### `onValueChange` -Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use `onChange`. +Called when the user tries to change the value of the switch. + +Receives the new value as an argument. If you want to instead receive an event, use `onChange`. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------------------------------------------- | -------- | +| (value: boolean) => Promise<void> | void | No | --- ### `thumbColor` -Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow. +Custom color for the switch thumb. | Type | Required | | ------------------ | -------- | @@ -88,18 +73,18 @@ Color of the foreground switch grip. If this is set on iOS, the switch grip will Custom colors for the switch track. -_iOS_: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use [`ios_backgroundColor`](switch.md#ios_backgroundColor). +NOTE: On iOS when the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use `ios_backgroundColor`. -| Type | Required | -| ------------------------------------------------------------- | -------- | -| object: {false: [color](colors.md), true: [color](colors.md)} | No | +| Type | Required | +| ------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| false?: ?ColorValue, true?: ?ColorValue, |}> | No | --- ### `value` -The value of the switch. If true the switch will be turned on. Default value is false. +Boolean value of the switch. Defaults to false. -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | +| --------- | -------- | +| `boolean` | No | From e9403083f29f03042a4cf9b126f1907644141563 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Thu, 6 Feb 2020 16:26:08 +0000 Subject: [PATCH 04/14] [remove before merging] Netlify fix --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index 1cb14009d45..c83f7a2f68c 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,4 +1,4 @@ [build] base = "website" - publish = "website/build/react-native" + publish = "build/react-native" command = "sed -i -e \"s|const baseUrl .*|const baseUrl = '/';|g\" siteConfig.js && yarn install && node netlify-reduce-versions && yarn sync-community-repos && yarn build" From b3699adf39071949bbc4eafad8e8a27b36551c64 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Tue, 11 Feb 2020 16:22:10 +0000 Subject: [PATCH 05/14] sync-api-docs: add docs extraction script --- website/package.json | 1 + .../sync-api-docs/extractDocsFromRN.js | 62 ++++++ .../preprocessGeneratedApiDocs.js | 8 +- .../scripts/sync-api-docs/sync-api-docs.js | 51 ++--- website/yarn.lock | 180 +++++++++++++++++- 5 files changed, 256 insertions(+), 46 deletions(-) create mode 100644 website/scripts/sync-api-docs/extractDocsFromRN.js diff --git a/website/package.json b/website/package.json index 1901063d870..33be7818daf 100644 --- a/website/package.json +++ b/website/package.json @@ -44,6 +44,7 @@ "remarkable": "^2.0.0" }, "devDependencies": { + "@motiz88/react-native-docgen": "^0.0.0", "comment-parser": "^0.7.2", "front-matter": "^2.3.0", "fs-extra": "^5.0.0", diff --git a/website/scripts/sync-api-docs/extractDocsFromRN.js b/website/scripts/sync-api-docs/extractDocsFromRN.js new file mode 100644 index 00000000000..bc4310dd0de --- /dev/null +++ b/website/scripts/sync-api-docs/extractDocsFromRN.js @@ -0,0 +1,62 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + * + * @format + */ + +'use strict'; + +const fs = require('fs-extra'); +const glob = require('glob'); +const path = require('path'); +const reactDocs = require('@motiz88/react-native-docgen'); + +const GENERATE_ANNOTATION = '@' + 'generate-docs'; + +module.exports = extractDocsFromRN; + +async function extractDocsFromRN(rnRoot) { + // TODO: make implementation async + + const allComponentFiles = glob.sync( + path.join(rnRoot, '/Libraries/{Components,Image,}/**/*.js'), + { + nodir: true, + } + ); + + const docs = []; + + for (const file of allComponentFiles) { + const contents = fs.readFileSync(file, {encoding: 'utf-8'}); + if (!contents.includes(GENERATE_ANNOTATION)) { + continue; + } + + console.log(file); + + const result = reactDocs.parse( + contents, + reactDocs.resolver.findExportedComponentDefinition, + reactDocs.defaultHandlers + ); + + docs.push({ + file, + component: cleanComponentResult(result), + }); + } + + // Make sure output is JSON-safe + return JSON.parse(JSON.stringify(docs)); +} + +function cleanComponentResult(component) { + return { + ...component, + methods: component.methods.filter(method => !method.name.startsWith('_')), + }; +} diff --git a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js index 2442489f608..9f13a6b05b5 100644 --- a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js +++ b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js @@ -44,12 +44,12 @@ function preprocessTagsInDescription(obj) { // NOTE: This function mutates `docs`. function preprocessGeneratedApiDocs(docs) { - for (const doc of docs) { - if (doc.props) { - for (const prop of Object.values(doc.props)) { + for (const {component} of docs) { + if (component.props) { + for (const prop of Object.values(component.props)) { preprocessTagsInDescription(prop); } - for (const prop of doc.methods) { + for (const prop of component.methods) { preprocessTagsInDescription(prop); } } diff --git a/website/scripts/sync-api-docs/sync-api-docs.js b/website/scripts/sync-api-docs/sync-api-docs.js index f29c5809b9b..ec3a4dae50c 100644 --- a/website/scripts/sync-api-docs/sync-api-docs.js +++ b/website/scripts/sync-api-docs/sync-api-docs.js @@ -11,68 +11,41 @@ 'use strict'; const process = require('process'); -const fetch = require('node-fetch'); const fs = require('fs-extra'); const path = require('path'); +const extractDocsFromRN = require('./extractDocsFromRN'); const preprocessGeneratedApiDocs = require('./preprocessGeneratedApiDocs'); const generateMarkdown = require('./generateMarkdown'); const titleToId = require('./titleToId'); const DOCS_ROOT_DIR = path.resolve(__dirname, '..', '..', '..', 'docs'); -const API_DOCS_ARTIFACT_URL = - 'https://raw.githubusercontent.com/facebook/react-native/master/docs/generatedComponentApiDocs.js'; -const API_DOCS_ARTIFACT_LOCAL_PATH = path.join( - __dirname, - 'generatedComponentApiDocs.js' -); - -async function downloadApiDocs(urlOrPath) { - if (await fs.exists(urlOrPath)) { - await fs.copyFile(urlOrPath, API_DOCS_ARTIFACT_LOCAL_PATH); - return; - } - const res = await fetch(API_DOCS_ARTIFACT_URL); - if (!res.ok) { - throw new Error(res.statusText); - } - const apiDocsJs = await res.text(); - await fs.writeFile(API_DOCS_ARTIFACT_LOCAL_PATH, apiDocsJs, 'utf8'); -} - -async function generateApiDocs() { - const apiDocs = require(API_DOCS_ARTIFACT_LOCAL_PATH); +async function generateApiDocs(rnPath) { + const apiDocs = await extractDocsFromRN(rnPath); preprocessGeneratedApiDocs(apiDocs); await Promise.all( - apiDocs.map(async (page, pageIndex) => { - if (!page.displayName) { + apiDocs.map(async ({component, file}, index) => { + if (!component.displayName) { console.log( - 'react-docgen data at index ' + - pageIndex + - ' was malformed, skipping.' + `react-docgen data for ${path.basename(file)} was malformed, skipping` ); return; } - const id = titleToId(page.displayName); - const pageMarkdown = generateMarkdown( - {title: page.displayName, id: id}, - page + const id = titleToId(component.displayName); + const componentMarkdown = generateMarkdown( + {title: component.displayName, id: id}, + component ); const outFile = path.join(DOCS_ROOT_DIR, id + '.md'); console.log('Generated ' + outFile); - await fs.writeFile(outFile, pageMarkdown, 'utf8'); + await fs.writeFile(outFile, componentMarkdown, 'utf8'); }) ); } -async function syncApiDocs(urlOrPath) { - await downloadApiDocs(urlOrPath || API_DOCS_ARTIFACT_URL); - await generateApiDocs(); -} - async function main(args) { - await syncApiDocs(args[0]); + await generateApiDocs(args[0]); } main(process.argv.slice(2)); diff --git a/website/yarn.lock b/website/yarn.lock index 0c4f2178b0a..98d8b9afff5 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -9,6 +9,13 @@ dependencies: "@babel/highlight" "^7.0.0" +"@babel/code-frame@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.8.3.tgz#33e25903d7481181534e12ec0a25f16b6fcf419e" + integrity sha512-a9gxpmdXtZEInkCSHUJDLHZVBgb1QS0jhss4cPP93EW7s+uC5bikET2twEF3KV+7rDblJcmNvTR7VJejqd2C2g== + dependencies: + "@babel/highlight" "^7.8.3" + "@babel/core@^7.7.4": version "7.7.5" resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.7.5.tgz#ae1323cd035b5160293307f50647e83f8ba62f7e" @@ -29,6 +36,27 @@ semver "^5.4.1" source-map "^0.5.0" +"@babel/core@^7.7.5": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/core/-/core-7.8.4.tgz#d496799e5c12195b3602d0fddd77294e3e38e80e" + integrity sha512-0LiLrB2PwrVI+a2/IEskBopDYSd8BCb3rOvH7D5tzoWd696TBEduBvuLVm4Nx6rltrLZqvI3MCalB2K2aVzQjA== + dependencies: + "@babel/code-frame" "^7.8.3" + "@babel/generator" "^7.8.4" + "@babel/helpers" "^7.8.4" + "@babel/parser" "^7.8.4" + "@babel/template" "^7.8.3" + "@babel/traverse" "^7.8.4" + "@babel/types" "^7.8.3" + convert-source-map "^1.7.0" + debug "^4.1.0" + gensync "^1.0.0-beta.1" + json5 "^2.1.0" + lodash "^4.17.13" + resolve "^1.3.2" + semver "^5.4.1" + source-map "^0.5.0" + "@babel/generator@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.7.4.tgz#db651e2840ca9aa66f327dcec1dc5f5fa9611369" @@ -39,6 +67,16 @@ lodash "^4.17.13" source-map "^0.5.0" +"@babel/generator@^7.8.4": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/generator/-/generator-7.8.4.tgz#35bbc74486956fe4251829f9f6c48330e8d0985e" + integrity sha512-PwhclGdRpNAf3IxZb0YVuITPZmmrXz9zf6fH8lT4XbrmfQKr6ryBzhv593P5C6poJRciFCL/eHGW2NuGrgEyxA== + dependencies: + "@babel/types" "^7.8.3" + jsesc "^2.5.1" + lodash "^4.17.13" + source-map "^0.5.0" + "@babel/helper-annotate-as-pure@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/helper-annotate-as-pure/-/helper-annotate-as-pure-7.7.4.tgz#bb3faf1e74b74bd547e867e48f551fa6b098b6ce" @@ -117,6 +155,15 @@ "@babel/template" "^7.7.4" "@babel/types" "^7.7.4" +"@babel/helper-function-name@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/helper-function-name/-/helper-function-name-7.8.3.tgz#eeeb665a01b1f11068e9fb86ad56a1cb1a824cca" + integrity sha512-BCxgX1BC2hD/oBlIFUgOCQDOPV8nSINxCwM3o93xP4P9Fq6aV5sgv2cOOITDMtCfQ+3PvHp3l689XZvAM9QyOA== + dependencies: + "@babel/helper-get-function-arity" "^7.8.3" + "@babel/template" "^7.8.3" + "@babel/types" "^7.8.3" + "@babel/helper-get-function-arity@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/helper-get-function-arity/-/helper-get-function-arity-7.7.4.tgz#cb46348d2f8808e632f0ab048172130e636005f0" @@ -124,6 +171,13 @@ dependencies: "@babel/types" "^7.7.4" +"@babel/helper-get-function-arity@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/helper-get-function-arity/-/helper-get-function-arity-7.8.3.tgz#b894b947bd004381ce63ea1db9f08547e920abd5" + integrity sha512-FVDR+Gd9iLjUMY1fzE2SR0IuaJToR4RkCDARVfsBBPSP53GEqSFjD8gNyxg246VUyc/ALRxFaAK8rVG7UT7xRA== + dependencies: + "@babel/types" "^7.8.3" + "@babel/helper-hoist-variables@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/helper-hoist-variables/-/helper-hoist-variables-7.7.4.tgz#612384e3d823fdfaaf9fce31550fe5d4db0f3d12" @@ -212,6 +266,13 @@ dependencies: "@babel/types" "^7.7.4" +"@babel/helper-split-export-declaration@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/helper-split-export-declaration/-/helper-split-export-declaration-7.8.3.tgz#31a9f30070f91368a7182cf05f831781065fc7a9" + integrity sha512-3x3yOeyBhW851hroze7ElzdkeRXQYQbFIb7gLK1WQYsw2GWDay5gAJNw1sWJ0VFP6z5J1whqeXH/WCdCjZv6dA== + dependencies: + "@babel/types" "^7.8.3" + "@babel/helper-wrap-function@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/helper-wrap-function/-/helper-wrap-function-7.7.4.tgz#37ab7fed5150e22d9d7266e830072c0cdd8baace" @@ -231,6 +292,15 @@ "@babel/traverse" "^7.7.4" "@babel/types" "^7.7.4" +"@babel/helpers@^7.8.4": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/helpers/-/helpers-7.8.4.tgz#754eb3ee727c165e0a240d6c207de7c455f36f73" + integrity sha512-VPbe7wcQ4chu4TDQjimHv/5tj73qz88o12EPkO2ValS2QiQS/1F2SsjyIGNnAD0vF/nZS6Cf9i+vW6HIlnaR8w== + dependencies: + "@babel/template" "^7.8.3" + "@babel/traverse" "^7.8.4" + "@babel/types" "^7.8.3" + "@babel/highlight@^7.0.0": version "7.5.0" resolved "https://registry.yarnpkg.com/@babel/highlight/-/highlight-7.5.0.tgz#56d11312bd9248fa619591d02472be6e8cb32540" @@ -240,11 +310,25 @@ esutils "^2.0.2" js-tokens "^4.0.0" +"@babel/highlight@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/highlight/-/highlight-7.8.3.tgz#28f173d04223eaaa59bc1d439a3836e6d1265797" + integrity sha512-PX4y5xQUvy0fnEVHrYOarRPXVWafSjTW9T0Hab8gVIawpl2Sj0ORyrygANq+KjcNlSSTw0YCLSNA8OyZ1I4yEg== + dependencies: + chalk "^2.0.0" + esutils "^2.0.2" + js-tokens "^4.0.0" + "@babel/parser@^7.7.4", "@babel/parser@^7.7.5": version "7.7.5" resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.7.5.tgz#cbf45321619ac12d83363fcf9c94bb67fa646d71" integrity sha512-KNlOe9+/nk4i29g0VXgl8PEXIRms5xKLJeuZ6UptN0fHv+jDiriG+y94X6qAgWTR0h3KaoM1wK5G5h7MHFRSig== +"@babel/parser@^7.8.3", "@babel/parser@^7.8.4": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/parser/-/parser-7.8.4.tgz#d1dbe64691d60358a974295fa53da074dd2ce8e8" + integrity sha512-0fKu/QqildpXmPVaRBoXOlyBb3MC+J0A66x97qEfLOMkn3u6nfY5esWogQwi/K0BjASYy4DbnsEWnpNL6qT5Mw== + "@babel/plugin-proposal-async-generator-functions@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/plugin-proposal-async-generator-functions/-/plugin-proposal-async-generator-functions-7.7.4.tgz#0351c5ac0a9e927845fffd5b82af476947b7ce6d" @@ -714,6 +798,13 @@ pirates "^4.0.0" source-map-support "^0.5.16" +"@babel/runtime@^7.7.6": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/runtime/-/runtime-7.8.4.tgz#d79f5a2040f7caa24d53e563aad49cbc05581308" + integrity sha512-neAp3zt80trRVBI1x0azq6c57aNBqYZH8KhMm3TaB7wEI5Q4A2SHfBHE8w9gOhI/lrqxtEbXZgQIrHP+wvSGwQ== + dependencies: + regenerator-runtime "^0.13.2" + "@babel/template@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.7.4.tgz#428a7d9eecffe27deac0a98e23bf8e3675d2a77b" @@ -723,6 +814,15 @@ "@babel/parser" "^7.7.4" "@babel/types" "^7.7.4" +"@babel/template@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/template/-/template-7.8.3.tgz#e02ad04fe262a657809327f578056ca15fd4d1b8" + integrity sha512-04m87AcQgAFdvuoyiQ2kgELr2tV8B4fP/xJAVUL3Yb3bkNdMedD3d0rlSQr3PegP0cms3eHjl1F7PWlvWbU8FQ== + dependencies: + "@babel/code-frame" "^7.8.3" + "@babel/parser" "^7.8.3" + "@babel/types" "^7.8.3" + "@babel/traverse@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.7.4.tgz#9c1e7c60fb679fe4fcfaa42500833333c2058558" @@ -738,6 +838,21 @@ globals "^11.1.0" lodash "^4.17.13" +"@babel/traverse@^7.8.4": + version "7.8.4" + resolved "https://registry.npmjs.org/@babel/traverse/-/traverse-7.8.4.tgz#f0845822365f9d5b0e312ed3959d3f827f869e3c" + integrity sha512-NGLJPZwnVEyBPLI+bl9y9aSnxMhsKz42so7ApAv9D+b4vAFPpY013FTS9LdKxcABoIYFU52HcYga1pPlx454mg== + dependencies: + "@babel/code-frame" "^7.8.3" + "@babel/generator" "^7.8.4" + "@babel/helper-function-name" "^7.8.3" + "@babel/helper-split-export-declaration" "^7.8.3" + "@babel/parser" "^7.8.4" + "@babel/types" "^7.8.3" + debug "^4.1.0" + globals "^11.1.0" + lodash "^4.17.13" + "@babel/types@^7.7.4": version "7.7.4" resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.7.4.tgz#516570d539e44ddf308c07569c258ff94fde9193" @@ -747,6 +862,29 @@ lodash "^4.17.13" to-fast-properties "^2.0.0" +"@babel/types@^7.8.3": + version "7.8.3" + resolved "https://registry.npmjs.org/@babel/types/-/types-7.8.3.tgz#5a383dffa5416db1b73dedffd311ffd0788fb31c" + integrity sha512-jBD+G8+LWpMBBWvVcdr4QysjUE4mU/syrhN17o1u3gx0/WzJB1kwiVZAXRtWbsIPOwW8pF/YJV5+nmetPzepXg== + dependencies: + esutils "^2.0.2" + lodash "^4.17.13" + to-fast-properties "^2.0.0" + +"@motiz88/react-native-docgen@^0.0.0": + version "0.0.0" + resolved "https://registry.npmjs.org/@motiz88/react-native-docgen/-/react-native-docgen-0.0.0.tgz#62b75b7e045e45150c612c8bd08e39c9cd1a530d" + integrity sha512-lL71PvgE7L8jpE+j70/s/aH14gc2AaWeK2gAGNPa+DVs3Sx6DVBk/CszkJSfdK/t7HaeaTIuYdBESj4F600kMg== + dependencies: + "@babel/core" "^7.7.5" + "@babel/runtime" "^7.7.6" + ast-types "^0.13.2" + commander "^2.19.0" + doctrine "^3.0.0" + neo-async "^2.6.1" + node-dir "^0.1.10" + strip-indent "^3.0.0" + "@mrmlnc/readdir-enhanced@^2.2.1": version "2.2.1" resolved "https://registry.yarnpkg.com/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.1.tgz#524af240d1a360527b730475ecfa1344aa540dde" @@ -1033,6 +1171,11 @@ assign-symbols@^1.0.0: resolved "https://registry.yarnpkg.com/assign-symbols/-/assign-symbols-1.0.0.tgz#59667f41fadd4f20ccbc2bb96b8d4f7f78ec0367" integrity sha1-WWZ/QfrdTyDMvCu5a41Pf3jsA2c= +ast-types@^0.13.2: + version "0.13.2" + resolved "https://registry.npmjs.org/ast-types/-/ast-types-0.13.2.tgz#df39b677a911a83f3a049644fb74fdded23cea48" + integrity sha512-uWMHxJxtfj/1oZClOxDEV1sQ1HCDkA4MG8Gr69KKeBjEVH0R84WlejZ0y2DcwyBlpAEMltmVYkVgqfLFb2oyiA== + async-each@^1.0.1: version "1.0.3" resolved "https://registry.yarnpkg.com/async-each/-/async-each-1.0.3.tgz#b727dbf87d7651602f06f4d4ac387f47d91b0cbf" @@ -1732,7 +1875,7 @@ comma-separated-tokens@^1.0.0: resolved "https://registry.yarnpkg.com/comma-separated-tokens/-/comma-separated-tokens-1.0.7.tgz#419cd7fb3258b1ed838dc0953167a25e152f5b59" integrity sha512-Jrx3xsP4pPv4AwJUDWY9wOXGtwPXARej6Xd99h4TUGotmf8APuquKMpK+dnD3UgyxK7OEWaisjZz+3b5jtL6xQ== -commander@^2.15.1, commander@~2.20.3: +commander@^2.15.1, commander@^2.19.0, commander@~2.20.3: version "2.20.3" resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33" integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ== @@ -2303,6 +2446,13 @@ dir-glob@2.0.0: arrify "^1.0.1" path-type "^3.0.0" +doctrine@^3.0.0: + version "3.0.0" + resolved "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz#addebead72a6574db783639dc87a121773973961" + integrity sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w== + dependencies: + esutils "^2.0.2" + docusaurus@1.14.4: version "1.14.4" resolved "https://registry.yarnpkg.com/docusaurus/-/docusaurus-1.14.4.tgz#1ef3ebe8c2aaaf1dec6c2e0e177e83be78aeaca3" @@ -3135,6 +3285,11 @@ gaze@^1.1.3: dependencies: globule "^1.0.0" +gensync@^1.0.0-beta.1: + version "1.0.0-beta.1" + resolved "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.1.tgz#58f4361ff987e5ff6e1e7a210827aa371eaac269" + integrity sha512-r8EC6NO1sngH/zdD9fiRDLdcgnbayXah+mLgManTaIZJqEC1MZstmnox8KpnI2/fxQwrp5OpCOYWLp4rBl4Jcg== + get-proxy@^2.0.0: version "2.1.0" resolved "https://registry.yarnpkg.com/get-proxy/-/get-proxy-2.1.0.tgz#349f2b4d91d44c4d4d4e9cba2ad90143fac5ef93" @@ -4983,7 +5138,12 @@ mimic-response@^1.0.0, mimic-response@^1.0.1: resolved "https://registry.yarnpkg.com/mimic-response/-/mimic-response-1.0.1.tgz#4923538878eef42063cb8a3e3b0798781487ab1b" integrity sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ== -minimatch@3.0.4, minimatch@^3.0.4, minimatch@~3.0.2: +min-indent@^1.0.0: + version "1.0.0" + resolved "https://registry.npmjs.org/min-indent/-/min-indent-1.0.0.tgz#cfc45c37e9ec0d8f0a0ec3dd4ef7f7c3abe39256" + integrity sha1-z8RcN+nsDY8KDsPdTvf3w6vjklY= + +minimatch@3.0.4, minimatch@^3.0.2, minimatch@^3.0.4, minimatch@~3.0.2: version "3.0.4" resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083" integrity sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA== @@ -5114,7 +5274,7 @@ negotiator@0.6.2: resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.2.tgz#feacf7ccf525a77ae9634436a64883ffeca346fb" integrity sha512-hZXc7K2e+PgeI1eDBe/10Ard4ekbfrrqG8Ep+8Jmf4JID2bNg7NvCPOZN+kfF574pFQI7mum2AUqDidoKqcTOw== -neo-async@^2.6.0: +neo-async@^2.6.0, neo-async@^2.6.1: version "2.6.1" resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.1.tgz#ac27ada66167fa8849a6addd837f6b189ad2081c" integrity sha512-iyam8fBuCUpWeKPGpaNMetEocMt364qkCsfL9JuhjXX6dRnguRVOfk2GZaDpPjcOKiiXCPINZC1GczQ7iTq3Zw== @@ -5152,6 +5312,13 @@ nlcst-to-string@^2.0.0: resolved "https://registry.yarnpkg.com/nlcst-to-string/-/nlcst-to-string-2.0.3.tgz#b7913bb1305263b0561a86de68e179f17f7febe3" integrity sha512-OY2QhGdf6jpYfHqS4vJwqF7aIBZkaMjMUkcHcskMPitvXLuYNGdQvgVWI/5yKwkmIdmhft3ounSJv+Re2yydng== +node-dir@^0.1.10: + version "0.1.17" + resolved "https://registry.npmjs.org/node-dir/-/node-dir-0.1.17.tgz#5f5665d93351335caabef8f1c554516cf5f1e4e5" + integrity sha1-X1Zl2TNRM1yqvvjxxVRRbPXx5OU= + dependencies: + minimatch "^3.0.2" + node-fetch@^2.3.0: version "2.3.0" resolved "https://registry.yarnpkg.com/node-fetch/-/node-fetch-2.3.0.tgz#1a1d940bbfb916a1d3e0219f037e89e71f8c5fa5" @@ -7375,6 +7542,13 @@ strip-indent@^2.0.0: resolved "https://registry.yarnpkg.com/strip-indent/-/strip-indent-2.0.0.tgz#5ef8db295d01e6ed6cbf7aab96998d7822527b68" integrity sha1-XvjbKV0B5u1sv3qrlpmNeCJSe2g= +strip-indent@^3.0.0: + version "3.0.0" + resolved "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz#c32e1cee940b6b3432c771bc2c54bcce73cd3001" + integrity sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ== + dependencies: + min-indent "^1.0.0" + strip-json-comments@~2.0.1: version "2.0.1" resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-2.0.1.tgz#3c531942e908c2697c0ec344858c286c7ca0a60a" From b6e57c57b8f815564409fd0113d999a31c5b3fec Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Tue, 11 Feb 2020 23:32:59 +0000 Subject: [PATCH 06/14] sync-api-docs: Improvements to method docs --- .../scripts/sync-api-docs/generateMarkdown.js | 59 ++++++++++++++++--- 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/website/scripts/sync-api-docs/generateMarkdown.js b/website/scripts/sync-api-docs/generateMarkdown.js index 8715648a64e..4b16464b307 100644 --- a/website/scripts/sync-api-docs/generateMarkdown.js +++ b/website/scripts/sync-api-docs/generateMarkdown.js @@ -76,7 +76,7 @@ function generateProp(propName, prop) { } // Formats information about a prop -function generateMethod(method) { +function generateMethod(method, component) { const infoTable = generateTable([ { ...(method.rnTags && method.rnTags.platform @@ -88,14 +88,54 @@ function generateMethod(method) { return ( '### `' + method.name + - '`' + + '()`' + '\n' + '\n' + + generateMethodSignatureBlock(method, component) + (method.description ? method.description + '\n\n' : '') + + generateMethodSignatureTable(method, component) + infoTable ).trim(); } +function lowerFirst(s) { + return s[0].toLowerCase() + s.slice(1); +} + +function generateMethodSignatureBlock(method, component) { + return ( + '```jsx\n' + + (method.modifiers.includes('static') + ? component.displayName + '.' + : lowerFirst(component.displayName + '.')) + + method.name + + '(' + + method.params + .map(param => (param.optional ? `[${param.name}]` : param.name)) + .join(', ') + + ');' + + '\n' + + '```\n\n' + ); +} + +function generateMethodSignatureTable(method, component) { + if (!method.params.length) { + return ''; + } + return ( + '**Parameters:**\n\n' + + generateTable( + method.params.map(param => ({ + Name: param.name, + Type: param.type ? maybeLinkifyType(param.type) : '', + Required: param.optional ? 'No' : 'Yes', + Description: param.description, + })) + ) + ); +} + function maybeLinkifyType(flowType) { let url, text; if (Object.hasOwnProperty.call(magic.linkableTypeAliases, flowType.name)) { @@ -148,7 +188,8 @@ function generateProps({props, composes}) { ); } -function generateMethods({methods}) { +function generateMethods(component) { + const {methods} = component; if (!methods || !methods.length) { return ''; } @@ -164,7 +205,7 @@ function generateMethods({methods}) { ) ) .map(function(method) { - return generateMethod(method); + return generateMethod(method, component); }) .join('\n\n---\n\n') ); @@ -177,18 +218,18 @@ function generateHeader({id, title}) { ); } -function generateMarkdown({id, title}, reactAPI) { +function generateMarkdown({id, title}, component) { const markdownString = generateHeader({id, title}) + '\n' + - reactAPI.description + + component.description + '\n\n' + '---\n\n' + '# Reference\n\n' + - generateProps(reactAPI) + - generateMethods(reactAPI); + generateProps(component) + + generateMethods(component); - return markdownString; + return markdownString.replace(/\n{3,}/g, '\n\n'); } module.exports = generateMarkdown; From 41fb8d2072fa59c9ff4dc1e19be20352436dd9d6 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 00:35:37 +0000 Subject: [PATCH 07/14] sync-api-docs: update docgen fork to 0.0.1 --- website/package.json | 2 +- website/yarn.lock | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/package.json b/website/package.json index 33be7818daf..3ac5a1dd6ec 100644 --- a/website/package.json +++ b/website/package.json @@ -44,7 +44,7 @@ "remarkable": "^2.0.0" }, "devDependencies": { - "@motiz88/react-native-docgen": "^0.0.0", + "@motiz88/react-native-docgen": "0.0.1", "comment-parser": "^0.7.2", "front-matter": "^2.3.0", "fs-extra": "^5.0.0", diff --git a/website/yarn.lock b/website/yarn.lock index 98d8b9afff5..1d729c330f5 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -871,10 +871,10 @@ lodash "^4.17.13" to-fast-properties "^2.0.0" -"@motiz88/react-native-docgen@^0.0.0": - version "0.0.0" - resolved "https://registry.npmjs.org/@motiz88/react-native-docgen/-/react-native-docgen-0.0.0.tgz#62b75b7e045e45150c612c8bd08e39c9cd1a530d" - integrity sha512-lL71PvgE7L8jpE+j70/s/aH14gc2AaWeK2gAGNPa+DVs3Sx6DVBk/CszkJSfdK/t7HaeaTIuYdBESj4F600kMg== +"@motiz88/react-native-docgen@0.0.1": + version "0.0.1" + resolved "https://registry.npmjs.org/@motiz88/react-native-docgen/-/react-native-docgen-0.0.1.tgz#841352fd6677b1e0ea690717ab533d65f5e5f9d6" + integrity sha512-ywgrygYfst18SZz2Aw73MJhZb6gXDrdPhJepUJShCKzA5ati4aIpLQ1QpW1GHVlZw0xqxWp/3wJIbvUgQn3t2A== dependencies: "@babel/core" "^7.7.5" "@babel/runtime" "^7.7.6" From 78a5cc4f28c02474a6915428f81fb6ee9e1cf837 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 11:35:07 +0000 Subject: [PATCH 08/14] [remove before merging] write extracted.json --- .gitignore | 1 + website/scripts/sync-api-docs/extractDocsFromRN.js | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a15db39de1a..5d4acae64f8 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ website/i18n/* .nvmrc website/scripts/sync-api-docs/generatedComponentApiDocs.js +website/scripts/sync-api-docs/extracted.json diff --git a/website/scripts/sync-api-docs/extractDocsFromRN.js b/website/scripts/sync-api-docs/extractDocsFromRN.js index bc4310dd0de..256d152f48b 100644 --- a/website/scripts/sync-api-docs/extractDocsFromRN.js +++ b/website/scripts/sync-api-docs/extractDocsFromRN.js @@ -51,7 +51,13 @@ async function extractDocsFromRN(rnRoot) { } // Make sure output is JSON-safe - return JSON.parse(JSON.stringify(docs)); + const docsSerialized = JSON.parse(JSON.stringify(docs)); + await fs.writeFile( + path.join(__dirname, 'extracted.json'), + JSON.stringify(docsSerialized, null, 2), + 'utf8' + ); + return docsSerialized; } function cleanComponentResult(component) { From b1a0425773b8d7da87292da8f122c3449921b89e Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 11:35:51 +0000 Subject: [PATCH 09/14] sync-api-docs: pass filename into react-docgen --- website/scripts/sync-api-docs/extractDocsFromRN.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/scripts/sync-api-docs/extractDocsFromRN.js b/website/scripts/sync-api-docs/extractDocsFromRN.js index 256d152f48b..2e47d9a31d2 100644 --- a/website/scripts/sync-api-docs/extractDocsFromRN.js +++ b/website/scripts/sync-api-docs/extractDocsFromRN.js @@ -25,6 +25,7 @@ async function extractDocsFromRN(rnRoot) { path.join(rnRoot, '/Libraries/{Components,Image,}/**/*.js'), { nodir: true, + absolute: true, } ); @@ -41,7 +42,8 @@ async function extractDocsFromRN(rnRoot) { const result = reactDocs.parse( contents, reactDocs.resolver.findExportedComponentDefinition, - reactDocs.defaultHandlers + reactDocs.defaultHandlers, + {filename: file} ); docs.push({ From 2943dd989f938a6a09829726ea6ec6bd4fff965d Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 11:36:25 +0000 Subject: [PATCH 10/14] sync-api-docs: don't use PropTypes composition handler We have Flow types for this. --- website/scripts/sync-api-docs/extractDocsFromRN.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/scripts/sync-api-docs/extractDocsFromRN.js b/website/scripts/sync-api-docs/extractDocsFromRN.js index 2e47d9a31d2..f55543ba44e 100644 --- a/website/scripts/sync-api-docs/extractDocsFromRN.js +++ b/website/scripts/sync-api-docs/extractDocsFromRN.js @@ -42,7 +42,9 @@ async function extractDocsFromRN(rnRoot) { const result = reactDocs.parse( contents, reactDocs.resolver.findExportedComponentDefinition, - reactDocs.defaultHandlers, + reactDocs.defaultHandlers.filter( + handler => handler !== reactDocs.handlers.propTypeCompositionHandler + ), {filename: file} ); From cad146cfc346bfcc90b3e2d38187e677b8bcf1b8 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 14:19:45 +0000 Subject: [PATCH 11/14] sync-api-docs: remove unused comment-parser --- website/package.json | 7 +++---- .../scripts/sync-api-docs/preprocessGeneratedApiDocs.js | 1 - website/yarn.lock | 5 ----- 3 files changed, 3 insertions(+), 10 deletions(-) diff --git a/website/package.json b/website/package.json index 3ac5a1dd6ec..74df4e9e81f 100644 --- a/website/package.json +++ b/website/package.json @@ -41,11 +41,11 @@ "alex": "^8.0.0", "docusaurus": "1.14.4", "highlight.js": "^9.15.10", - "remarkable": "^2.0.0" + "remarkable": "^2.0.0", + "tokenize-comment": "^3.0.1" }, "devDependencies": { "@motiz88/react-native-docgen": "0.0.1", - "comment-parser": "^0.7.2", "front-matter": "^2.3.0", "fs-extra": "^5.0.0", "glob": "^7.1.2", @@ -56,7 +56,6 @@ "path": "^0.12.7", "prettier": "1.16.4", "pretty-quick": "^1.10.0", - "react-docgen-markdown-renderer": "^2.1.3", - "tokenize-comment": "^3.0.1" + "react-docgen-markdown-renderer": "^2.1.3" } } diff --git a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js index 9f13a6b05b5..3732e45fa0e 100644 --- a/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js +++ b/website/scripts/sync-api-docs/preprocessGeneratedApiDocs.js @@ -11,7 +11,6 @@ // This file may end up in the React Native repo, as part of the // `generate-api-docs` script. -const parseDocComment = require('comment-parser'); const tokenizeComment = require('tokenize-comment'); function joinDescriptionAndExamples(tokenized) { diff --git a/website/yarn.lock b/website/yarn.lock index 1d729c330f5..fd026382478 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -1892,11 +1892,6 @@ commander@~2.8.1: dependencies: graceful-readlink ">= 1.0.0" -comment-parser@^0.7.2: - version "0.7.2" - resolved "https://registry.npmjs.org/comment-parser/-/comment-parser-0.7.2.tgz#baf6d99b42038678b81096f15b630d18142f4b8a" - integrity sha512-4Rjb1FnxtOcv9qsfuaNuVsmmVn4ooVoBHzYfyKteiXwIU84PClyGA5jASoFMwPV93+FPh9spwueXauxFJZkGAg== - commondir@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/commondir/-/commondir-1.0.1.tgz#ddd800da0c66127393cca5950ea968a3aaf1253b" From eca8238d5cf5fb21c488c743c30673c46d513832 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 14:21:52 +0000 Subject: [PATCH 12/14] sync-api-docs: bump docgen fork to 0.0.2 --- website/package.json | 2 +- website/yarn.lock | 28 ++++++++++++++++++---------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/website/package.json b/website/package.json index 74df4e9e81f..e4b81a1cf31 100644 --- a/website/package.json +++ b/website/package.json @@ -45,7 +45,7 @@ "tokenize-comment": "^3.0.1" }, "devDependencies": { - "@motiz88/react-native-docgen": "0.0.1", + "@motiz88/react-native-docgen": "0.0.2", "front-matter": "^2.3.0", "fs-extra": "^5.0.0", "glob": "^7.1.2", diff --git a/website/yarn.lock b/website/yarn.lock index fd026382478..0fa0e41e940 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -871,18 +871,24 @@ lodash "^4.17.13" to-fast-properties "^2.0.0" -"@motiz88/react-native-docgen@0.0.1": - version "0.0.1" - resolved "https://registry.npmjs.org/@motiz88/react-native-docgen/-/react-native-docgen-0.0.1.tgz#841352fd6677b1e0ea690717ab533d65f5e5f9d6" - integrity sha512-ywgrygYfst18SZz2Aw73MJhZb6gXDrdPhJepUJShCKzA5ati4aIpLQ1QpW1GHVlZw0xqxWp/3wJIbvUgQn3t2A== +"@motiz88/ast-types@^0.13.3": + version "0.13.3" + resolved "https://registry.npmjs.org/@motiz88/ast-types/-/ast-types-0.13.3.tgz#0630c411325b145a7ad5632adf8d8d40d28e07d0" + integrity sha512-OzqnfkQv2JjhRqZ0BeuJRuU6rx47LqBYeirDOUfb5C5fFFtpOh0AHTlQRifG4a5kir/OwjWW+x4HlViYxVko/Q== + +"@motiz88/react-native-docgen@0.0.2": + version "0.0.2" + resolved "https://registry.npmjs.org/@motiz88/react-native-docgen/-/react-native-docgen-0.0.2.tgz#0da1170dc601bddb28e255194b480e9dc6e7acd5" + integrity sha512-5knOlVOnHDUZRx6KCE94yGJYuevnckb+Q/+TL2mG9SEqAlDEh/4bMRyZMxcaoKOi/MIj1ZUQlbXVYoUlDAW5Tw== dependencies: "@babel/core" "^7.7.5" "@babel/runtime" "^7.7.6" - ast-types "^0.13.2" + "@motiz88/ast-types" "^0.13.3" commander "^2.19.0" doctrine "^3.0.0" neo-async "^2.6.1" node-dir "^0.1.10" + resolve "^1.10.1" strip-indent "^3.0.0" "@mrmlnc/readdir-enhanced@^2.2.1": @@ -1171,11 +1177,6 @@ assign-symbols@^1.0.0: resolved "https://registry.yarnpkg.com/assign-symbols/-/assign-symbols-1.0.0.tgz#59667f41fadd4f20ccbc2bb96b8d4f7f78ec0367" integrity sha1-WWZ/QfrdTyDMvCu5a41Pf3jsA2c= -ast-types@^0.13.2: - version "0.13.2" - resolved "https://registry.npmjs.org/ast-types/-/ast-types-0.13.2.tgz#df39b677a911a83f3a049644fb74fdded23cea48" - integrity sha512-uWMHxJxtfj/1oZClOxDEV1sQ1HCDkA4MG8Gr69KKeBjEVH0R84WlejZ0y2DcwyBlpAEMltmVYkVgqfLFb2oyiA== - async-each@^1.0.1: version "1.0.3" resolved "https://registry.yarnpkg.com/async-each/-/async-each-1.0.3.tgz#b727dbf87d7651602f06f4d4ac387f47d91b0cbf" @@ -6869,6 +6870,13 @@ resolve@^1.1.6, resolve@^1.10.0, resolve@^1.3.2: dependencies: path-parse "^1.0.6" +resolve@^1.10.1: + version "1.15.1" + resolved "https://registry.npmjs.org/resolve/-/resolve-1.15.1.tgz#27bdcdeffeaf2d6244b95bb0f9f4b4653451f3e8" + integrity sha512-84oo6ZTtoTUpjgNEr5SJyzQhzL72gaRodsSfyxC/AXRvwu0Yse9H8eF9IpGo7b8YetZhlI6v7ZQ6bKBFV/6S7w== + dependencies: + path-parse "^1.0.6" + responselike@1.0.2, responselike@^1.0.2: version "1.0.2" resolved "https://registry.yarnpkg.com/responselike/-/responselike-1.0.2.tgz#918720ef3b631c5642be068f15ade5a46f4ba1e7" From 4064bbf0652cdc66bec836fb63264d87f800e333 Mon Sep 17 00:00:00 2001 From: Moti Zilberman Date: Wed, 12 Feb 2020 14:22:48 +0000 Subject: [PATCH 13/14] [remove before merging] update Markdown files --- docs/activityindicator.md | 674 ++++++++++++++++++++++++++++++++- docs/drawerlayoutandroid.md | 104 ++++-- docs/image.md | 462 ++++++++--------------- docs/switch.md | 686 +++++++++++++++++++++++++++++++++- docs/text.md | 571 ++++++++-------------------- docs/view.md | 721 ++++++++++++++++++++---------------- 6 files changed, 2143 insertions(+), 1075 deletions(-) diff --git a/docs/activityindicator.md b/docs/activityindicator.md index 97c9d25e169..c12d5790240 100644 --- a/docs/activityindicator.md +++ b/docs/activityindicator.md @@ -9,7 +9,125 @@ title: ActivityIndicator ## Props -Inherits [View Props](view.md#props). +### `accessibilityActions` + +Provides an array of custom actions available for accessibility. + +| Type | Required | +| ----------------------------------------- | -------- | +| `$ReadOnlyArray` | No | + +--- + +### `accessibilityElementsHidden` + +A value indicating whether the accessibility elements contained within this accessibility element are hidden. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | + +--- + +### `accessibilityHint` + +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. + +See http://facebook.github.io/react-native/docs/view.html#accessibilityHint + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | + +--- + +### `accessibilityIgnoresInvertColors` + +Prevents view from being inverted if set to true and color inversion is turned on. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | iOS | + +--- + +### `accessibilityLabel` + +Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. + +See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | + +--- + +### `accessibilityLiveRegion` + +Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. + +| Type | Required | Platform | +| ------------------------------------------------------------------------------------ | -------- | -------- | +| 'none' | 'polite' | 'assertive' | No | android | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | + +--- + +### `accessibilityRole` + +Indicates to accessibility services to treat UI component like a specific role. + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | + +--- + +### `accessibilityState` + +Indicates to accessibility services that UI Component is in a specific State. + +| Type | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | + +--- + +### `accessibilityValue` + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| /** _ The minimum value of this component's range. (should be an integer) _/ min?: number, /** _ The maximum value of this component's range. (should be an integer) _/ max?: number, /** _ The current value of this component's range. (should be an integer) _/ now?: number, /** _ A textual description of this component's value. (will override minimum, current, and maximum if set) _/ text?: string, |}> | No | + +--- + +### `accessibilityViewIsModal` + +A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityviewismodal | + +--- + +### `accessible` + +When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. + +See http://facebook.github.io/react-native/docs/view.html#accessible + +| Type | Required | +| --------- | -------- | +| `boolean` | No | + +--- ### `animating` @@ -23,6 +141,26 @@ See http://facebook.github.io/react-native/docs/activityindicator.html#animating --- +### `children` + +| Type | Required | +| ------ | -------- | +| `Node` | No | + +--- + +### `collapsable` + +Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#collapsable | + +--- + ### `color` The foreground color of the spinner (default is gray). @@ -35,6 +173,26 @@ See http://facebook.github.io/react-native/docs/activityindicator.html#color --- +### `focusable` + +Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | + +--- + +### `hasTVPreferredFocus` + +Whether to force the Android TV focus engine to move focus to this view. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | + +--- + ### `hidesWhenStopped` Whether the indicator should hide when not animating (true by default). @@ -47,6 +205,498 @@ See http://facebook.github.io/react-native/docs/activityindicator.html#hideswhen --- +### `hitSlop` + +This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. + +> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. + +See http://facebook.github.io/react-native/docs/view.html#hitslop + +| Type | Required | +| -------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | + +--- + +### `importantForAccessibility` + +Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. + +| Type | Required | Platform | +| ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | +| 'auto' | 'yes' | 'no' | 'no-hide-descendants' | No | android | + +See http://facebook.github.io/react-native/docs/view.html#importantforaccessibility | + +--- + +### `nativeBackgroundAndroid` + +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeForegroundAndroid` + +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeID` + +Used to locate this view from native classes. + +> This disables the 'layout-only view removal' optimization for this view! + +See http://facebook.github.io/react-native/docs/view.html#nativeid + +| Type | Required | +| -------- | -------- | +| `string` | No | + +--- + +### `needsOffscreenAlphaCompositing` + +Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#needsoffscreenalphacompositing | + +--- + +### `nextFocusDown` + +TV next focus down (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusForward` + +TV next focus forward (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusLeft` + +TV next focus left (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusRight` + +TV next focus right (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusUp` + +TV next focus up (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `onAccessibilityAction` + +When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action. + +| Type | Required | +| -------------------------------------------- | -------- | +| `(event: AccessibilityActionEvent) => mixed` | No | + +--- + +### `onAccessibilityEscape` + +When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. + +See http://facebook.github.io/react-native/docs/view.html#onaccessibilityescape + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onAccessibilityTap` + +When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. + +See http://facebook.github.io/react-native/docs/view.html#onaccessibilitytap + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onBlur` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: BlurEvent) => mixed` | No | + +--- + +### `onClick` + +The action to perform when this `View` is clicked on by a non-touch click, eg. enter key on a hardware keyboard. + +| Type | Required | Platform | +| ------------------------------ | -------- | -------- | +| `(event: PressEvent) => mixed` | No | Android | + +--- + +### `onFocus` + +| Type | Required | +| ------------------------------ | -------- | +| `(event: FocusEvent) => mixed` | No | + +--- + +### `onLayout` + +Invoked on mount and layout changes with: + +`{nativeEvent: { layout: {x, y, width, height}}}` + +This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. + +See http://facebook.github.io/react-native/docs/view.html#onlayout + +| Type | Required | +| ------------------------------- | -------- | +| `(event: LayoutEvent) => mixed` | No | + +--- + +### `onMagicTap` + +When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. + +See http://facebook.github.io/react-native/docs/view.html#onmagictap + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onMouseEnter` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | + +--- + +### `onMouseLeave` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | + +--- + +### `onMoveShouldSetResponder` + +Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. + +`View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onmoveshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onMoveShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a move, it should have this handler which returns `true`. + +`View.props.onMoveShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onMoveShouldsetrespondercapture + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onResponderEnd` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderGrant` + +The View is now responding for touch events. This is the time to highlight and show the user what is happening. + +`View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. + +PanResponder includes a note `// TODO: t7467124 investigate if this can be removed` that should help fixing this return type. + +See http://facebook.github.io/react-native/docs/view.html#onrespondergrant + +| Type | Required | +| -------------------------------------------------------- | -------- | +| (e: PressEvent) => void | boolean | No | + +--- + +### `onResponderMove` + +The user is moving their finger. + +`View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onrespondermove + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderReject` + +Another responder is already active and will not release it to that `View` asking to be the responder. + +`View.props.onResponderReject: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderreject + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderRelease` + +Fired at the end of the touch. + +`View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderrelease + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderStart` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderTerminate` + +The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) + +`View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderterminate + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderTerminationRequest` + +Some other `View` wants to become responder and is asking this `View` to release its responder. Returning `true` allows its release. + +`View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderterminationrequest + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onStartShouldSetResponder` + +Does this view want to become responder on the start of a touch? + +`View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onStartShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. + +`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetrespondercapture + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onTouchCancel` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchCancelCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchEnd` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchEndCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchMove` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchMoveCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchStart` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchStartCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `pointerEvents` + +Controls whether the `View` can be the target of touch events. + +See http://facebook.github.io/react-native/docs/view.html#pointerevents + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------- | -------- | +| 'auto' | 'box-none' | 'box-only' | 'none' | No | + +--- + +### `removeClippedSubviews` + +This is a special performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). + +See http://facebook.github.io/react-native/docs/view.html#removeclippedsubviews + +| Type | Required | +| --------- | -------- | +| `boolean` | No | + +--- + +### `renderToHardwareTextureAndroid` + +Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#rendertohardwaretextureandroid | + +--- + +### `shouldRasterizeIOS` + +Whether this `View` should be rendered as a bitmap before compositing. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#shouldrasterizeios | + +--- + ### `size` Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android. @@ -56,3 +706,25 @@ See http://facebook.github.io/react-native/docs/activityindicator.html#size | Type | Required | | --------------------------------------------------------------------- | -------- | | number | 'small' | 'large' | No | + +--- + +### `style` + +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | + +--- + +### `testID` + +Used to locate this view in end-to-end tests. + +> This disables the 'layout-only view removal' optimization for this view! + +See http://facebook.github.io/react-native/docs/view.html#testid + +| Type | Required | +| -------- | -------- | +| `string` | No | diff --git a/docs/drawerlayoutandroid.md b/docs/drawerlayoutandroid.md index 25a1b7ed5e2..018e2d3d8b1 100644 --- a/docs/drawerlayoutandroid.md +++ b/docs/drawerlayoutandroid.md @@ -53,9 +53,9 @@ return ( ); ``` -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| ------------------------------- | -------- | +| null | string | No | --- @@ -130,9 +130,9 @@ Function called whenever the navigation view has been opened. Function called whenever there is an interaction with the navigation view. -| Type | Required | -| -------------------------------------- | -------- | -| `DirectEventHandler` | No | +| Type | Required | +| --------------------------------------------------------------------------------------------- | -------- | +| (event: SyntheticEvent<T>) => void | Promise<void> | No | --- @@ -164,56 +164,118 @@ The navigation view that will be rendered to the side of the screen and can be p Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+. -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| ------------------------------- | -------- | +| null | string | No | --- ### `style` -| Type | Required | -| --------------- | -------- | -| `ViewStyleProp` | No | +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | ## Methods -### `blur` +### `blur()` + +```jsx +drawerLayoutAndroid.blur(); +``` Native methods --- -### `closeDrawer` +### `closeDrawer()` + +```jsx +drawerLayoutAndroid.closeDrawer(); +``` Closes the drawer. --- -### `focus` +### `focus()` + +```jsx +drawerLayoutAndroid.focus(); +``` --- -### `measure` +### `measure()` + +```jsx +drawerLayoutAndroid.measure(callback); +``` + +**Parameters:** + +| Name | Type | Required | Description | +| -------- | ------------------------------------------------------------------------------------------------ | -------- | ----------- | +| callback | `( x: number, y: number, width: number, height: number, pageX: number, pageY: number, ) => void` | Yes | | --- -### `measureInWindow` +### `measureInWindow()` + +```jsx +drawerLayoutAndroid.measureInWindow(callback); +``` + +**Parameters:** + +| Name | Type | Required | Description | +| -------- | ------------------------------------------------------------------ | -------- | ----------- | +| callback | `( x: number, y: number, width: number, height: number, ) => void` | Yes | | --- -### `measureLayout` +### `measureLayout()` + +```jsx +drawerLayoutAndroid.measureLayout(relativeToNativeNode, onSuccess, [onFail]); +``` + +**Parameters:** + +| Name | Type | Required | Description | +| -------------------- | ----------------------------------------------------------------------- | -------- | ----------- | +| relativeToNativeNode | `number` | Yes | | +| onSuccess | `( left: number, top: number, width: number, height: number, ) => void` | Yes | | +| onFail | `() => void` | No | | --- -### `openDrawer` +### `openDrawer()` + +```jsx +drawerLayoutAndroid.openDrawer(); +``` Opens the drawer. --- -### `positions` +### `positions()` + +```jsx +DrawerLayoutAndroid.positions(); +``` --- -### `setNativeProps` +### `setNativeProps()` + +```jsx +drawerLayoutAndroid.setNativeProps(nativeProps); +``` + +**Parameters:** + +| Name | Type | Required | Description | +| ----------- | -------- | -------- | ----------- | +| nativeProps | `Object` | Yes | | diff --git a/docs/image.md b/docs/image.md index 093655e143c..31757343582 100644 --- a/docs/image.md +++ b/docs/image.md @@ -5,86 +5,7 @@ title: Image A React component for displaying different types of images, including network images, static resources, temporary local images, and images from local disk, such as the camera roll. -This example shows fetching and displaying an image from local storage as well as one from network and even from data provided in the `'data:'` uri scheme. - -> Note that for network and data images, you will need to manually specify the dimensions of your image! - -```SnackPlayer name=Image -import React, { Component } from 'react'; -import { View, Image } from 'react-native'; - -export default class DisplayAnImage extends Component { - render() { - return ( - - - - - - ); - } -} -``` - -You can also add `style` to an image: - -```SnackPlayer name=Image -import React, { Component } from 'react'; -import { View, Image, StyleSheet } from 'react-native'; - -const styles = StyleSheet.create({ - stretch: { - width: 50, - height: 200, - resizeMode: 'stretch' - } -}); - -export default class DisplayAnImageWithStyle extends Component { - render() { - return ( - - - - ); - } -} -``` - -### GIF and WebP support on Android - -When building your own native code, GIF and WebP are not supported by default on Android. - -You will need to add some optional modules in `android/app/build.gradle`, depending on the needs of your app. - -```gradle -dependencies { - // If your app supports Android versions before Ice Cream Sandwich (API level 14) - implementation 'com.facebook.fresco:animated-base-support:1.3.0' - - // For animated GIF support - implementation 'com.facebook.fresco:animated-gif:2.0.0' - - // For WebP support, including animated WebP - implementation 'com.facebook.fresco:animated-webp:2.1.0' - implementation 'com.facebook.fresco:webpsupport:2.0.0' - - // For WebP support, without animations - implementation 'com.facebook.fresco:webpsupport:2.0.0' -} -``` +See https://facebook.github.io/react-native/docs/image.html --- @@ -92,288 +13,257 @@ dependencies { ## Props -### `style` - -`ImageResizeMode` is an `Enum` for different image resizing modes, set via the `resizeMode` style property on `Image` components. The values are `contain`, `cover`, `stretch`, `center`, `repeat`. - -| Type | Required | -| ----- | -------- | -| style | No | - -- [Layout Props...](layout-props.md#props) - -- [Shadow Props...](shadow-props.md#props) +### `accessibilityLabel` -- [Transforms...](transforms.md#props) +The text that's read by the screen reader when the user interacts with the image. -- **`borderTopRightRadius`**: number +See https://facebook.github.io/react-native/docs/image.html#accessibilitylabel -- **`backfaceVisibility`**: enum('visible', 'hidden') +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | -- **`borderBottomLeftRadius`**: number +--- -- **`borderBottomRightRadius`**: number +### `accessible` -- **`borderColor`**: [color](colors.md) +When true, indicates the image is an accessibility element. -- **`borderRadius`**: number +See https://facebook.github.io/react-native/docs/image.html#accessible -- **`borderTopLeftRadius`**: number +| Type | Required | +| --------- | -------- | +| `boolean` | No | -- **`backgroundColor`**: [color](colors.md) +--- -- **`borderWidth`**: number +### `blurRadius` -- **`opacity`**: number +blurRadius: the blur radius of the blur filter added to the image -- **`overflow`**: enum('visible', 'hidden') +See https://facebook.github.io/react-native/docs/image.html#blurradius -- **`resizeMode`**: Object.keys(ImageResizeMode) +| Type | Required | +| -------- | -------- | +| `number` | No | -- **`tintColor`**: [color](colors.md) +--- - Changes the color of all the non-transparent pixels to the tintColor. +### `capInsets` -- **`overlayColor`**: string (_Android_) +See https://facebook.github.io/react-native/docs/image.html#capinsets - When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners: +| Type | Required | +| -------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | - - Certain resize modes, such as 'contain' - - Animated GIFs +--- - A typical way to use this prop is with images displayed on a solid background and setting the `overlayColor` to the same color as the background. +### `children` - For details of how this works under the hood, see http://frescolib.org/docs/rounded-corners-and-circles.html +| Type | Required | +| --------- | -------- | +| `unknown` | No | --- -### `blurRadius` +### `defaultSource` -blurRadius: the blur radius of the blur filter added to the image +A static image to display while loading the image source. -| Type | Required | -| ------ | -------- | -| number | No | +See https://facebook.github.io/react-native/docs/image.html#defaultsource -> Tip : IOS you will need to increase `blurRadius` more than `5` ---- +| Type | Required | +| -------------------------------------------------------------------------------- | -------- | +| ImageURISource | number | Array<ImageURISource> | No | -### `onLayout` +--- -Invoked on mount and layout changes with `{nativeEvent: {layout: {x, y, width, height}}}`. +### `fadeDuration` | Type | Required | | -------- | -------- | -| function | No | +| `number` | No | --- -### `onLoad` +### `height` -Invoked when load completes successfully. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------------------------------------------- | -------- | +| null | number | string | AnimatedNode | No | --- -### `onLoadEnd` - -Invoked when load either succeeds or fails. +### `loadingIndicatorSource` -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| -------------------------------------------------------------------------- | -------- | +| number | \$ReadOnly<{|uri: string|}> | No | --- -### `onLoadStart` +### `onError` -Invoked on load start. +Invoked on load error with `{nativeEvent: {error}}`. -e.g., `onLoadStart={(e) => this.setState({loading: true})}` +See https://facebook.github.io/react-native/docs/image.html#onerror -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------------------------------------------------------------------------------------------------- | -------- | +| ( event: SyntheticEvent< \$ReadOnly<{| error: string, |}>, >, ) => void | No | --- -### `resizeMode` - -Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to `cover`. - -- `cover`: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding). - -- `contain`: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding). - -- `stretch`: Scale width and height independently, This may change the aspect ratio of the src. +### `onLayout` -- `repeat`: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view. +Invoked on mount and layout changes with `{nativeEvent: {layout: {x, y, width, height}}}`. -- `center`: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view. +See https://facebook.github.io/react-native/docs/image.html#onlayout -| Type | Required | -| ------------------------------------------------------- | -------- | -| enum('cover', 'contain', 'stretch', 'repeat', 'center') | No | +| Type | Required | +| ------------------------------- | -------- | +| `(event: LayoutEvent) => mixed` | No | --- -### `source` - -The image source (either a remote URL or a local file resource). +### `onLoad` -This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best `uri` to display based on the measured size of the image container. A `cache` property can be added to control how networked request interacts with the local cache. (For more information see [Cache Control for Images](images#cache-control-ios-only)). +Invoked when load completes successfully. -The currently supported formats are `png`, `jpg`, `jpeg`, `bmp`, `gif`, `webp` (Android only), `psd` (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967). +See https://facebook.github.io/react-native/docs/image.html#onload -| Type | Required | -| ------------------- | -------- | -| ImageSourcePropType | No | +| Type | Required | +| --------------------------------- | -------- | +| `(event: ImageLoadEvent) => void` | No | --- -### `loadingIndicatorSource` +### `onLoadEnd` -Similarly to `source`, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network. +Invoked when load either succeeds or fails. -| Type | Required | -| ------------------------------------- | -------- | -| array of ImageSourcePropTypes, number | No | +See https://facebook.github.io/react-native/docs/image.html#onloadend -> Can accept a number as returned by `require('./image.jpg')` +| Type | Required | +| ------------ | -------- | +| `() => void` | No | --- -### `onError` - -Invoked on load error with `{nativeEvent: {error}}`. - -| Type | Required | -| -------- | -------- | -| function | No | - ---- +### `onLoadStart` -### `testID` +Invoked on load start. -A unique identifier for this element to be used in UI Automation testing scripts. +See https://facebook.github.io/react-native/docs/image.html#onloadstart -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| ------------ | -------- | +| `() => void` | No | --- -### `resizeMethod` - -The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to `auto`. - -- `auto`: Use heuristics to pick between `resize` and `scale`. - -- `resize`: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of `scale` when the image is much larger than the view. +### `onPartialLoad` -- `scale`: The image gets drawn downscaled or upscaled. Compared to `resize`, `scale` is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view. +Invoked when a partial load of the image is complete. -More details about `resize` and `scale` can be found at http://frescolib.org/docs/resizing.html. +See https://facebook.github.io/react-native/docs/image.html#onpartialload -| Type | Required | Platform | -| ------------------------------- | -------- | -------- | -| enum('auto', 'resize', 'scale') | No | Android | +| Type | Required | +| ------------ | -------- | +| `() => void` | No | --- -### `accessibilityLabel` +### `onProgress` -The text that's read by the screen reader when the user interacts with the image. +Invoked on download progress with `{nativeEvent: {loaded, total}}`. -| Type | Required | Platform | -| ------ | -------- | -------- | -| string | No | iOS | +See https://facebook.github.io/react-native/docs/image.html#onprogress ---- +| Type | Required | +| --------------------------------------------------------------------------------------------------------------------------------- | -------- | +| ( event: SyntheticEvent<\$ReadOnly<{|loaded: number, total: number|}>>, ) => void | No | -### `accessible` +--- -When true, indicates the image is an accessibility element. +### `progressiveRenderingEnabled` -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- -### `capInsets` +### `resizeMethod` -When the image is resized, the corners of the size specified by `capInsets` will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the [official Apple documentation](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIImage_Class/index.html#//apple_ref/occ/instm/UIImage/resizableImageWithCapInsets). +See https://facebook.github.io/react-native/docs/image.html#resizemethod -| Type | Required | Platform | -| ------------------------------------------------------------------ | -------- | -------- | -| object: {top: number, left: number, bottom: number, right: number} | No | iOS | +| Type | Required | +| -------------------------------------------------------------------------------- | -------- | +| 'auto' | 'resize' | 'scale' | No | --- -### `defaultSource` +### `resizeMode` -A static image to display while loading the image source. +Determines how to resize the image when the frame doesn't match the raw image dimensions. -| Type | Required | Platform | -| -------------- | -------- | -------- | -| object, number | No | iOS | -| number | No | Android | +See https://facebook.github.io/react-native/docs/image.html#resizemode -If passing an object, the general shape is `{uri: string, width: number, height: number, scale: number}`: +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| 'cover' | 'contain' | 'stretch' | 'repeat' | 'center' | No | -- `uri` - a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource (which should be wrapped in the `require('./path/to/image.png')` function). -- `width`, `height` - can be specified if known at build time, in which case these will be used to set the default `` component dimensions. -- `scale` - used to indicate the scale factor of the image. Defaults to 1.0 if unspecified, meaning that one image pixel equates to one display point / DIP. +--- -If passing a number: +### `source` -- `number` - Opaque type returned by something like `require('./image.jpg')`. +The image source (either a remote URL or a local file resource). -> **Note:** On Android, the default source prop is ignored on debug builds. +See https://facebook.github.io/react-native/docs/image.html#source ---- +| Type | Required | +| -------------------------------------------------------------------------------- | -------- | +| ImageURISource | number | Array<ImageURISource> | No | -### `onPartialLoad` +--- -Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads. +### `src` -| Type | Required | Platform | -| -------- | -------- | -------- | -| function | No | iOS | +| Type | Required | +| --------- | -------- | +| `unknown` | No | --- -### `onProgress` +### `style` -Invoked on download progress with `{nativeEvent: {loaded, total}}`. +See https://facebook.github.io/react-native/docs/image.html#style -| Type | Required | Platform | -| -------- | -------- | -------- | -| function | No | iOS | +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | --- -### `fadeDuration` +### `testID` -Android only. By default, it is 300ms. +A unique identifier for this element to be used in UI Automation testing scripts. -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +See https://facebook.github.io/react-native/docs/image.html#testid ---- +| Type | Required | +| -------- | -------- | +| `string` | No | -### `progressiveRenderingEnabled` +--- -Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html +### `width` -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | Android | +| Type | Required | +| ----------------------------------------------------------------- | -------- | +| null | number | string | AnimatedNode | No | ## Methods @@ -383,17 +273,17 @@ Android only. When true, enables progressive jpeg streaming. https://frescolib.o Image.getSize(uri, success, [failure]); ``` -Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download. +Retrieve the width and height (in pixels) of an image prior to displaying it. -In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API. +See https://facebook.github.io/react-native/docs/image.html#getsize **Parameters:** -| Name | Type | Required | Description | -| ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | -| uri | string | Yes | The location of the image. | -| success | function | Yes | The function that will be called if the image was successfully found and width and height retrieved. | -| failure | function | No | The function that will be called if there was an error, such as failing to retrieve the image. | +| Name | Type | Required | Description | +| ------- | ----------------------------------------- | -------- | ----------- | +| uri | `string` | Yes | | +| success | `(width: number, height: number) => void` | Yes | | +| failure | `(error: any) => void` | No | | --- @@ -403,20 +293,18 @@ In order to retrieve the image dimensions, the image may first need to be loaded Image.getSizeWithHeaders(uri, headers, success, [failure]); ``` -Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download. - -In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API. +Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. -Does not work for static image resources. +See https://facebook.github.io/react-native/docs/image.html#getsizewithheaders **Parameters:** -| Name | Type | Required | Description | -| ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | -| uri | string | Yes | The location of the image. | -| headers | object | Yes | The headers for the request. | -| success | function | Yes | The function that will be called if the image was successfully found and width and height retrieved. | -| failure | function | No | The function that will be called if there was an error, such as failing toto retrieve the image. | +| Name | Type | Required | Description | +| ------- | ----------------------------------------- | -------- | ----------- | +| uri | `string` | Yes | | +| headers | `{[string]: string, ...}` | Yes | | +| success | `(width: number, height: number) => void` | Yes | | +| failure | `(error: any) => void` | No | | --- @@ -426,29 +314,15 @@ Does not work for static image resources. Image.prefetch(url); ``` -Prefetches a remote image for later use by downloading it to the disk cache - -**Parameters:** - -| Name | Type | Required | Description | -| ---- | ------ | -------- | --------------------------------- | -| url | string | Yes | The remote location of the image. | - ---- +Prefetches a remote image for later use by downloading it to the disk cache. -### `abortPrefetch()` - -```jsx -Image.abortPrefetch(requestId); -``` - -Abort prefetch request. Android-only. +See https://facebook.github.io/react-native/docs/image.html#prefetch **Parameters:** -| Name | Type | Required | Description | -| --------- | ------ | -------- | ---------------------------- | -| requestId | number | Yes | Id as returned by prefetch() | +| Name | Type | Required | Description | +| ---- | -------- | -------- | ----------- | +| url | `string` | Yes | | --- @@ -458,28 +332,12 @@ Abort prefetch request. Android-only. Image.queryCache(urls); ``` -Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache. - -**Parameters:** +Performs cache interrogation. -| Name | Type | Required | Description | -| ---- | ----- | -------- | ------------------------------------------ | -| urls | array | Yes | List of image URLs to check the cache for. | - ---- - -### `resolveAssetSource()` - -```jsx -Image.resolveAssetSource(source); -``` - -Resolves an asset reference into an object which has the properties `uri`, `width`, and `height`. +See https://facebook.github.io/react-native/docs/image.html#querycache **Parameters:** -| Name | Type | Required | Description | -| ------ | -------------- | -------- | ---------------------------------------------------------------------------- | -| source | number, object | Yes | A number (opaque type returned by require('./foo.png')) or an `ImageSource`. | - -> `ImageSource` is an object like `{ uri: '' }` +| Name | Type | Required | Description | +| ---- | --------------- | -------- | ----------- | +| urls | `Array` | Yes | | diff --git a/docs/switch.md b/docs/switch.md index 5ff0d195653..a864fb94333 100644 --- a/docs/switch.md +++ b/docs/switch.md @@ -13,7 +13,145 @@ This is a controlled component that requires an `onValueChange` callback that up ## Props -Inherits [View Props](view.md#props). +### `accessibilityActions` + +Provides an array of custom actions available for accessibility. + +| Type | Required | +| ----------------------------------------- | -------- | +| `$ReadOnlyArray` | No | + +--- + +### `accessibilityElementsHidden` + +A value indicating whether the accessibility elements contained within this accessibility element are hidden. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | + +--- + +### `accessibilityHint` + +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. + +See http://facebook.github.io/react-native/docs/view.html#accessibilityHint + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | + +--- + +### `accessibilityIgnoresInvertColors` + +Prevents view from being inverted if set to true and color inversion is turned on. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | iOS | + +--- + +### `accessibilityLabel` + +Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. + +See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | + +--- + +### `accessibilityLiveRegion` + +Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. + +| Type | Required | Platform | +| ------------------------------------------------------------------------------------ | -------- | -------- | +| 'none' | 'polite' | 'assertive' | No | android | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | + +--- + +### `accessibilityRole` + +Indicates to accessibility services to treat UI component like a specific role. + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | + +--- + +### `accessibilityState` + +Indicates to accessibility services that UI Component is in a specific State. + +| Type | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | + +--- + +### `accessibilityValue` + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| /** _ The minimum value of this component's range. (should be an integer) _/ min?: number, /** _ The maximum value of this component's range. (should be an integer) _/ max?: number, /** _ The current value of this component's range. (should be an integer) _/ now?: number, /** _ A textual description of this component's value. (will override minimum, current, and maximum if set) _/ text?: string, |}> | No | + +--- + +### `accessibilityViewIsModal` + +A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityviewismodal | + +--- + +### `accessible` + +When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. + +See http://facebook.github.io/react-native/docs/view.html#accessible + +| Type | Required | +| --------- | -------- | +| `boolean` | No | + +--- + +### `children` + +| Type | Required | +| ------ | -------- | +| `Node` | No | + +--- + +### `collapsable` + +Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#collapsable | + +--- ### `disabled` @@ -25,13 +163,193 @@ Whether the switch is disabled. Defaults to false. --- +### `focusable` + +Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | + +--- + +### `hasTVPreferredFocus` + +Whether to force the Android TV focus engine to move focus to this view. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | + +--- + +### `hitSlop` + +This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. + +> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. + +See http://facebook.github.io/react-native/docs/view.html#hitslop + +| Type | Required | +| -------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | + +--- + +### `importantForAccessibility` + +Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. + +| Type | Required | Platform | +| ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | +| 'auto' | 'yes' | 'no' | 'no-hide-descendants' | No | android | + +See http://facebook.github.io/react-native/docs/view.html#importantforaccessibility | + +--- + ### `ios_backgroundColor` On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent). -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| ------------------------------- | -------- | +| null | string | No | + +--- + +### `nativeBackgroundAndroid` + +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeForegroundAndroid` + +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeID` + +Used to locate this view from native classes. + +> This disables the 'layout-only view removal' optimization for this view! + +See http://facebook.github.io/react-native/docs/view.html#nativeid + +| Type | Required | +| -------- | -------- | +| `string` | No | + +--- + +### `needsOffscreenAlphaCompositing` + +Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#needsoffscreenalphacompositing | + +--- + +### `nextFocusDown` + +TV next focus down (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusForward` + +TV next focus forward (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusLeft` + +TV next focus left (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusRight` + +TV next focus right (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `nextFocusUp` + +TV next focus up (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `onAccessibilityAction` + +When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action. + +| Type | Required | +| -------------------------------------------- | -------- | +| `(event: AccessibilityActionEvent) => mixed` | No | + +--- + +### `onAccessibilityEscape` + +When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. + +See http://facebook.github.io/react-native/docs/view.html#onaccessibilityescape + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onAccessibilityTap` + +When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. + +See http://facebook.github.io/react-native/docs/view.html#onaccessibilitytap + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onBlur` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: BlurEvent) => mixed` | No | --- @@ -47,6 +365,290 @@ Receives the change event as an argument. If you want to only receive the new va --- +### `onClick` + +The action to perform when this `View` is clicked on by a non-touch click, eg. enter key on a hardware keyboard. + +| Type | Required | Platform | +| ------------------------------ | -------- | -------- | +| `(event: PressEvent) => mixed` | No | Android | + +--- + +### `onFocus` + +| Type | Required | +| ------------------------------ | -------- | +| `(event: FocusEvent) => mixed` | No | + +--- + +### `onLayout` + +Invoked on mount and layout changes with: + +`{nativeEvent: { layout: {x, y, width, height}}}` + +This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. + +See http://facebook.github.io/react-native/docs/view.html#onlayout + +| Type | Required | +| ------------------------------- | -------- | +| `(event: LayoutEvent) => mixed` | No | + +--- + +### `onMagicTap` + +When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. + +See http://facebook.github.io/react-native/docs/view.html#onmagictap + +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- + +### `onMouseEnter` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | + +--- + +### `onMouseLeave` + +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | + +--- + +### `onMoveShouldSetResponder` + +Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. + +`View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onmoveshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onMoveShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a move, it should have this handler which returns `true`. + +`View.props.onMoveShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onMoveShouldsetrespondercapture + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onResponderEnd` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderGrant` + +The View is now responding for touch events. This is the time to highlight and show the user what is happening. + +`View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. + +PanResponder includes a note `// TODO: t7467124 investigate if this can be removed` that should help fixing this return type. + +See http://facebook.github.io/react-native/docs/view.html#onrespondergrant + +| Type | Required | +| -------------------------------------------------------- | -------- | +| (e: PressEvent) => void | boolean | No | + +--- + +### `onResponderMove` + +The user is moving their finger. + +`View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onrespondermove + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderReject` + +Another responder is already active and will not release it to that `View` asking to be the responder. + +`View.props.onResponderReject: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderreject + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderRelease` + +Fired at the end of the touch. + +`View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderrelease + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderStart` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderTerminate` + +The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) + +`View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderterminate + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderTerminationRequest` + +Some other `View` wants to become responder and is asking this `View` to release its responder. Returning `true` allows its release. + +`View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onresponderterminationrequest + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onStartShouldSetResponder` + +Does this view want to become responder on the start of a touch? + +`View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onStartShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. + +`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetrespondercapture + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onTouchCancel` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchCancelCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchEnd` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchEndCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchMove` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchMoveCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchStart` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onTouchStartCapture` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + ### `onValueChange` Called when the user tries to change the value of the switch. @@ -59,13 +661,83 @@ Receives the new value as an argument. If you want to instead receive an event, --- +### `pointerEvents` + +Controls whether the `View` can be the target of touch events. + +See http://facebook.github.io/react-native/docs/view.html#pointerevents + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------- | -------- | +| 'auto' | 'box-none' | 'box-only' | 'none' | No | + +--- + +### `removeClippedSubviews` + +This is a special performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). + +See http://facebook.github.io/react-native/docs/view.html#removeclippedsubviews + +| Type | Required | +| --------- | -------- | +| `boolean` | No | + +--- + +### `renderToHardwareTextureAndroid` + +Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#rendertohardwaretextureandroid | + +--- + +### `shouldRasterizeIOS` + +Whether this `View` should be rendered as a bitmap before compositing. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#shouldrasterizeios | + +--- + +### `style` + +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | + +--- + +### `testID` + +Used to locate this view in end-to-end tests. + +> This disables the 'layout-only view removal' optimization for this view! + +See http://facebook.github.io/react-native/docs/view.html#testid + +| Type | Required | +| -------- | -------- | +| `string` | No | + +--- + ### `thumbColor` Custom color for the switch thumb. -| Type | Required | -| ------------------ | -------- | -| [color](colors.md) | No | +| Type | Required | +| ------------------------------- | -------- | +| null | string | No | --- diff --git a/docs/text.md b/docs/text.md index c956884065f..3bd5a14b0a2 100644 --- a/docs/text.md +++ b/docs/text.md @@ -5,180 +5,7 @@ title: Text A React component for displaying text. -`Text` supports nesting, styling, and touch handling. - -In the following example, the nested title and body text will inherit the `fontFamily` from `styles.baseText`, but the title provides its own additional styles. The title and body will stack on top of each other on account of the literal newlines: - -```SnackPlayer name=Text -import React, { Component } from 'react'; -import { Text, StyleSheet } from 'react-native'; - -export default class TextInANest extends Component { - constructor(props) { - super(props); - this.state = { - titleText: "Bird's Nest", - bodyText: 'This is not really a bird nest.' - }; - } - - render() { - return ( - - - {this.state.titleText}{'\n'}{'\n'} - - - {this.state.bodyText} - - - ); - } -} - -const styles = StyleSheet.create({ - baseText: { - fontFamily: 'Cochin', - }, - titleText: { - fontSize: 20, - fontWeight: 'bold', - }, -}); -``` - -## Nested text - -Both Android and iOS allow you to display formatted text by annotating ranges of a string with specific formatting like bold or colored text (`NSAttributedString` on iOS, `SpannableString` on Android). In practice, this is very tedious. For React Native, we decided to use web paradigm for this where you can nest text to achieve the same effect. - -```SnackPlayer name=Nested -import React, { Component } from 'react'; -import { Text } from 'react-native'; - -export default class BoldAndBeautiful extends Component { - render() { - return ( - - I am bold - - and red - - - ); - } -} -``` - -Behind the scenes, React Native converts this to a flat `NSAttributedString` or `SpannableString` that contains the following information: - -```jsx -"I am bold and red" -0-9: bold -9-17: bold, red -``` - -## Containers - -The `` element is unique relative to layout: everything inside is no longer using the Flexbox layout but using text layout. This means that elements inside of a `` are no longer rectangles, but wrap when they see the end of the line. - -```jsx - - First part and - second part - -// Text container: the text will be inline if the space allowed it -// |First part and second part| - -// otherwise, the text will flow as if it was one -// |First part | -// |and second | -// |part | - - - First part and - second part - -// View container: each text is its own block -// |First part and| -// |second part | - -// otherwise, the text will flow in its own block -// |First part | -// |and | -// |second part| -``` - -## Limited Style Inheritance - -On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so: - -```css -html { - font-family: 'lucida grande', tahoma, verdana, arial, sans-serif; - font-size: 11px; - color: #141823; -} -``` - -All elements in the document will inherit this font unless they or one of their parents specifies a new rule. - -In React Native, we are more strict about it: **you must wrap all the text nodes inside of a `` component**. You cannot have a text node directly under a ``. - -```jsx -// BAD: will raise exception, can't have a text node as child of a - - Some text - - -// GOOD - - - Some text - - -``` - -You also lose the ability to set up a default font for an entire subtree. Meanwhile, `fontFamily` only accepts a single font name, which is different from `font-family` in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component `MyAppText` that includes them and use this component across your app. You can also use this component to make more specific components like `MyAppHeaderText` for other kinds of text. - -```jsx - - - Text styled with the default font for the entire application - - Text styled as a header - -``` - -Assuming that `MyAppText` is a component that only renders out its children into a `Text` component with styling, then `MyAppHeaderText` can be defined as follows: - -```jsx -class MyAppHeaderText extends Component { - render() { - return ( - - {this.props.children} - - ); - } -} -``` - -Composing `MyAppText` in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases. - -React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red. - -```jsx - - I am bold - and red - -``` - -We believe that this more constrained way to style text will yield better apps: - -- (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation. - -- (Implementor) The implementation of React Native is also simplified. We do not need to have a `fontFamily` field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself. +See https://facebook.github.io/react-native/docs/text.html --- @@ -188,171 +15,131 @@ We believe that this more constrained way to style text will yield better apps: ### `accessibilityHint` -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. - -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | --- ### `accessibilityLabel` -Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. - -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | --- ### `accessibilityRole` -Tells the screen reader to treat the currently focused on element as having a specific role. - -Possible values for `AccessibilityRole` is one of: - -- `'none'` - The element has no role. -- `'button'` - The element should be treated as a button. -- `'link'` - The element should be treated as a link. -- `'header'` - The element is a header that divides content into sections. -- `'search'` - The element should be treated as a search field. -- `'image'` - The element should be treated as an image. -- `'key'` - The element should be treated like a keyboard key. -- `'text'` - The element should be treated as text. -- `'summary'` - The element provides app summary information. -- `'imagebutton'` - The element has the role of both an image and also a button. -- `'adjustable'` - The element allows adjustment over a range of values. - -On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the [Accessibility guide](accessibility.md#accessibilitytraits-ios) for more information. - -On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS - -| Type | Required | -| ----------------- | -------- | -| AccessibilityRole | No | +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | --- ### `accessibilityState` -Tells the screen reader to treat the currently focused on element as being in a specific state. - -You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: `{selected: true, disabled: true}`. - -Possible values for `AccessibilityState` are: - -- `'selected'` - The element is in a selected state. -- `'disabled'` - The element is in a disabled state. - -| Type | Required | -| ------ | -------- | -| object | No | +| Type | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | --- ### `accessible` -When set to `true`, indicates that the view is an accessibility element. The default value for a `Text` element is `true`. +Indicates whether the view is an accessibility element. -See the [Accessibility guide](accessibility.md#accessible-ios-android) for more information. +See https://facebook.github.io/react-native/docs/text.html#accessible -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- ### `adjustsFontSizeToFit` -Specifies whether fonts should be scaled down automatically to fit given style constraints. +Whether font should be scaled down automatically. + +See https://facebook.github.io/react-native/docs/text.html#adjustsfontsizetofit -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- ### `allowFontScaling` -Specifies whether fonts should scale to respect Text Size accessibility settings. The default is `true`. +Whether fonts should scale to respect Text Size accessibility settings. -| Type | Required | -| ---- | -------- | -| bool | No | +See https://facebook.github.io/react-native/docs/text.html#allowfontscaling ---- +| Type | Required | +| --------- | -------- | +| `boolean` | No | -### `dataDetectorType` +--- -Determines the types of data converted to clickable URLs in the text element. By default no data types are detected. +### `children` -You can provide only one type. +| Type | Required | +| ------ | -------- | +| `Node` | No | -Possible values for `dataDetectorType` are: +--- -- `'phoneNumber'` -- `'link'` -- `'email'` -- `'none'` -- `'all'` +### `dataDetectorType` -| Type | Required | Platform | -| --------------------------------------------------- | -------- | -------- | -| enum('phoneNumber', 'link', 'email', 'none', 'all') | No | Android | +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| 'phoneNumber' | 'link' | 'email' | 'none' | 'all' | No | --- ### `disabled` -Specifies the disabled state of the text view for testing purposes +Specifies the disabled state of the text view for testing purposes. + +See https://facebook.github.io/react-native/docs/text.html#disabled -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | Android | +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- ### `ellipsizeMode` -When `numberOfLines` is set, this prop defines how text will be truncated. `numberOfLines` must be set in conjunction with this prop. +When `numberOfLines` is set, this prop defines how text will be truncated. -This can be one of the following values: +See https://facebook.github.io/react-native/docs/text.html#ellipsizemode -- `head` - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz" -- `middle` - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz" -- `tail` - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..." -- `clip` - Lines are not drawn past the edge of the text container. - -The default is `tail`. - -| Type | Required | -| -------------------------------------- | -------- | -| enum('head', 'middle', 'tail', 'clip') | No | +| Type | Required | +| ------------------------------------------------------------------------------------------------------- | -------- | +| 'clip' | 'head' | 'middle' | 'tail' | No | --- ### `maxFontSizeMultiplier` -Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: - -- `null/undefined` (default): inherit from the parent node or the global default (0) -- `0`: no max, ignore parent/global default -- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value +Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: `null/undefined` (default): inherit from the parent node or the global default (0) `0`: no max, ignore parent/global default `>= 1`: sets the maxFontSizeMultiplier of this node to this value -| Type | Required | -| ------ | -------- | -| number | No | +| Type | Required | +| -------- | -------- | +| `number` | No | --- ### `minimumFontScale` -Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0). +Smallest possible scale a font can reach. -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | iOS | +See https://facebook.github.io/react-native/docs/text.html#minimumfontscale + +| Type | Required | +| -------- | -------- | +| `number` | No | --- @@ -360,33 +147,35 @@ Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is Used to locate this view from native code. -| Type | Required | -| ------ | -------- | -| string | No | +See https://facebook.github.io/react-native/docs/text.html#nativeid + +| Type | Required | +| -------- | -------- | +| `string` | No | --- ### `numberOfLines` -Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. +Used to truncate the text with an ellipsis. -This prop is commonly used with `ellipsizeMode`. +See https://facebook.github.io/react-native/docs/text.html#numberoflines -| Type | Required | -| ------ | -------- | -| number | No | +| Type | Required | +| -------- | -------- | +| `number` | No | --- ### `onLayout` -Invoked on mount and layout changes with +Invoked on mount and layout changes. -`{nativeEvent: {layout: {x, y, width, height}}}` +See https://facebook.github.io/react-native/docs/text.html#onlayout -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------- | -------- | +| `(event: LayoutEvent) => mixed` | No | --- @@ -394,23 +183,19 @@ Invoked on mount and layout changes with This function is called on long press. -e.g., `onLongPress={this.increaseSize}>` +See https://facebook.github.io/react-native/docs/text.html#onlongpress -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------ | -------- | +| `(event: PressEvent) => mixed` | No | --- ### `onMoveShouldSetResponder` -Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. - -`View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| --------------- | -------- | +| `() => boolean` | No | --- @@ -418,107 +203,91 @@ Does this view want to "claim" touch responsiveness? This is called for every to This function is called on press. -e.g., `onPress={() => console.log('1st')}` +See https://facebook.github.io/react-native/docs/text.html#onpress -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------ | -------- | +| `(event: PressEvent) => mixed` | No | --- ### `onResponderGrant` -The View is now responding for touch events. This is the time to highlight and show the user what is happening. - -`View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------------------- | -------- | +| `(event: PressEvent, dispatchID: string) => void` | No | --- ### `onResponderMove` -The user is moving their finger. - -`View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------- | -------- | +| `(event: PressEvent) => void` | No | --- ### `onResponderRelease` -Fired at the end of the touch. - -`View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------- | -------- | +| `(event: PressEvent) => void` | No | --- ### `onResponderTerminate` -The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) - -`View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------- | -------- | +| `(event: PressEvent) => void` | No | --- ### `onResponderTerminationRequest` -Some other `View` wants to become responder and is asking this `View` to release its responder. Returning `true` allows its release. - -`View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| --------------- | -------- | +| `() => boolean` | No | --- -### `onStartShouldSetResponderCapture` - -If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. +### `onStartShouldSetResponder` -`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| --------------- | -------- | +| `() => boolean` | No | --- ### `onTextLayout` -TODO. +| Type | Required | +| ----------------------------------- | -------- | +| `(event: TextLayoutEvent) => mixed` | No | + +--- ### `pressRetentionOffset` -When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations. +Defines how far your touch may move off of the button, before deactivating the button. + +See https://facebook.github.io/react-native/docs/text.html#pressretentionoffset -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| object: {top: number, left: number, bottom: number, right: number} | No | +| Type | Required | +| ------------------------------------------------------------------------------------------------------------ | -------- | +| \$ReadOnly<{| top: number, left: number, bottom: number, right: number, |}> | No | --- ### `selectable` -Lets the user select text, to use the native copy and paste functionality. +Lets the user select text. -| Type | Required | -| ---- | -------- | -| bool | No | +See https://facebook.github.io/react-native/docs/text.html#selectable + +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- @@ -526,79 +295,31 @@ Lets the user select text, to use the native copy and paste functionality. The highlight color of the text. -| Type | Required | Platform | -| ------------------ | -------- | -------- | -| [color](colors.md) | No | Android | +See https://facebook.github.io/react-native/docs/text.html#selectioncolor + +| Type | Required | +| -------- | -------- | +| `string` | No | --- ### `style` -| Type | Required | -| ----- | -------- | -| style | No | - -- [View Style Props...](view-style-props.md#style) - -- **`textShadowOffset`**: object: {width: number,height: number} - -- **`color`**: [color](colors.md) - -- **`fontSize`**: number - -- **`fontStyle`**: enum('normal', 'italic') - -- **`fontWeight`**: enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900') - - Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen. - -- **`lineHeight`**: number - -- **`textAlign`**: enum('auto', 'left', 'right', 'center', 'justify') - - Specifies text alignment. On Android, the value 'justify' is only supported on Oreo (8.0) or above (API level >= 26). The value will fallback to `left` on lower Android versions. - -- **`textDecorationLine`**: enum('none', 'underline', 'line-through', 'underline line-through') - -- **`textShadowColor`**: [color](colors.md) - -- **`fontFamily`**: string - -- **`textShadowRadius`**: number - -- **`includeFontPadding`**: bool (_Android_) - - Set to `false` to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set `textAlignVertical` to `center`. Default is true. - -* **`textAlignVertical`**: enum('auto', 'top', 'bottom', 'center') (_Android_) - -* **`fontVariant`**: array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums') (_iOS_) - -* **`letterSpacing`**: number - - Increase or decrease the spacing between characters. The default is 0, for no extra letter spacing. - - iOS: The additional space will be rendered after each glyph. - - Android: Only supported since Android 5.0 - older versions will ignore this attribute. Please note that additional space will be added _around_ the glyphs (half on each side), which differs from the iOS rendering. It is possible to emulate the iOS rendering by using layout attributes, e.g. negative margins, as appropriate for your situation. - -* **`textDecorationColor`**: [color](colors.md) (_iOS_) - -* **`textDecorationStyle`**: enum('solid', 'double', 'dotted', 'dashed') (_iOS_) - -* **`textTransform`**: enum('none', 'uppercase', 'lowercase', 'capitalize') - -* **`writingDirection`**: enum('auto', 'ltr', 'rtl') (_iOS_) +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | --- ### `suppressHighlighting` -When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. +When `true`, no visual change is made when text is pressed down. -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +See https://facebook.github.io/react-native/docs/text.html#supperhighlighting + +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- @@ -606,20 +327,20 @@ When `true`, no visual change is made when text is pressed down. By default, a g Used to locate this view in end-to-end tests. -| Type | Required | -| ------ | -------- | -| string | No | +See https://facebook.github.io/react-native/docs/text.html#testid + +| Type | Required | +| -------- | -------- | +| `string` | No | --- ### `textBreakStrategy` -Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced` The default value is `highQuality`. - -| Type | Required | Platform | -| ----------------------------------------- | -------- | -------- | -| enum('simple', 'highQuality', 'balanced') | No | Android | +Set text break strategy on Android. -# Known issues +See https://facebook.github.io/react-native/docs/text.html#textbreakstrategy -- [react-native#22811](https://github.com/facebook/react-native/issues/22811): Nested Text elements do not support `numberOfLines` attribute +| Type | Required | +| ------------------------------------------------------------------------------------------ | -------- | +| 'balanced' | 'highQuality' | 'simple' | No | diff --git a/docs/view.md b/docs/view.md index b88d048446c..8c2dbd19079 100644 --- a/docs/view.md +++ b/docs/view.md @@ -3,47 +3,9 @@ id: view title: View --- -The most fundamental component for building a UI, `View` is a container that supports layout with [flexbox](flexbox.md), [style](style.md), [some touch handling](handling-touches.md), and [accessibility](accessibility.md) controls. `View` maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a `UIView`, `
`, `android.view`, etc. - -`View` is designed to be nested inside other views and can have 0 to many children of any type. - -This example creates a `View` that wraps two boxes with color and a text component in a row with padding. - -```jsx -class ViewBoxesWithColorAndText extends Component { - render() { - return ( - - - - Hello World! - - ); - } -} -``` - -> `View`s are designed to be used with [`StyleSheet`](style.md) for clarity and performance, although inline styles are also supported. - -### Synthetic Touch Events - -For `View` responder props (e.g., `onResponderMove`), the synthetic touch event passed to them are of the following form: - -- `nativeEvent` - - `changedTouches` - Array of all touch events that have changed since the last event. - - `identifier` - The ID of the touch. - - `locationX` - The X position of the touch, relative to the element. - - `locationY` - The Y position of the touch, relative to the element. - - `pageX` - The X position of the touch, relative to the root element. - - `pageY` - The Y position of the touch, relative to the root element. - - `target` - The node id of the element receiving the touch event. - - `timestamp` - A time identifier for the touch, useful for velocity calculation. - - `touches` - Array of all current touches on the screen. +The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. + +@see http://facebook.github.io/react-native/docs/view.html --- @@ -51,25 +13,47 @@ For `View` responder props (e.g., `onResponderMove`), the synthetic touch event ## Props -### `onStartShouldSetResponder` +### `accessibilityActions` -Does this view want to become responder on the start of a touch? +Provides an array of custom actions available for accessibility. -`View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. +| Type | Required | +| ----------------------------------------- | -------- | +| `$ReadOnlyArray` | No | -| Type | Required | -| -------- | -------- | -| function | No | +--- + +### `accessibilityElementsHidden` + +A value indicating whether the accessibility elements contained within this accessibility element are hidden. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | --- -### `accessible` +### `accessibilityHint` -When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. -| Type | Required | -| ---- | -------- | -| bool | No | +See http://facebook.github.io/react-native/docs/view.html#accessibilityHint + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | + +--- + +### `accessibilityIgnoresInvertColors` + +Prevents view from being inverted if set to true and color inversion is turned on. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | iOS | --- @@ -77,248 +61,337 @@ When `true`, indicates that the view is an accessibility element. By default, al Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. -| Type | Required | -| ------ | -------- | -| string | No | +See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel + +| Type | Required | +| ----------- | -------- | +| `Stringish` | No | --- -### `accessibilityHint` +### `accessibilityLiveRegion` -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. +Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | Platform | +| ------------------------------------------------------------------------------------ | -------- | -------- | +| 'none' | 'polite' | 'assertive' | No | android | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | --- ### `accessibilityRole` -`accessibilityRole` communicates the purpose of a component to the user of an assistive technology. - -`accessibilityRole` can be one of the following: - -- `'none'` - Used when the element has no role. -- `'button'` - Used when the element should be treated as a button. -- `'link'` - Used when the element should be treated as a link. -- `'search'` - Used when the text field element should also be treated as a search field. -- `'image'` - Used when the element should be treated as an image. Can be combined with button or link, for example. -- `'keyboardkey'` - Used when the element acts as a keyboard key. -- `'text'` - Used when the element should be treated as static text that cannot change. -- `'adjustable'` - Used when an element can be "adjusted" (e.g. a slider). -- `'imagebutton'` - Used when the element should be treated as a button and is also an image. -- `'header'` - Used when an element acts as a header for a content section (e.g. the title of a navigation bar). -- `'summary'` - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches. -- `'alert'` - Used when an element contains important text to be presented to the user. -- `'checkbox'` - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state. -- `'combobox'` - Used when an element represents a combo box, which allows the user to select among several choices. -- `'menu'` - Used when the component is a menu of choices. -- `'menubar'` - Used when a component is a container of multiple menus. -- `'menuitem'` - Used to represent an item within a menu. -- `'progressbar'` - Used to represent a component which indicates progress of a task. -- `'radio'` - Used to represent a radio button. -- `'radiogroup'` - Used to represent a group of radio buttons. -- `'scrollbar'` - Used to represent a scroll bar. -- `'spinbutton'` - Used to represent a button which opens a list of choices. -- `'switch'` - Used to represent a switch which can be turned on and off. -- `'tab'` - Used to represent a tab. -- `'tablist'` - Used to represent a list of tabs. -- `'timer'` - Used to represent a timer. -- `'toolbar'` - Used to represent a tool bar (a container of action buttons or components). +Indicates to accessibility services to treat UI component like a specific role. + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | + +--- + +### `accessibilityState` + +Indicates to accessibility services that UI Component is in a specific State. + +| Type | Required | +| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | + +--- + +### `accessibilityValue` + +| Type | Required | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| /** _ The minimum value of this component's range. (should be an integer) _/ min?: number, /** _ The maximum value of this component's range. (should be an integer) _/ max?: number, /** _ The current value of this component's range. (should be an integer) _/ now?: number, /** _ A textual description of this component's value. (will override minimum, current, and maximum if set) _/ text?: string, |}> | No | + +--- + +### `accessibilityViewIsModal` + +A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | + +See http://facebook.github.io/react-native/docs/view.html#accessibilityviewismodal | + +--- + +### `accessible` + +When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. + +See http://facebook.github.io/react-native/docs/view.html#accessible + +| Type | Required | +| --------- | -------- | +| `boolean` | No | + +--- + +### `children` | Type | Required | | ------ | -------- | -| string | No | +| `Node` | No | --- -### `accessibilityState` +### `collapsable` -Describes the current state of a component to the user of an assistive technology. +Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. -See the [Accessibility guide](accessibility.md#accessibilitystate-ios-android) for more information. +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | -| Type | Required | -| ---------------------------------------------------------------------------------------------- | -------- | -| object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool} | No | +See http://facebook.github.io/react-native/docs/view.html#collapsable | --- -### `accessibilityValue` +### `focusable` -Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum). +Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. -See the [Accessibility guide](accessibility.md#accessibilityvalue-ios-android) for more information. +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | -| Type | Required | -| ------------------------------------------------------------- | -------- | -| object: {min: number, max: number, now: number, text: string} | No | +--- + +### `hasTVPreferredFocus` + +Whether to force the Android TV focus engine to move focus to this view. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | Android | --- -### `accessibilityActions` +### `hitSlop` -Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label. +This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. + +> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. -See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. +See http://facebook.github.io/react-native/docs/view.html#hitslop -| Type | Required | -| ----- | -------- | -| array | No | +| Type | Required | +| -------------------------------------------------------------------------------------------------------------------- | -------- | +| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | --- -### `onAccessibilityAction` +### `importantForAccessibility` -Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform. +Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. -See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. +| Type | Required | Platform | +| ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | +| 'auto' | 'yes' | 'no' | 'no-hide-descendants' | No | android | -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#importantforaccessibility | --- -### `onAccessibilityTap` +### `nativeBackgroundAndroid` -When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeForegroundAndroid` + +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | + +--- + +### `nativeID` + +Used to locate this view from native classes. + +> This disables the 'layout-only view removal' optimization for this view! + +See http://facebook.github.io/react-native/docs/view.html#nativeid | Type | Required | | -------- | -------- | -| function | No | +| `string` | No | --- -### `onMagicTap` +### `needsOffscreenAlphaCompositing` -When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. +Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. + +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | + +See http://facebook.github.io/react-native/docs/view.html#needsoffscreenalphacompositing | + +--- + +### `nextFocusDown` + +TV next focus down (see documentation for the View component). | Type | Required | Platform | | -------- | -------- | -------- | -| function | No | iOS | +| `number` | No | Android | --- -### `onAccessibilityEscape` +### `nextFocusForward` -When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. +TV next focus forward (see documentation for the View component). | Type | Required | Platform | | -------- | -------- | -------- | -| function | No | iOS | +| `number` | No | Android | --- -### `accessibilityViewIsModal` +### `nextFocusLeft` -A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. +TV next focus left (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | -See the [Accessibility guide](accessibility.md#accessibilityviewismodal-ios) for more information. +--- + +### `nextFocusRight` -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +TV next focus right (see documentation for the View component). + +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | --- -### `accessibilityElementsHidden` +### `nextFocusUp` -A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is `false`. +TV next focus up (see documentation for the View component). -See the [Accessibility guide](accessibility.md#accessibilityelementshidden-ios) for more information. +| Type | Required | Platform | +| -------- | -------- | -------- | +| `number` | No | Android | + +--- + +### `onAccessibilityAction` + +When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action. -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | +| -------------------------------------------- | -------- | +| `(event: AccessibilityActionEvent) => mixed` | No | --- -### `accessibilityIgnoresInvertColors` +### `onAccessibilityEscape` -A value indicating this view should or should not be inverted when color inversion is turned on. A value of `true` will tell the view to not be inverted even if color inversion is turned on. +When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. -See the [Accessibility guide](accessibility.md#accessibilityignoresinvertcolors) for more information. +See http://facebook.github.io/react-native/docs/view.html#onaccessibilityescape -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | --- -### `accessibilityLiveRegion` +### `onAccessibilityTap` -Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values: +When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. + +See http://facebook.github.io/react-native/docs/view.html#onaccessibilitytap -- `'none'` - Accessibility services should not announce changes to this view. -- `'polite'`- Accessibility services should announce changes to this view. -- `'assertive'` - Accessibility services should interrupt ongoing speech to immediately announce changes to this view. +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | + +--- -See the [Android `View` docs](http://developer.android.com/reference/android/view/View.html#attr_android:accessibilityLiveRegion) for reference. +### `onBlur` -| Type | Required | Platform | -| ----------------------------------- | -------- | -------- | -| enum('none', 'polite', 'assertive') | No | Android | +| Type | Required | +| ----------------------------- | -------- | +| `(event: BlurEvent) => mixed` | No | --- -### `importantForAccessibility` +### `onClick` -Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. +The action to perform when this `View` is clicked on by a non-touch click, eg. enter key on a hardware keyboard. -Possible values: +| Type | Required | Platform | +| ------------------------------ | -------- | -------- | +| `(event: PressEvent) => mixed` | No | Android | -- `'auto'` - The system determines whether the view is important for accessibility - default (recommended). -- `'yes'` - The view is important for accessibility. -- `'no'` - The view is not important for accessibility. -- `'no-hide-descendants'` - The view is not important for accessibility, nor are any of its descendant views. +--- -See the [Android `importantForAccessibility` docs](http://developer.android.com/reference/android/R.attr.html#importantForAccessibility) for reference. +### `onFocus` -| Type | Required | Platform | -| ------------------------------------------------ | -------- | -------- | -| enum('auto', 'yes', 'no', 'no-hide-descendants') | No | Android | +| Type | Required | +| ------------------------------ | -------- | +| `(event: FocusEvent) => mixed` | No | --- -### `hitSlop` +### `onLayout` -This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. +Invoked on mount and layout changes with: + +`{nativeEvent: { layout: {x, y, width, height}}}` -For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with `hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}` +This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. -> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. +See http://facebook.github.io/react-native/docs/view.html#onlayout -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| object: {top: number, left: number, bottom: number, right: number} | No | +| Type | Required | +| ------------------------------- | -------- | +| `(event: LayoutEvent) => mixed` | No | --- -### `nativeID` +### `onMagicTap` -Used to locate this view from native classes. +When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. -> This disables the 'layout-only view removal' optimization for this view! +See http://facebook.github.io/react-native/docs/view.html#onmagictap -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| ------------- | -------- | +| `() => mixed` | No | --- -### `onLayout` +### `onMouseEnter` -Invoked on mount and layout changes with: +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | -`{nativeEvent: { layout: {x, y, width, height}}}` +--- -This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. +### `onMouseLeave` -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ----------------------------- | -------- | +| `(event: MouseEvent) => void` | No | --- @@ -328,9 +401,11 @@ Does this view want to "claim" touch responsiveness? This is called for every to `View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onmoveshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | --- @@ -340,9 +415,19 @@ If a parent `View` wants to prevent a child `View` from becoming responder on a `View.props.onMoveShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onMoveShouldsetrespondercapture + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | + +--- + +### `onResponderEnd` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- @@ -352,9 +437,13 @@ The View is now responding for touch events. This is the time to highlight and s `View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +PanResponder includes a note `// TODO: t7467124 investigate if this can be removed` that should help fixing this return type. + +See http://facebook.github.io/react-native/docs/view.html#onrespondergrant + +| Type | Required | +| -------------------------------------------------------- | -------- | +| (e: PressEvent) => void | boolean | No | --- @@ -364,9 +453,11 @@ The user is moving their finger. `View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onrespondermove + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- @@ -376,9 +467,11 @@ Another responder is already active and will not release it to that `View` askin `View.props.onResponderReject: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onresponderreject + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- @@ -388,9 +481,19 @@ Fired at the end of the touch. `View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onresponderrelease + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | + +--- + +### `onResponderStart` + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- @@ -400,9 +503,11 @@ The responder has been taken from the `View`. Might be taken by other views afte `View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onresponderterminate + +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- @@ -412,192 +517,170 @@ Some other `View` wants to become responder and is asking this `View` to release `View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onresponderterminationrequest + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | --- -### `onStartShouldSetResponderCapture` +### `onStartShouldSetResponder` -If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. +Does this view want to become responder on the start of a touch? -`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. +`View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. -| Type | Required | -| -------- | -------- | -| function | No | +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetresponder + +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | --- -### `pointerEvents` +### `onStartShouldSetResponderCapture` -Controls whether the `View` can be the target of touch events. +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. -- `'auto'`: The View can be the target of touch events. -- `'none'`: The View is never the target of touch events. -- `'box-none'`: The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS: +`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. -``` -.box-none { - pointer-events: none; -} -.box-none * { - pointer-events: auto; -} -``` +See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetrespondercapture -- `'box-only'`: The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS: +| Type | Required | +| ---------------------------- | -------- | +| `(e: PressEvent) => boolean` | No | -``` -.box-only { - pointer-events: auto; -} -.box-only * { - pointer-events: none; -} -``` +--- -> Since `pointerEvents` does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include `pointerEvents` on `style`. On some platforms, we would need to implement it as a `className` anyways. Using `style` or not is an implementation detail of the platform. +### `onTouchCancel` -| Type | Required | -| -------------------------------------------- | -------- | -| enum('box-none', 'none', 'box-only', 'auto') | No | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `removeClippedSubviews` - -This is a reserved performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). +### `onTouchCancelCapture` -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `style` +### `onTouchEnd` -| Type | Required | -| ---------------------------------- | -------- | -| [view styles](view-style-props.md) | No | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `testID` +### `onTouchEndCapture` -Used to locate this view in end-to-end tests. - -> This disables the 'layout-only view removal' optimization for this view! - -| Type | Required | -| ------ | -------- | -| string | No | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `collapsable` - -Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. +### `onTouchMove` -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | Android | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `needsOffscreenAlphaCompositing` - -Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (`false`) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the `View` you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping `View`s, or text and a background). - -Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view **contents** are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU. +### `onTouchMoveCapture` -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | --- -### `renderToHardwareTextureAndroid` +### `onTouchStart` -Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | -On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation. +--- -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | Android | +### `onTouchStartCapture` ---- +| Type | Required | +| ------------------------- | -------- | +| `(e: PressEvent) => void` | No | -### `shouldRasterizeIOS` +--- -Whether this `View` should be rendered as a bitmap before compositing. +### `pointerEvents` -On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame. +Controls whether the `View` can be the target of touch events. -Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property. +See http://facebook.github.io/react-native/docs/view.html#pointerevents -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Required | +| ------------------------------------------------------------------------------------------------------------- | -------- | +| 'auto' | 'box-none' | 'box-only' | 'none' | No | --- -### `nextFocusDown` +### `removeClippedSubviews` -Designates the next view to receive focus when the user navigates down. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown). +This is a special performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +See http://facebook.github.io/react-native/docs/view.html#removeclippedsubviews + +| Type | Required | +| --------- | -------- | +| `boolean` | No | --- -### `nextFocusForward` +### `renderToHardwareTextureAndroid` + +Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. -Designates the next view to receive focus when the user navigates forward. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward). +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | android | -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +See http://facebook.github.io/react-native/docs/view.html#rendertohardwaretextureandroid | --- -### `nextFocusLeft` +### `shouldRasterizeIOS` -Designates the next view to receive focus when the user navigates left. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft). +Whether this `View` should be rendered as a bitmap before compositing. -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | Platform | +| --------- | -------- | -------- | +| `boolean` | No | ios | ---- +See http://facebook.github.io/react-native/docs/view.html#shouldrasterizeios | -### `nextFocusRight` +--- -Designates the next view to receive focus when the user navigates right. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight). +### `style` -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +| Type | Required | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | --- -### `nextFocusUp` - -Designates the next view to receive focus when the user navigates up. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp). - -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | Android | +### `testID` ---- +Used to locate this view in end-to-end tests. -### `focusable` +> This disables the 'layout-only view removal' optimization for this view! -Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. +See http://facebook.github.io/react-native/docs/view.html#testid -| Type | Required | Platform | -| ------- | -------- | -------- | -| boolean | No | Android | +| Type | Required | +| -------- | -------- | +| `string` | No | From 8c81bec2130abc6fc8c3be6dde2923d69fd0d6f0 Mon Sep 17 00:00:00 2001 From: Ayush Jain Date: Thu, 6 Aug 2020 00:06:43 +0530 Subject: [PATCH 14/14] Sync docs with upstream --- STYLEGUIDE.md | 2 +- docs/activityindicator.md | 84 +- docs/button.md | 16 +- docs/drawerlayoutandroid.md | 52 +- docs/flatlist.md | 20 +- docs/image.md | 124 +-- docs/switch.md | 728 +----------------- docs/text.md | 256 +++--- docs/textinput.md | 1 - docs/view.md | 671 +++++++--------- netlify.toml | 2 +- .../static/docs/building-for-apple-tv.html | 15 +- 12 files changed, 574 insertions(+), 1397 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 50aaa99fa4f..b86814965e0 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -121,7 +121,7 @@ When it comes to describing property values, be definitive in what is and is not ## Other grammar policies -- Capitalize “Hooks.” +* Capitalize “Hooks.” ## Empathize with readers diff --git a/docs/activityindicator.md b/docs/activityindicator.md index b2a385ba4bd..3f7ac179ab0 100644 --- a/docs/activityindicator.md +++ b/docs/activityindicator.md @@ -3,9 +3,7 @@ id: activityindicator title: ActivityIndicator --- ---- - -# Reference +Displays a circular loading indicator. ## Example @@ -86,83 +84,9 @@ export default App; -### `accessibilityElementsHidden` - -A value indicating whether the accessibility elements contained within this accessibility element are hidden. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | - ---- - -### `accessibilityHint` - -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. - -See http://facebook.github.io/react-native/docs/view.html#accessibilityHint - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | - ---- - -### `accessibilityIgnoresInvertColors` - -Prevents view from being inverted if set to true and color inversion is turned on. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | iOS | - ---- - -### `accessibilityLabel` - -Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. - -See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | - ---- - -### `accessibilityLiveRegion` - -Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. - -| Type | Required | Platform | -| ------------------------------------------------------------------------------------ | -------- | -------- | -| 'none' | 'polite' | 'assertive' | No | android | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | - ---- - -### `accessibilityRole` - -Indicates to accessibility services to treat UI component like a specific role. - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | - ---- - -### `accessibilityState` - -Indicates to accessibility services that UI Component is in a specific State. - -| Type | Required | -| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | +# Reference ---- +## Props Inherits [View Props](view#props). @@ -198,7 +122,7 @@ Whether the indicator should hide when not animating. --- -### `hitSlop` +### `size` Size of the indicator. diff --git a/docs/button.md b/docs/button.md index 2331c6bd82f..feefb4786ba 100644 --- a/docs/button.md +++ b/docs/button.md @@ -128,7 +128,7 @@ Text to display inside the button. On Android the given title will be converted --- -### `disabled` +### `accessibilityLabel` Text to display for blindness accessibility features. @@ -138,7 +138,7 @@ Text to display for blindness accessibility features. --- -### `hasTVPreferredFocus` +### `color` Color of the text (iOS), or background color of the button (Android). @@ -148,7 +148,7 @@ Color of the text (iOS), or background color of the button (Android). --- -### `nextFocusDown` +### `disabled` If `true`, disable all interactions for this component. @@ -170,7 +170,7 @@ TV preferred focus. ### `nextFocusDown`
Android
TV
-### `nextFocusRight` +Designates the next view to receive focus when the user navigates down. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown). | Type | | ------ | @@ -180,7 +180,7 @@ TV preferred focus. ### `nextFocusForward`
Android
TV
-TV next focus up (see documentation for the View component). +Designates the next view to receive focus when the user navigates forward. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward). | Type | | ------ | @@ -190,7 +190,7 @@ TV next focus up (see documentation for the View component). ### `nextFocusLeft`
Android
TV
-Handler to be called when the user taps the button +Designates the next view to receive focus when the user navigates left. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft). | Type | | ------ | @@ -200,7 +200,7 @@ Handler to be called when the user taps the button ### `nextFocusRight`
Android
TV
-Used to locate this view in end-to-end tests. +Designates the next view to receive focus when the user navigates right. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight). | Type | | ------ | @@ -210,7 +210,7 @@ Used to locate this view in end-to-end tests. ### `nextFocusUp`
Android
TV
-Text to display inside the button +Designates the next view to receive focus when the user navigates up. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp). | Type | | ------ | diff --git a/docs/drawerlayoutandroid.md b/docs/drawerlayoutandroid.md index 738bf6dd077..b3a1b3c7dbf 100644 --- a/docs/drawerlayoutandroid.md +++ b/docs/drawerlayoutandroid.md @@ -75,7 +75,7 @@ export default App; ## Props -### `children` +Inherits [View Props](view.md#props). ### `drawerBackgroundColor` @@ -121,9 +121,9 @@ Specifies the side of the screen from which the drawer will slide in. By default Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window. -| Type | Required | -| -------- | -------- | -| `number` | No | +| Type | Required | +| ------ | -------- | +| number | No | --- @@ -134,9 +134,9 @@ Determines whether the keyboard gets dismissed in response to a drag. - 'none' (the default), drags do not dismiss the keyboard. - 'on-drag', the keyboard is dismissed when a drag begins. -| Type | Required | -| -------------------------------------------------------- | -------- | -| 'none' | 'on-drag' | No | +| Type | Required | +| ----------------------- | -------- | +| enum('none', 'on-drag') | No | --- @@ -154,9 +154,9 @@ Function called whenever the navigation view has been closed. Function called whenever the navigation view has been opened. -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -164,9 +164,9 @@ Function called whenever the navigation view has been opened. Function called whenever there is an interaction with the navigation view. -| Type | Required | -| --------------------------------------------------------------------------------------------- | -------- | -| (event: SyntheticEvent<T>) => void | Promise<void> | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -174,13 +174,13 @@ Function called whenever there is an interaction with the navigation view. Function called when the drawer state has changed. The drawer can be in 3 states: -- Idle, meaning there is no interaction with the navigation view happening at the time -- Dragging, meaning there is currently an interaction with the navigation view -- Settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation +- idle, meaning there is no interaction with the navigation view happening at the time +- dragging, meaning there is currently an interaction with the navigation view +- settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation -| Type | Required | -| -------------------------------- | -------- | -| `(state: DrawerStates) => mixed` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -198,17 +198,9 @@ The navigation view that will be rendered to the side of the screen and can be p Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+. -| Type | Required | -| ------------------------------- | -------- | -| null | string | No | - ---- - -### `style` - -| Type | Required | -| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | +| Type | Required | +| ------------------ | -------- | +| [color](colors.md) | No | ## Methods diff --git a/docs/flatlist.md b/docs/flatlist.md index 10228928748..96b566561f3 100644 --- a/docs/flatlist.md +++ b/docs/flatlist.md @@ -199,25 +199,17 @@ Example usage: ```jsx ( - - )) - } - data={[{ title: 'Title Text', key: 'item1' }]} - renderItem={({ item, index, separators }) => ( + ItemSeparatorComponent={Platform.OS !== 'android' && (({highlighted}) => ( + + ))} + data={[{title: 'Title Text', key: 'item1'}]} + renderItem={({item, index, separators}) => ( this._onPress(item)} onShowUnderlay={separators.highlight} onHideUnderlay={separators.unhighlight}> - + {item.title} diff --git a/docs/image.md b/docs/image.md index ac34a24769b..9482e37b90b 100644 --- a/docs/image.md +++ b/docs/image.md @@ -262,11 +262,13 @@ The text that's read by the screen reader when the user interacts with the image --- -### `defaultSource` +### `blurRadius` -A static image to display while loading the image source. +blurRadius: the blur radius of the blur filter added to the image -See https://facebook.github.io/react-native/docs/image.html#defaultsource +| Type | Required | +| ------ | -------- | +| number | No | > Tip : IOS you will need to increase `blurRadius` more than `5` @@ -315,19 +317,27 @@ Android only. By default, it is 300ms. --- -### `onLoadEnd` +### `loadingIndicatorSource` -Invoked when load either succeeds or fails. +Similarly to `source`, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network. -See https://facebook.github.io/react-native/docs/image.html#onloadend +| Type | Required | +| ------------------------------------- | -------- | +| array of ImageSourcePropTypes, number | No | -| Type | Required | -| ------------ | -------- | -| `() => void` | No | +> Can accept a number as returned by `require('./image.jpg')` --- -### `onLoadStart` +### `onError` + +Invoked on load error with `{nativeEvent: {error}}`. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- ### `onLayout` @@ -369,9 +379,7 @@ e.g., `onLoadStart={(e) => this.setState({loading: true})}` | -------- | -------- | | function | No | -| Type | Required | -| --------------------------------------------------------------------------------------------------------------------------------- | -------- | -| ( event: SyntheticEvent<\$ReadOnly<{|loaded: number, total: number|}>>, ) => void | No | +--- ### `onPartialLoad` @@ -419,9 +427,7 @@ More details about `resize` and `scale` can be found at http://frescolib.org/doc | ------------------------------- | -------- | -------- | | enum('auto', 'resize', 'scale') | No | Android | -| Type | Required | -| -------------------------------------------------------------------------------- | -------- | -| ImageURISource | number | Array<ImageURISource> | No | +--- ### `resizeMode` @@ -455,9 +461,7 @@ The currently supported formats are `png`, `jpg`, `jpeg`, `bmp`, `gif`, `webp` ( | ------------------- | -------- | | ImageSourcePropType | No | -| Type | Required | -| -------- | -------- | -| `string` | No | +--- ### `testID` @@ -475,17 +479,17 @@ A unique identifier for this element to be used in UI Automation testing scripts Image.getSize(uri, success, [failure]); ``` -Retrieve the width and height (in pixels) of an image prior to displaying it. +Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download. -See https://facebook.github.io/react-native/docs/image.html#getsize +In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API. **Parameters:** -| Name | Type | Required | Description | -| ------- | ----------------------------------------- | -------- | ----------- | -| uri | `string` | Yes | | -| success | `(width: number, height: number) => void` | Yes | | -| failure | `(error: any) => void` | No | | +| Name | Type | Required | Description | +| ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | +| uri | string | Yes | The location of the image. | +| success | function | Yes | The function that will be called if the image was successfully found and width and height retrieved. | +| failure | function | No | The function that will be called if there was an error, such as failing to retrieve the image. | --- @@ -495,18 +499,20 @@ See https://facebook.github.io/react-native/docs/image.html#getsize Image.getSizeWithHeaders(uri, headers, success, [failure]); ``` -Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. +Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download. + +In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API. -See https://facebook.github.io/react-native/docs/image.html#getsizewithheaders +Does not work for static image resources. **Parameters:** -| Name | Type | Required | Description | -| ------- | ----------------------------------------- | -------- | ----------- | -| uri | `string` | Yes | | -| headers | `{[string]: string, ...}` | Yes | | -| success | `(width: number, height: number) => void` | Yes | | -| failure | `(error: any) => void` | No | | +| Name | Type | Required | Description | +| ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | +| uri | string | Yes | The location of the image. | +| headers | object | Yes | The headers for the request. | +| success | function | Yes | The function that will be called if the image was successfully found and width and height retrieved. | +| failure | function | No | The function that will be called if there was an error, such as failing toto retrieve the image. | --- @@ -516,15 +522,29 @@ See https://facebook.github.io/react-native/docs/image.html#getsizewithheaders Image.prefetch(url); ``` -Prefetches a remote image for later use by downloading it to the disk cache. +Prefetches a remote image for later use by downloading it to the disk cache -See https://facebook.github.io/react-native/docs/image.html#prefetch +**Parameters:** + +| Name | Type | Required | Description | +| ---- | ------ | -------- | --------------------------------- | +| url | string | Yes | The remote location of the image. | + +--- + +### `abortPrefetch()` + +```jsx +Image.abortPrefetch(requestId); +``` + +Abort prefetch request. Android-only. **Parameters:** -| Name | Type | Required | Description | -| ---- | -------- | -------- | ----------- | -| url | `string` | Yes | | +| Name | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------- | +| requestId | number | Yes | Id as returned by prefetch() | --- @@ -534,12 +554,28 @@ See https://facebook.github.io/react-native/docs/image.html#prefetch Image.queryCache(urls); ``` -Performs cache interrogation. +Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache. -See https://facebook.github.io/react-native/docs/image.html#querycache +**Parameters:** + +| Name | Type | Required | Description | +| ---- | ----- | -------- | ------------------------------------------ | +| urls | array | Yes | List of image URLs to check the cache for. | + +--- + +### `resolveAssetSource()` + +```jsx +Image.resolveAssetSource(source); +``` + +Resolves an asset reference into an object which has the properties `uri`, `width`, and `height`. **Parameters:** -| Name | Type | Required | Description | -| ---- | --------------- | -------- | ----------- | -| urls | `Array` | Yes | | +| Name | Type | Required | Description | +| ------ | -------------- | -------- | ---------------------------------------------------------------------------- | +| source | number, object | Yes | A number (opaque type returned by require('./foo.png')) or an `ImageSource`. | + +> `ImageSource` is an object like `{ uri: '' }` diff --git a/docs/switch.md b/docs/switch.md index b1d10a19bd8..5fefeb7de20 100644 --- a/docs/switch.md +++ b/docs/switch.md @@ -3,7 +3,7 @@ id: switch title: Switch --- -A visual toggle between two mutually exclusive states. +Renders a boolean input. This is a controlled component that requires an `onValueChange` callback that updates the `value` prop in order for the component to reflect user actions. If the `value` prop is not updated, the component will continue to render the supplied `value` prop instead of the expected result of any user actions. @@ -47,199 +47,15 @@ export default App; ## Props -### `accessibilityActions` - -Provides an array of custom actions available for accessibility. - -| Type | Required | -| ----------------------------------------- | -------- | -| `$ReadOnlyArray` | No | - ---- - -### `accessibilityElementsHidden` - -A value indicating whether the accessibility elements contained within this accessibility element are hidden. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | - ---- - -### `accessibilityHint` - -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. - -See http://facebook.github.io/react-native/docs/view.html#accessibilityHint - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | - ---- - -### `accessibilityIgnoresInvertColors` - -Prevents view from being inverted if set to true and color inversion is turned on. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | iOS | - ---- - -### `accessibilityLabel` - -Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. - -See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | - ---- - -### `accessibilityLiveRegion` - -Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. - -| Type | Required | Platform | -| ------------------------------------------------------------------------------------ | -------- | -------- | -| 'none' | 'polite' | 'assertive' | No | android | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | - ---- - -### `accessibilityRole` - -Indicates to accessibility services to treat UI component like a specific role. - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | - ---- - -### `accessibilityState` - -Indicates to accessibility services that UI Component is in a specific State. - -| Type | Required | -| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | - ---- - -### `accessibilityValue` - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| \$ReadOnly<{| /** _ The minimum value of this component's range. (should be an integer) _/ min?: number, /** _ The maximum value of this component's range. (should be an integer) _/ max?: number, /** _ The current value of this component's range. (should be an integer) _/ now?: number, /** _ A textual description of this component's value. (will override minimum, current, and maximum if set) _/ text?: string, |}> | No | - ---- - -### `accessibilityViewIsModal` - -A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityviewismodal | - ---- - -### `accessible` - -When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. - -See http://facebook.github.io/react-native/docs/view.html#accessible - -| Type | Required | -| --------- | -------- | -| `boolean` | No | - ---- - -### `children` - -| Type | Required | -| ------ | -------- | -| `Node` | No | - ---- - -### `collapsable` - -Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | - -See http://facebook.github.io/react-native/docs/view.html#collapsable | - ---- +Inherits [View Props](view.md#props). ### `disabled` -Whether the switch is disabled. Defaults to false. - -| Type | Required | -| --------- | -------- | -| `boolean` | No | - ---- - -### `focusable` - -Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | Android | - ---- - -### `hasTVPreferredFocus` - -Whether to force the Android TV focus engine to move focus to this view. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | Android | - ---- - -### `hitSlop` - -This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. - -> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. +If true the user won't be able to toggle the switch. Default value is false. -See http://facebook.github.io/react-native/docs/view.html#hitslop - -| Type | Required | -| -------------------------------------------------------------------------------------------------------------------- | -------- | -| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | - ---- - -### `importantForAccessibility` - -Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. - -| Type | Required | Platform | -| ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | -| 'auto' | 'yes' | 'no' | 'no-hide-descendants' | No | android | - -See http://facebook.github.io/react-native/docs/view.html#importantforaccessibility | +| Type | Required | +| ---- | -------- | +| bool | No | --- @@ -247,531 +63,39 @@ See http://facebook.github.io/react-native/docs/view.html#importantforaccessibil On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent). -| Type | Required | -| ------------------------------- | -------- | -| null | string | No | - ---- - -### `nativeBackgroundAndroid` - -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | +| Type | Required | +| ------------------ | -------- | +| [color](colors.md) | No | --- -### `nativeForegroundAndroid` - -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | - ---- - -### `nativeID` - -Used to locate this view from native classes. - -> This disables the 'layout-only view removal' optimization for this view! +### `onChange` -See http://facebook.github.io/react-native/docs/view.html#nativeid +Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use `onValueChange` instead. | Type | Required | | -------- | -------- | -| `string` | No | - ---- - -### `needsOffscreenAlphaCompositing` - -Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | - -See http://facebook.github.io/react-native/docs/view.html#needsoffscreenalphacompositing | - ---- - -### `nextFocusDown` - -TV next focus down (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- - -### `nextFocusForward` - -TV next focus forward (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- - -### `nextFocusLeft` - -TV next focus left (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- - -### `nextFocusRight` - -TV next focus right (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- - -### `nextFocusUp` - -TV next focus up (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- - -### `onAccessibilityAction` - -When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action. - -| Type | Required | -| -------------------------------------------- | -------- | -| `(event: AccessibilityActionEvent) => mixed` | No | - ---- - -### `onAccessibilityEscape` - -When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. - -See http://facebook.github.io/react-native/docs/view.html#onaccessibilityescape - -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | - ---- - -### `onAccessibilityTap` - -When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. - -See http://facebook.github.io/react-native/docs/view.html#onaccessibilitytap - -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | - ---- - -### `onBlur` - -| Type | Required | -| ----------------------------- | -------- | -| `(event: BlurEvent) => mixed` | No | - ---- - -### `onChange` - -Called when the user tries to change the value of the switch. - -Receives the change event as an argument. If you want to only receive the new value, use `onValueChange` instead. - -| Type | Required | -| ----------------------------------------------------------------------------------- | -------- | -| (event: SwitchChangeEvent) => Promise<void> | void | No | - ---- - -### `onClick` - -The action to perform when this `View` is clicked on by a non-touch click, eg. enter key on a hardware keyboard. - -| Type | Required | Platform | -| ------------------------------ | -------- | -------- | -| `(event: PressEvent) => mixed` | No | Android | - ---- - -### `onFocus` - -| Type | Required | -| ------------------------------ | -------- | -| `(event: FocusEvent) => mixed` | No | - ---- - -### `onLayout` - -Invoked on mount and layout changes with: - -`{nativeEvent: { layout: {x, y, width, height}}}` - -This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. - -See http://facebook.github.io/react-native/docs/view.html#onlayout - -| Type | Required | -| ------------------------------- | -------- | -| `(event: LayoutEvent) => mixed` | No | - ---- - -### `onMagicTap` - -When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. - -See http://facebook.github.io/react-native/docs/view.html#onmagictap - -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | - ---- - -### `onMouseEnter` - -| Type | Required | -| ----------------------------- | -------- | -| `(event: MouseEvent) => void` | No | - ---- - -### `onMouseLeave` - -| Type | Required | -| ----------------------------- | -------- | -| `(event: MouseEvent) => void` | No | - ---- - -### `onMoveShouldSetResponder` - -Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. - -`View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onmoveshouldsetresponder - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onMoveShouldSetResponderCapture` - -If a parent `View` wants to prevent a child `View` from becoming responder on a move, it should have this handler which returns `true`. - -`View.props.onMoveShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onMoveShouldsetrespondercapture - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onResponderEnd` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderGrant` - -The View is now responding for touch events. This is the time to highlight and show the user what is happening. - -`View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. - -PanResponder includes a note `// TODO: t7467124 investigate if this can be removed` that should help fixing this return type. - -See http://facebook.github.io/react-native/docs/view.html#onrespondergrant - -| Type | Required | -| -------------------------------------------------------- | -------- | -| (e: PressEvent) => void | boolean | No | - ---- - -### `onResponderMove` - -The user is moving their finger. - -`View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onrespondermove - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderReject` - -Another responder is already active and will not release it to that `View` asking to be the responder. - -`View.props.onResponderReject: (event) => {}`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onresponderreject - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderRelease` - -Fired at the end of the touch. - -`View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onresponderrelease - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderStart` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderTerminate` - -The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) - -`View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onresponderterminate - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderTerminationRequest` - -Some other `View` wants to become responder and is asking this `View` to release its responder. Returning `true` allows its release. - -`View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onresponderterminationrequest - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onStartShouldSetResponder` - -Does this view want to become responder on the start of a touch? - -`View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetresponder - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onStartShouldSetResponderCapture` - -If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. - -`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. - -See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetrespondercapture - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onTouchCancel` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchCancelCapture` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchEnd` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchEndCapture` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchMove` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchMoveCapture` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchStart` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onTouchStartCapture` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| function | No | --- ### `onValueChange` -Called when the user tries to change the value of the switch. - -Receives the new value as an argument. If you want to instead receive an event, use `onChange`. - -| Type | Required | -| ------------------------------------------------------------------------- | -------- | -| (value: boolean) => Promise<void> | void | No | - ---- - -### `pointerEvents` - -Controls whether the `View` can be the target of touch events. - -See http://facebook.github.io/react-native/docs/view.html#pointerevents - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------- | -------- | -| 'auto' | 'box-none' | 'box-only' | 'none' | No | - ---- - -### `removeClippedSubviews` - -This is a special performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). - -See http://facebook.github.io/react-native/docs/view.html#removeclippedsubviews - -| Type | Required | -| --------- | -------- | -| `boolean` | No | - ---- - -### `renderToHardwareTextureAndroid` - -Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | - -See http://facebook.github.io/react-native/docs/view.html#rendertohardwaretextureandroid | - ---- - -### `shouldRasterizeIOS` - -Whether this `View` should be rendered as a bitmap before compositing. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#shouldrasterizeios | - ---- - -### `style` - -| Type | Required | -| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | - ---- - -### `testID` - -Used to locate this view in end-to-end tests. - -> This disables the 'layout-only view removal' optimization for this view! - -See http://facebook.github.io/react-native/docs/view.html#testid +Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use `onChange`. | Type | Required | | -------- | -------- | -| `string` | No | +| function | No | --- ### `thumbColor` -Custom color for the switch thumb. +Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow. -| Type | Required | -| ------------------------------- | -------- | -| null | string | No | +| Type | Required | +| ------------------ | -------- | +| [color](colors.md) | No | --- @@ -779,18 +103,18 @@ Custom color for the switch thumb. Custom colors for the switch track. -NOTE: On iOS when the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use `ios_backgroundColor`. +_iOS_: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use [`ios_backgroundColor`](switch.md#ios_backgroundColor). -| Type | Required | -| ------------------------------------------------------------------------------------------- | -------- | -| \$ReadOnly<{| false?: ?ColorValue, true?: ?ColorValue, |}> | No | +| Type | Required | +| ------------------------------------------------------------- | -------- | +| object: {false: [color](colors.md), true: [color](colors.md)} | No | --- ### `value` -Boolean value of the switch. Defaults to false. +The value of the switch. If true the switch will be turned on. Default value is false. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | +| ---- | -------- | +| bool | No | diff --git a/docs/text.md b/docs/text.md index 499cf2724c0..8286d814dfd 100644 --- a/docs/text.md +++ b/docs/text.md @@ -254,131 +254,171 @@ We believe that this more constrained way to style text will yield better apps: ### `accessibilityHint` -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. + +| Type | Required | +| ------ | -------- | +| string | No | --- ### `accessibilityLabel` -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | +Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. + +| Type | Required | +| ------ | -------- | +| string | No | --- ### `accessibilityRole` -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | +Tells the screen reader to treat the currently focused on element as having a specific role. + +Possible values for `AccessibilityRole` is one of: + +- `'none'` - The element has no role. +- `'button'` - The element should be treated as a button. +- `'link'` - The element should be treated as a link. +- `'header'` - The element is a header that divides content into sections. +- `'search'` - The element should be treated as a search field. +- `'image'` - The element should be treated as an image. +- `'key'` - The element should be treated like a keyboard key. +- `'text'` - The element should be treated as text. +- `'summary'` - The element provides app summary information. +- `'imagebutton'` - The element has the role of both an image and also a button. +- `'adjustable'` - The element allows adjustment over a range of values. + +On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the [Accessibility guide](accessibility.md#accessibilitytraits-ios) for more information. + +On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS + +| Type | Required | +| ----------------- | -------- | +| AccessibilityRole | No | --- ### `accessibilityState` -| Type | Required | -| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | +Tells the screen reader to treat the currently focused on element as being in a specific state. + +You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: `{selected: true, disabled: true}`. + +Possible values for `AccessibilityState` are: + +- `'selected'` - The element is in a selected state. +- `'disabled'` - The element is in a disabled state. + +| Type | Required | +| ------ | -------- | +| object | No | --- ### `accessible` -Indicates whether the view is an accessibility element. +When set to `true`, indicates that the view is an accessibility element. The default value for a `Text` element is `true`. -See https://facebook.github.io/react-native/docs/text.html#accessible +See the [Accessibility guide](accessibility.md#accessible-ios-android) for more information. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | +| ---- | -------- | +| bool | No | --- ### `adjustsFontSizeToFit` -Whether font should be scaled down automatically. +Specifies whether fonts should be scaled down automatically to fit given style constraints. -See https://facebook.github.io/react-native/docs/text.html#adjustsfontsizetofit - -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | --- ### `allowFontScaling` -Whether fonts should scale to respect Text Size accessibility settings. - -See https://facebook.github.io/react-native/docs/text.html#allowfontscaling +Specifies whether fonts should scale to respect Text Size accessibility settings. The default is `true`. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | +| ---- | -------- | +| bool | No | --- -### `children` +### `dataDetectorType` -| Type | Required | -| ------ | -------- | -| `Node` | No | +Determines the types of data converted to clickable URLs in the text element. By default no data types are detected. ---- +You can provide only one type. -### `dataDetectorType` +Possible values for `dataDetectorType` are: -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| 'phoneNumber' | 'link' | 'email' | 'none' | 'all' | No | +- `'phoneNumber'` +- `'link'` +- `'email'` +- `'none'` +- `'all'` + +| Type | Required | Platform | +| --------------------------------------------------- | -------- | -------- | +| enum('phoneNumber', 'link', 'email', 'none', 'all') | No | Android | --- ### `disabled` -Specifies the disabled state of the text view for testing purposes. - -See https://facebook.github.io/react-native/docs/text.html#disabled +Specifies the disabled state of the text view for testing purposes -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | Android | --- ### `ellipsizeMode` -When `numberOfLines` is set, this prop defines how text will be truncated. +When `numberOfLines` is set, this prop defines how text will be truncated. `numberOfLines` must be set in conjunction with this prop. -See https://facebook.github.io/react-native/docs/text.html#ellipsizemode +This can be one of the following values: -| Type | Required | -| ------------------------------------------------------------------------------------------------------- | -------- | -| 'clip' | 'head' | 'middle' | 'tail' | No | +- `head` - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz" +- `middle` - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz" +- `tail` - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..." +- `clip` - Lines are not drawn past the edge of the text container. + +The default is `tail`. + +| Type | Required | +| -------------------------------------- | -------- | +| enum('head', 'middle', 'tail', 'clip') | No | --- ### `maxFontSizeMultiplier` -Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: `null/undefined` (default): inherit from the parent node or the global default (0) `0`: no max, ignore parent/global default `>= 1`: sets the maxFontSizeMultiplier of this node to this value +Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: -| Type | Required | -| -------- | -------- | -| `number` | No | +- `null/undefined` (default): inherit from the parent node or the global default (0) +- `0`: no max, ignore parent/global default +- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value + +| Type | Required | +| ------ | -------- | +| number | No | --- ### `minimumFontScale` -Smallest possible scale a font can reach. +Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0). -See https://facebook.github.io/react-native/docs/text.html#minimumfontscale - -| Type | Required | -| -------- | -------- | -| `number` | No | +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | iOS | --- @@ -386,35 +426,33 @@ See https://facebook.github.io/react-native/docs/text.html#minimumfontscale Used to locate this view from native code. -See https://facebook.github.io/react-native/docs/text.html#nativeid - -| Type | Required | -| -------- | -------- | -| `string` | No | +| Type | Required | +| ------ | -------- | +| string | No | --- ### `numberOfLines` -Used to truncate the text with an ellipsis. +Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. -See https://facebook.github.io/react-native/docs/text.html#numberoflines +This prop is commonly used with `ellipsizeMode`. -| Type | Required | -| -------- | -------- | -| `number` | No | +| Type | Required | +| ------ | -------- | +| number | No | --- ### `onLayout` -Invoked on mount and layout changes. +Invoked on mount and layout changes with -See https://facebook.github.io/react-native/docs/text.html#onlayout +`{nativeEvent: {layout: {x, y, width, height}}}` -| Type | Required | -| ------------------------------- | -------- | -| `(event: LayoutEvent) => mixed` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -422,11 +460,11 @@ See https://facebook.github.io/react-native/docs/text.html#onlayout This function is called on long press. -See https://facebook.github.io/react-native/docs/text.html#onlongpress +e.g., `onLongPress={this.increaseSize}>` -| Type | Required | -| ------------------------------ | -------- | -| `(event: PressEvent) => mixed` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -446,11 +484,11 @@ Does this view want to "claim" touch responsiveness? This is called for every to This function is called on press. The first function argument is an event in form of [PressEvent](pressevent). -See https://facebook.github.io/react-native/docs/text.html#onpress +e.g., `onPress={() => console.log('1st')}` -| Type | Required | -| ------------------------------ | -------- | -| `(event: PressEvent) => mixed` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -514,7 +552,9 @@ Some other `View` wants to become responder and is asking this `View` to release --- -### `onStartShouldSetResponder` +### `onStartShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. `View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a [PressEvent](pressevent). @@ -539,9 +579,7 @@ Invoked on Text layout ### `pressRetentionOffset` -Defines how far your touch may move off of the button, before deactivating the button. - -See https://facebook.github.io/react-native/docs/text.html#pressretentionoffset +When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations. | Type | Required | | ---------------------- | -------- | @@ -551,13 +589,11 @@ See https://facebook.github.io/react-native/docs/text.html#pressretentionoffset ### `selectable` -Lets the user select text. - -See https://facebook.github.io/react-native/docs/text.html#selectable +Lets the user select text, to use the native copy and paste functionality. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | +| ---- | -------- | +| bool | No | --- @@ -565,11 +601,9 @@ See https://facebook.github.io/react-native/docs/text.html#selectable The highlight color of the text. -See https://facebook.github.io/react-native/docs/text.html#selectioncolor - -| Type | Required | -| -------- | -------- | -| `string` | No | +| Type | Required | Platform | +| ------------------ | -------- | -------- | +| [color](colors.md) | No | Android | --- @@ -583,13 +617,11 @@ See https://facebook.github.io/react-native/docs/text.html#selectioncolor ### `suppressHighlighting` -When `true`, no visual change is made when text is pressed down. - -See https://facebook.github.io/react-native/docs/text.html#supperhighlighting +When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | --- @@ -597,17 +629,19 @@ See https://facebook.github.io/react-native/docs/text.html#supperhighlighting Used to locate this view in end-to-end tests. -See https://facebook.github.io/react-native/docs/text.html#testid - -| Type | Required | -| -------- | -------- | -| `string` | No | +| Type | Required | +| ------ | -------- | +| string | No | --- ### `textBreakStrategy` -Set text break strategy on Android. +Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced` The default value is `highQuality`. + +| Type | Required | Platform | +| ----------------------------------------- | -------- | -------- | +| enum('simple', 'highQuality', 'balanced') | No | Android | --- @@ -621,6 +655,4 @@ Sets the frequency of automatic hyphenation to use when determining word breaks # Known issues -| Type | Required | -| ------------------------------------------------------------------------------------------ | -------- | -| 'balanced' | 'highQuality' | 'simple' | No | +- [react-native#22811](https://github.com/facebook/react-native/issues/22811): Nested Text elements do not support `numberOfLines` attribute diff --git a/docs/textinput.md b/docs/textinput.md index 7252b1edcb1..be966139445 100644 --- a/docs/textinput.md +++ b/docs/textinput.md @@ -747,7 +747,6 @@ Possible values for `textContentType` are: When using `textContentType` as `newPassword` on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for `PasswordRules` take a look to the [Apple Docs](https://developer.apple.com/password-rules/). > If passwords generation dialog doesn't appear please make sure that: -> > - AutoFill is enabled: **Settings** → **Passwords & Accounts** → toggle "On" the **AutoFill Passwords**, > - iCloud Keychain is used: **Settings** → **Apple ID** → **iCloud** → **Keychain** → toggle "On" the **iCloud Keychain**. diff --git a/docs/view.md b/docs/view.md index be05c0da901..c82317c7d8e 100644 --- a/docs/view.md +++ b/docs/view.md @@ -86,45 +86,25 @@ For `View` responder props (e.g., `onResponderMove`), the synthetic touch event ## Props -### `accessibilityActions` +### `onStartShouldSetResponder` -Provides an array of custom actions available for accessibility. +Does this view want to become responder on the start of a touch? `View.props.onStartShouldSetResponder: (event) => [true | false]`, where `event` is a [PressEvent](pressevent). ---- - -### `accessibilityElementsHidden` - -A value indicating whether the accessibility elements contained within this accessibility element are hidden. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityElementsHidden | - ---- - -### `accessibilityHint` - -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. - -See http://facebook.github.io/react-native/docs/view.html#accessibilityHint - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- -### `accessibilityIgnoresInvertColors` +### `accessible` -Prevents view from being inverted if set to true and color inversion is turned on. +When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | iOS | +| Type | Required | +| ---- | -------- | +| bool | No | --- @@ -132,337 +112,248 @@ Prevents view from being inverted if set to true and color inversion is turned o Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. -See http://facebook.github.io/react-native/docs/view.html#accessibilitylabel - -| Type | Required | -| ----------- | -------- | -| `Stringish` | No | +| Type | Required | +| ------ | -------- | +| string | No | --- -### `accessibilityLiveRegion` - -Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. +### `accessibilityHint` -| Type | Required | Platform | -| ------------------------------------------------------------------------------------ | -------- | -------- | -| 'none' | 'polite' | 'assertive' | No | android | +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. -See http://facebook.github.io/react-native/docs/view.html#accessibilityliveregion | +| Type | Required | +| ------ | -------- | +| string | No | --- ### `accessibilityRole` -Indicates to accessibility services to treat UI component like a specific role. - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | 'none' | 'button' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tablist' | 'timer' | 'toolbar' | No | - ---- - -### `accessibilityState` - -Indicates to accessibility services that UI Component is in a specific State. - -| Type | Required | -| --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| { disabled?: boolean, selected?: boolean, checked?: ?boolean | 'mixed', busy?: boolean, expanded?: boolean, ... } | No | - ---- - -### `accessibilityValue` - -| Type | Required | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| \$ReadOnly<{| /** _ The minimum value of this component's range. (should be an integer) _/ min?: number, /** _ The maximum value of this component's range. (should be an integer) _/ max?: number, /** _ The current value of this component's range. (should be an integer) _/ now?: number, /** _ A textual description of this component's value. (will override minimum, current, and maximum if set) _/ text?: string, |}> | No | - ---- - -### `accessibilityViewIsModal` - -A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | - -See http://facebook.github.io/react-native/docs/view.html#accessibilityviewismodal | - ---- - -### `accessible` - -When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible. - -See http://facebook.github.io/react-native/docs/view.html#accessible - -| Type | Required | -| --------- | -------- | -| `boolean` | No | - ---- - -### `children` +`accessibilityRole` communicates the purpose of a component to the user of an assistive technology. + +`accessibilityRole` can be one of the following: + +- `'none'` - Used when the element has no role. +- `'button'` - Used when the element should be treated as a button. +- `'link'` - Used when the element should be treated as a link. +- `'search'` - Used when the text field element should also be treated as a search field. +- `'image'` - Used when the element should be treated as an image. Can be combined with button or link, for example. +- `'keyboardkey'` - Used when the element acts as a keyboard key. +- `'text'` - Used when the element should be treated as static text that cannot change. +- `'adjustable'` - Used when an element can be "adjusted" (e.g. a slider). +- `'imagebutton'` - Used when the element should be treated as a button and is also an image. +- `'header'` - Used when an element acts as a header for a content section (e.g. the title of a navigation bar). +- `'summary'` - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches. +- `'alert'` - Used when an element contains important text to be presented to the user. +- `'checkbox'` - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state. +- `'combobox'` - Used when an element represents a combo box, which allows the user to select among several choices. +- `'menu'` - Used when the component is a menu of choices. +- `'menubar'` - Used when a component is a container of multiple menus. +- `'menuitem'` - Used to represent an item within a menu. +- `'progressbar'` - Used to represent a component which indicates progress of a task. +- `'radio'` - Used to represent a radio button. +- `'radiogroup'` - Used to represent a group of radio buttons. +- `'scrollbar'` - Used to represent a scroll bar. +- `'spinbutton'` - Used to represent a button which opens a list of choices. +- `'switch'` - Used to represent a switch which can be turned on and off. +- `'tab'` - Used to represent a tab. +- `'tablist'` - Used to represent a list of tabs. +- `'timer'` - Used to represent a timer. +- `'toolbar'` - Used to represent a tool bar (a container of action buttons or components). | Type | Required | | ------ | -------- | -| `Node` | No | - ---- - -### `collapsable` - -Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | - -See http://facebook.github.io/react-native/docs/view.html#collapsable | - ---- - -### `focusable` - -Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | Android | - ---- - -### `hasTVPreferredFocus` - -Whether to force the Android TV focus engine to move focus to this view. - -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | Android | +| string | No | --- -### `hitSlop` - -This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. +### `accessibilityState` -> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. +Describes the current state of a component to the user of an assistive technology. -See http://facebook.github.io/react-native/docs/view.html#hitslop +See the [Accessibility guide](accessibility.md#accessibilitystate-ios-android) for more information. -| Type | Required | -| -------------------------------------------------------------------------------------------------------------------- | -------- | -| \$ReadOnly<{| bottom?: ?number, left?: ?number, right?: ?number, top?: ?number, |}> | No | +| Type | Required | +| ---------------------------------------------------------------------------------------------- | -------- | +| object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool} | No | --- -### `importantForAccessibility` +### `accessibilityValue` -Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. +Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum). -| Type | Required | Platform | -| ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | -| 'auto' | 'yes' | 'no' | 'no-hide-descendants' | No | android | +See the [Accessibility guide](accessibility.md#accessibilityvalue-ios-android) for more information. -See http://facebook.github.io/react-native/docs/view.html#importantforaccessibility | +| Type | Required | +| ------------------------------------------------------------- | -------- | +| object: {min: number, max: number, now: number, text: string} | No | --- -### `nativeBackgroundAndroid` +### `accessibilityActions` -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | +Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label. ---- +See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. -### `nativeForegroundAndroid` - -| Type | Required | -| ------------------------------------------------------------------ | -------- | -| AndroidDrawableThemeAttr | AndroidDrawableRipple | No | +| Type | Required | +| ----- | -------- | +| array | No | --- -### `nativeID` - -Used to locate this view from native classes. +### `onAccessibilityAction` -> This disables the 'layout-only view removal' optimization for this view! +Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform. -See http://facebook.github.io/react-native/docs/view.html#nativeid +See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. | Type | Required | | -------- | -------- | -| `string` | No | +| function | No | --- -### `needsOffscreenAlphaCompositing` - -Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. +### `onAccessibilityTap` -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | +When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. -See http://facebook.github.io/react-native/docs/view.html#needsoffscreenalphacompositing | +| Type | Required | +| -------- | -------- | +| function | No | --- -### `nextFocusDown` +### `onMagicTap` -TV next focus down (see documentation for the View component). +When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. | Type | Required | Platform | | -------- | -------- | -------- | -| `number` | No | Android | +| function | No | iOS | --- -### `nextFocusForward` +### `onAccessibilityEscape` -TV next focus forward (see documentation for the View component). +When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. | Type | Required | Platform | | -------- | -------- | -------- | -| `number` | No | Android | +| function | No | iOS | --- -### `nextFocusLeft` - -TV next focus left (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- +### `accessibilityViewIsModal` -### `nextFocusRight` +A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is `false`. -TV next focus right (see documentation for the View component). +See the [Accessibility guide](accessibility.md#accessibilityviewismodal-ios) for more information. -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | --- -### `nextFocusUp` - -TV next focus up (see documentation for the View component). - -| Type | Required | Platform | -| -------- | -------- | -------- | -| `number` | No | Android | - ---- +### `accessibilityElementsHidden` -### `onAccessibilityAction` +A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is `false`. -When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action. +See the [Accessibility guide](accessibility.md#accessibilityelementshidden-ios) for more information. -| Type | Required | -| -------------------------------------------- | -------- | -| `(event: AccessibilityActionEvent) => mixed` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | --- -### `onAccessibilityEscape` +### `accessibilityIgnoresInvertColors` -When `accessible` is `true`, the system will invoke this function when the user performs the escape gesture. +A value indicating this view should or should not be inverted when color inversion is turned on. A value of `true` will tell the view to not be inverted even if color inversion is turned on. -See http://facebook.github.io/react-native/docs/view.html#onaccessibilityescape +See the [Accessibility guide](accessibility.md#accessibilityignoresinvertcolors) for more information. -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | --- -### `onAccessibilityTap` - -When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture. +### `accessibilityLiveRegion` -See http://facebook.github.io/react-native/docs/view.html#onaccessibilitytap +Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values: -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | +- `'none'` - Accessibility services should not announce changes to this view. +- `'polite'`- Accessibility services should announce changes to this view. +- `'assertive'` - Accessibility services should interrupt ongoing speech to immediately announce changes to this view. ---- +See the [Android `View` docs](http://developer.android.com/reference/android/view/View.html#attr_android:accessibilityLiveRegion) for reference. -### `onBlur` - -| Type | Required | -| ----------------------------- | -------- | -| `(event: BlurEvent) => mixed` | No | +| Type | Required | Platform | +| ----------------------------------- | -------- | -------- | +| enum('none', 'polite', 'assertive') | No | Android | --- -### `onClick` +### `importantForAccessibility` -The action to perform when this `View` is clicked on by a non-touch click, eg. enter key on a hardware keyboard. +Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only. -| Type | Required | Platform | -| ------------------------------ | -------- | -------- | -| `(event: PressEvent) => mixed` | No | Android | +Possible values: ---- +- `'auto'` - The system determines whether the view is important for accessibility - default (recommended). +- `'yes'` - The view is important for accessibility. +- `'no'` - The view is not important for accessibility. +- `'no-hide-descendants'` - The view is not important for accessibility, nor are any of its descendant views. -### `onFocus` +See the [Android `importantForAccessibility` docs](http://developer.android.com/reference/android/R.attr.html#importantForAccessibility) for reference. -| Type | Required | -| ------------------------------ | -------- | -| `(event: FocusEvent) => mixed` | No | +| Type | Required | Platform | +| ------------------------------------------------ | -------- | -------- | +| enum('auto', 'yes', 'no', 'no-hide-descendants') | No | Android | --- -### `onLayout` - -Invoked on mount and layout changes with: +### `hitSlop` -`{nativeEvent: { layout: {x, y, width, height}}}` +This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. -This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. +For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with `hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}` -See http://facebook.github.io/react-native/docs/view.html#onlayout +> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. -| Type | Required | -| ------------------------------- | -------- | -| `(event: LayoutEvent) => mixed` | No | +| Type | Required | +| ------------------------------------------------------------------ | -------- | +| object: {top: number, left: number, bottom: number, right: number} | No | --- -### `onMagicTap` +### `nativeID` -When `accessible` is `true`, the system will invoke this function when the user performs the magic tap gesture. +Used to locate this view from native classes. -See http://facebook.github.io/react-native/docs/view.html#onmagictap +> This disables the 'layout-only view removal' optimization for this view! -| Type | Required | -| ------------- | -------- | -| `() => mixed` | No | +| Type | Required | +| ------ | -------- | +| string | No | --- -### `onMouseEnter` +### `onLayout` -| Type | Required | -| ----------------------------- | -------- | -| `(event: MouseEvent) => void` | No | +Invoked on mount and layout changes with: ---- +`{nativeEvent: { layout: {x, y, width, height}}}` -### `onMouseLeave` +This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. -| Type | Required | -| ----------------------------- | -------- | -| `(event: MouseEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -472,11 +363,9 @@ Does this view want to "claim" touch responsiveness? This is called for every to `View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onmoveshouldsetresponder - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -486,19 +375,9 @@ If a parent `View` wants to prevent a child `View` from becoming responder on a `View.props.onMoveShouldSetResponderCapture: (event) => [true | false]`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onMoveShouldsetrespondercapture - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | - ---- - -### `onResponderEnd` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -508,13 +387,9 @@ The View is now responding for touch events. This is the time to highlight and s `View.props.onResponderGrant: (event) => {}`, where `event` is a [PressEvent](pressevent). -PanResponder includes a note `// TODO: t7467124 investigate if this can be removed` that should help fixing this return type. - -See http://facebook.github.io/react-native/docs/view.html#onrespondergrant - -| Type | Required | -| -------------------------------------------------------- | -------- | -| (e: PressEvent) => void | boolean | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -524,11 +399,9 @@ The user is moving their finger. `View.props.onResponderMove: (event) => {}`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onrespondermove - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -538,11 +411,9 @@ Another responder is already active and will not release it to that `View` askin `View.props.onResponderReject: (event) => {}`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onresponderreject - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -552,19 +423,9 @@ Fired at the end of the touch. `View.props.onResponderRelease: (event) => {}`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onresponderrelease - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | - ---- - -### `onResponderStart` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -574,11 +435,9 @@ The responder has been taken from the `View`. Might be taken by other views afte `View.props.onResponderTerminate: (event) => {}`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onresponderterminate - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- @@ -588,170 +447,192 @@ Some other `View` wants to become responder and is asking this `View` to release `View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onresponderterminationrequest - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- -### `onStartShouldSetResponder` +### `onStartShouldSetResponderCapture` -Does this view want to become responder on the start of a touch? +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. `View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a [PressEvent](pressevent). -See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetresponder - -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | +| Type | Required | +| -------- | -------- | +| function | No | --- -### `onStartShouldSetResponderCapture` +### `pointerEvents` -If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. +Controls whether the `View` can be the target of touch events. -`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. +- `'auto'`: The View can be the target of touch events. +- `'none'`: The View is never the target of touch events. +- `'box-none'`: The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS: -See http://facebook.github.io/react-native/docs/view.html#onstartshouldsetrespondercapture +``` +.box-none { + pointer-events: none; +} +.box-none * { + pointer-events: auto; +} +``` -| Type | Required | -| ---------------------------- | -------- | -| `(e: PressEvent) => boolean` | No | +- `'box-only'`: The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS: ---- +``` +.box-only { + pointer-events: auto; +} +.box-only * { + pointer-events: none; +} +``` -### `onTouchCancel` +> Since `pointerEvents` does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include `pointerEvents` on `style`. On some platforms, we would need to implement it as a `className` anyways. Using `style` or not is an implementation detail of the platform. -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| -------------------------------------------- | -------- | +| enum('box-none', 'none', 'box-only', 'auto') | No | --- -### `onTouchCancelCapture` +### `removeClippedSubviews` + +This is a reserved performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| ---- | -------- | +| bool | No | --- -### `onTouchEnd` +### `style` -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| ---------------------------------- | -------- | +| [view styles](view-style-props.md) | No | --- -### `onTouchEndCapture` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +### `testID` ---- +Used to locate this view in end-to-end tests. -### `onTouchMove` +> This disables the 'layout-only view removal' optimization for this view! -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| ------ | -------- | +| string | No | --- -### `onTouchMoveCapture` +### `collapsable` + +Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to `false` to disable this optimization and ensure that this `View` exists in the native view hierarchy. -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | Android | --- -### `onTouchStart` - -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +### `needsOffscreenAlphaCompositing` ---- +Whether this `View` needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (`false`) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the `View` you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping `View`s, or text and a background). -### `onTouchStartCapture` +Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view **contents** are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU. -| Type | Required | -| ------------------------- | -------- | -| `(e: PressEvent) => void` | No | +| Type | Required | +| ---- | -------- | +| bool | No | --- -### `pointerEvents` +### `renderToHardwareTextureAndroid` -Controls whether the `View` can be the target of touch events. +Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. -See http://facebook.github.io/react-native/docs/view.html#pointerevents +On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation. -| Type | Required | -| ------------------------------------------------------------------------------------------------------------- | -------- | -| 'auto' | 'box-none' | 'box-only' | 'none' | No | +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | Android | --- -### `removeClippedSubviews` +### `shouldRasterizeIOS` -This is a special performance property exposed by `RCTView` and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have `overflow: hidden`, as should the containing view (or one of its superviews). +Whether this `View` should be rendered as a bitmap before compositing. -See http://facebook.github.io/react-native/docs/view.html#removeclippedsubviews +On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame. -| Type | Required | -| --------- | -------- | -| `boolean` | No | +Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property. ---- +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | -### `renderToHardwareTextureAndroid` +--- -Whether this `View` should render itself (and all of its children) into a single hardware texture on the GPU. +### `nextFocusDown` -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | android | +Designates the next view to receive focus when the user navigates down. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown). -See http://facebook.github.io/react-native/docs/view.html#rendertohardwaretextureandroid | +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | Android | --- -### `shouldRasterizeIOS` +### `nextFocusForward` -Whether this `View` should be rendered as a bitmap before compositing. +Designates the next view to receive focus when the user navigates forward. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward). + +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | Android | + +--- + +### `nextFocusLeft` -| Type | Required | Platform | -| --------- | -------- | -------- | -| `boolean` | No | ios | +Designates the next view to receive focus when the user navigates left. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft). -See http://facebook.github.io/react-native/docs/view.html#shouldrasterizeios | +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | Android | --- -### `style` +### `nextFocusRight` -| Type | Required | -| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| | null | void | T | false | '' | \$ReadOnlyArray<GenericStyleProp<T>> | No | +Designates the next view to receive focus when the user navigates right. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight). + +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | Android | --- -### `testID` +### `nextFocusUp` -Used to locate this view in end-to-end tests. +Designates the next view to receive focus when the user navigates up. See the [Android documentation](https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp). -> This disables the 'layout-only view removal' optimization for this view! +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | Android | -See http://facebook.github.io/react-native/docs/view.html#testid +--- -| Type | Required | -| -------- | -------- | -| `string` | No | +### `focusable` + +Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. + +| Type | Required | Platform | +| ------- | -------- | -------- | +| boolean | No | Android | diff --git a/netlify.toml b/netlify.toml index c83f7a2f68c..1cb14009d45 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,4 +1,4 @@ [build] base = "website" - publish = "build/react-native" + publish = "website/build/react-native" command = "sed -i -e \"s|const baseUrl .*|const baseUrl = '/';|g\" siteConfig.js && yarn install && node netlify-reduce-versions && yarn sync-community-repos && yarn build" diff --git a/website/static/docs/building-for-apple-tv.html b/website/static/docs/building-for-apple-tv.html index b5b412559cb..414a49a3ba3 100644 --- a/website/static/docs/building-for-apple-tv.html +++ b/website/static/docs/building-for-apple-tv.html @@ -1,17 +1,14 @@ - + - - + + - - React Native · A framework for building native apps using React - + React Native · A framework for building native apps using React - If you are not redirected automatically, follow this - link. + If you are not redirected automatically, follow this link.