docs(input, searchbar, textarea): improve docs for managing focus (#28614)

Issue number: Related to #18132 

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
The documentation about the `autofocus` prop is unclear and does not
accurately reflect how it actually works across browsers and devices.

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- The documentation for `autofocus` and `setFocus` are more detailed.
- The documentation links to the relevant page in the docs.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!-- If this introduces a breaking change, please describe the impact
and migration path for existing applications below. -->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
This commit is contained in:
Shawn Taylor
2023-12-04 08:24:34 -05:00
committed by GitHub
parent 1705d064cc
commit fe3c3d500a
4 changed files with 19 additions and 9 deletions

View File

@ -1162,7 +1162,7 @@ export namespace Components {
*/ */
"autocorrect": 'on' | 'off'; "autocorrect": 'on' | 'off';
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element. This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"autofocus": boolean; "autofocus": boolean;
/** /**
@ -1274,7 +1274,7 @@ export namespace Components {
*/ */
"required": boolean; "required": boolean;
/** /**
* Sets focus on the native `input` in `ion-input`. Use this method instead of the global `input.focus()`. Developers who wish to focus an input when a page enters should call `setFocus()` in the `ionViewDidEnter()` lifecycle method. Developers who wish to focus an input when an overlay is presented should call `setFocus` after `didPresent` has resolved. * Sets focus on the native `input` in `ion-input`. Use this method instead of the global `input.focus()`. Developers who wish to focus an input when a page enters should call `setFocus()` in the `ionViewDidEnter()` lifecycle method. Developers who wish to focus an input when an overlay is presented should call `setFocus` after `didPresent` has resolved. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"setFocus": () => Promise<void>; "setFocus": () => Promise<void>;
/** /**
@ -2601,7 +2601,7 @@ export namespace Components {
*/ */
"searchIcon"?: string; "searchIcon"?: string;
/** /**
* Sets focus on the native `input` in `ion-searchbar`. Use this method instead of the global `input.focus()`. Developers who wish to focus an input when a page enters should call `setFocus()` in the `ionViewDidEnter()` lifecycle method. Developers who wish to focus an input when an overlay is presented should call `setFocus` after `didPresent` has resolved. * Sets focus on the native `input` in `ion-searchbar`. Use this method instead of the global `input.focus()`. Developers who wish to focus an input when a page enters should call `setFocus()` in the `ionViewDidEnter()` lifecycle method. Developers who wish to focus an input when an overlay is presented should call `setFocus` after `didPresent` has resolved. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"setFocus": () => Promise<void>; "setFocus": () => Promise<void>;
/** /**
@ -2950,7 +2950,7 @@ export namespace Components {
*/ */
"autocapitalize": string; "autocapitalize": string;
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element. This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"autofocus": boolean; "autofocus": boolean;
/** /**
@ -3050,7 +3050,7 @@ export namespace Components {
*/ */
"rows"?: number; "rows"?: number;
/** /**
* Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global `textarea.focus()`. * Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global `textarea.focus()`. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"setFocus": () => Promise<void>; "setFocus": () => Promise<void>;
/** /**
@ -5854,7 +5854,7 @@ declare namespace LocalJSX {
*/ */
"autocorrect"?: 'on' | 'off'; "autocorrect"?: 'on' | 'off';
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element. This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"autofocus"?: boolean; "autofocus"?: boolean;
/** /**
@ -7699,7 +7699,7 @@ declare namespace LocalJSX {
*/ */
"autocapitalize"?: string; "autocapitalize"?: string;
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element. This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
"autofocus"?: boolean; "autofocus"?: boolean;
/** /**

View File

@ -95,7 +95,9 @@ export class Input implements ComponentInterface {
@Prop() autocorrect: 'on' | 'off' = 'off'; @Prop() autocorrect: 'on' | 'off' = 'off';
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element.
*
* This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
@Prop() autofocus = false; @Prop() autofocus = false;
@ -424,6 +426,8 @@ export class Input implements ComponentInterface {
* *
* Developers who wish to focus an input when an overlay is presented * Developers who wish to focus an input when an overlay is presented
* should call `setFocus` after `didPresent` has resolved. * should call `setFocus` after `didPresent` has resolved.
*
* See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
@Method() @Method()
async setFocus() { async setFocus() {

View File

@ -257,6 +257,8 @@ export class Searchbar implements ComponentInterface {
* *
* Developers who wish to focus an input when an overlay is presented * Developers who wish to focus an input when an overlay is presented
* should call `setFocus` after `didPresent` has resolved. * should call `setFocus` after `didPresent` has resolved.
*
* See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
@Method() @Method()
async setFocus() { async setFocus() {

View File

@ -93,7 +93,9 @@ export class Textarea implements ComponentInterface {
@Prop() autocapitalize = 'none'; @Prop() autocapitalize = 'none';
/** /**
* This Boolean attribute lets you specify that a form control should have input focus when the page loads. * Sets the [`autofocus` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) on the native input element.
*
* This may not be sufficient for the element to be focused on page load. See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
@Prop() autofocus = false; @Prop() autofocus = false;
@ -372,6 +374,8 @@ export class Textarea implements ComponentInterface {
/** /**
* Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global * Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global
* `textarea.focus()`. * `textarea.focus()`.
*
* See [managing focus](/docs/developing/managing-focus) for more information.
*/ */
@Method() @Method()
async setFocus() { async setFocus() {