/* * Copyright (c) 2021-2024 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @file * @kit ArkUI */ /*** if arkts 1.2 */ import { CancelButtonSymbolOptions, CancelButtonOptions } from "./search"; import { Callback, CommonMethod, TextContentControllerBase, SelectionOptions, InputCounterOptions, TextDecorationOptions, Optional } from "./common"; import { CustomBuilder } from './builder'; import { BarState, LineBreakStrategy, TextAlign, FontStyle, FontWeight, WordBreak, TextOverflow, CopyOptions, TextHeightAdaptivePolicy, TextContentStyle, EllipsisMode } from './enums'; import { Resource, ResourceStr, ResourceColor, Dimension, Font, Length } from './units'; import { InsertValue, DeleteValue, CaretStyle, EditableTextOnChangeCallback, EditMenuOptions, AutoCapitalizationMode,EditableTextChangeValue,KeyboardAppearance } from "./textCommon"; import { KeyboardOptions, PasteEvent } from "./richEditor"; /*** endif */ /** * Declare the type of input box * * @enum { number } * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 7 */ /** * Declare the type of input box * * @enum { number } * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @since 10 */ /** * Declare the type of input box * * @enum { number } * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @atomicservice * @since arkts {'1.1':'11','1.2':'20'} * @arkts 1.1&1.2 */ declare enum InputType { /** * Basic input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 7 */ /** * Basic input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @since 10 */ /** * Basic input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @atomicservice * @since arkts {'1.1':'11','1.2':'20'} * @arkts 1.1&1.2 */ Normal, /** * Pure digital input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 7 */ /** * Pure digital input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @since 10 */ /** * Pure digital input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @atomicservice * @since arkts {'1.1':'11','1.2':'20'} * @arkts 1.1&1.2 */ Number, /** * Phone number entry mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 9 */ /** * Phone number entry mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @since 10 */ /** * Phone number entry mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @atomicservice * @since arkts {'1.1':'11','1.2':'20'} * @arkts 1.1&1.2 */ PhoneNumber, /** * E-mail address input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @since 7 */ /** * E-mail address input mode. * * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform * @since 10 */ /** * E-mail address input mode. * *
NOTE:
*
This mode accepts only digits, letters, underscores (_), dots (.),
* and the following special characters: ! # $ % & ' " * + - / = ? ^ ` { | } ~ @ (which can only appear once)
*
NOTE:
*
An eye icon is used to show or hide the password.
*
By default, the entered characters are temporarily shown before being obscured by dots;
* they are directly obscured by dots since API version 12 on certain devices.
*
The password input mode does not support underlines.
*
If Password Vault is enabled, autofill is available for the username and password.
*
NOTE:
*
An eye icon is used to show or hide the password.
*
By default, the entered characters are temporarily shown before being obscured by dots;
* they are directly obscured by dots since API version 12 on certain devices.
*
The password input mode does not support underlines.
*
NOTE:
*
If Password Vault is enabled, autofill is available for the username and password.
*
NOTE:
*
An eye icon is used to show or hide the password.
*
By default, the entered characters are temporarily shown before being obscured by dots;
* they are directly obscured by dots since API version 12 on certain devices.
*
If Password Vault is enabled, a new password can be automatically generated.
*
NOTE:
*
The value can contain digits and one decimal point.
*
NOTE:
*
If no value is specified or if the value specified is undefined,
* null, or invalid, the default value is used.
*
NOTE:
*
If no value is specified or if the value specified is undefined,
* null, or invalid, the default value is used.
*
NOTE:
*
If no value is specified or if the value specified is undefined,
* null, or invalid, the default value is used.
*
This option changes the color used in the showCounter attribute
* when the maximum number of characters is reached.
*
NOTE:
*
If no value is specified or if the value specified is undefined,
* null, or invalid, the default value is used.
*
NOTE:
*
If the value is less than 0, the value 0 is used.
*
If the value exceeds the text length, the caret is placed at the end of the text.
*
NOTE:
*
If selectionStart or selectionEnd is set to undefined, the value 0 will be used.
*
If selectionMenuHidden is set to true or a 2-in-1 device is used,
* calling setTextSelection does not display the context menu even when options is set to MenuPolicy.SHOW.
*
If the selected text contains an emoji,
* the emoji is selected when its start position is within the text selection range.
*
NOTE:
*
You are advised to bind the state variable to the text in real time through the onChange event,
* so as to prevent display errors when the component is updated.
*
Since API version 10, this parameter supports two-way binding through $$.
*
Since API version 18, this parameter supports two-way binding through !!.
*
NOTE:
*
The caret width is fixed at 1.5 vp,
* and the caret height is subject to the background height and font size of the selected text.
*
NOTE:
*
The background height of the selected text is the same as the height of the text box.
*
This style is used in scenarios where editing and non-editing states are obvious,
* for example, renaming in the file list view.
*
The showError attribute is not supported for this style.
*
This style does not allow for text dragging and dropping.
*
NOTE:
*
Icon that can be used to hide the password in password input mode.
*
The string type can be used to load network images and local images.
*
NOTE:
*
Icon that can be used to show the password in password input mode.
*
The string type can be used to load network images and local images.
*
NOTE:
*
This attribute is only available for the inline input style.
*
Text is clipped at the transition between words.
*
To clip text in the middle of a word, set wordBreak to WordBreak.BREAK_ALL.
*
TextOverflow.None produces the same effect as TextOverflow.Clip.
*
Default value in non-editing state in the inline input style: TextOverflow.Ellipsis.
*
Default value in editing state in the inline input style: TextOverflow.Clip.
*
The TextInput component does not support the TextOverflow.MARQUEE mode.
*
If TextOverflow.MARQUEE is set, the component automatically switches to TextOverflow.Ellipsis
* for the non-editing state in the inline input style and TextOverflow.Clip
* for the non-inline input style and the editing state in the inline input style.
*
NOTE:
*
The 'HarmonyOS Sans' font and registered custom fonts are supported.
*
The default value on wearable devices is 18fp.
*
NOTE:
*
Since API version 12, this API can be used to set the text handle color, which is the same as the caret color.
*
NOTE:
*
This API is deprecated since API version 8.
*
You are advised to use onEditChange instead.
*
NOTE:
*
The text box is in the editing state when it has the caret placed in it,
* and is in the non-editing state otherwise.
*
It returns true if the input operation is currently in progress.
*
NOTE:
*
In this callback, if cursor operations are performed, you need to adjust the cursor logic
* based on the previewText parameter to ensure it works seamlessly within the preview display scenario.
*
NOTE:
*
If this attribute is not set or is set to an invalid value, the default value is used.
*
If a decimal number is specified, the integer part is used.
*
NOTE:
*
If fontSize is of the number type, the unit fp is used.
*
The default font size is 16 fp.
*
The value cannot be a percentage.
*
The default value on wearable devices is 18fp.
*
NOTE:
*
If the value is too large, the text may be clipped depending on the font.
*
For the number type, the value range is [100, 900], at an interval of 100.
*
The default value is 400.
*
A larger value indicates a heavier font weight.
*
For the string type, only strings that represent a number, for example, "400",
* and the following enumerated values of FontWeight are supported: "bold", "bolder", "lighter", "regular", and "medium".
*
NOTE:
*
Default font: 'HarmonyOS Sans'
*
The 'HarmonyOS Sans' font and registered custom fonts are supported for applications.
*
Only the 'HarmonyOS Sans' font is supported for widgets.
*
NOTE:
*
Only inputs that comply with the regular expression can be displayed.
*
Other inputs are filtered out.
*
The specified regular expression can match single characters, but not strings.
*
Since API version 11, if inputFilter is set and the entered characters are not null,
* the filtering effect attached to the text box type (specified through the type attribute) does not take effect.
*
NOTE:
*
If this attribute is set to CopyOptions.None, the text can only be pasted;
* all other actions, such as copying, cutting, and sharing, are disabled.
*
Dragging is not allowed when CopyOptions.None is set.
*
NOTE:
*
This API has effect only when the input type is set to Password,
* NEWPASSWORD, or NUMBERPASSWORD mode. It does not work in other modes.
*
When in password mode, there may be inconsistency between the backend state of the text box
* and the frontend application's state management variables.
*
This can cause issues with the icon at the end of the password text box.
*
To avoid such issues, use the onSecurityStateChange callback to sync the states.
*
NOTE:
*
Available options are TextAlign.Start, TextAlign.Center, and TextAlign.End.
*
To set vertical alignment for the text, use the align attribute.
*
The align attribute alone does not control the horizontal position of the text.
*
In other words, Alignment.TopStart, Alignment.Top, and Alignment.TopEnd produce the same effect, top-aligning the text;
* Alignment.Start, Alignment.Center, and Alignment.End produce the same effect, centered-aligning the text vertically;
* Alignment.BottomStart, Alignment.Bottom, and Alignment.BottomEnd produce the same effect, bottom-aligning the text.
*
NOTE:
*
The inline input style only supports InputType.Normal.
*
NOTE:
*
If the opacity is not set, a 20% opacity will be used.
*
NOTE:
*
Since API version 10, the TextInput component brings up the keyboard by default when it obtains focus.
*
NOTE:
*
Images in JPG, PNG, BMP, HEIC, and WEBP formats are supported.
*
By default, the system-provided icon is used.
*
The icon size is fixed at 24 vp (or 28 vp on wearable devices), regardless of the source image size.
*
NOTE:
*
On wearable devices, the error message is displayed at a font size of 13 fp and center-aligned.
*
If the data type is ResourceStr and the input content does not comply with specifications, the error message is displayed.
*
If the error message does not fit in one line, an ellipsis (…) is displayed to represent clipped text.
*
If the data type is undefined, no error message is displayed.
*
By default, no error message is displayed.
*
NOTE:
*
This attribute effective only when showUnderline is set to true.
*
NOTE:
*
By default, the underline comes in the color of '#33182431', thickness of 1 px, and text box size of 48 vp.
*
The underline is only available for the InputType.Normal type.
*
NOTE:
*
The underline color changes with the underline mode.
*
If the underline color is only set for the normal state, you can directly enter a value of the ResourceColor type.
*
If the value specified is undefined, null, or invalid, all underlines are restored to the default value.
*
Default value: underline color configured for the theme, which is #33182431 by default.
*
NOTE:
*
true:
*
The system text selection menu does not appear under the following circumstances:
* clicking the text box cursor, long-pressing the text box, double-tapping the text box,
* triple-tapping the text box, or right-clicking the text box.
*
false:
*
The system text selection menu appears under the following circumstances:
* clicking the text box cursor, long-pressing the text box, double-tapping the text box,
* triple-tapping the text box, or right-clicking the text box.
*
NOTE:
*
This attribute is effective for the inline input style,
* but does not apply to the placeholder text.
*
The component does not support the clip attribute.
*
Therefore, setting this attribute does not affect text clipping.
*
NOTE:
*
This attribute takes effect when wordBreak is not set to breakAll.
*
Hyphens are not supported.
*
This attribute does not take effect for the non-inline input style.
*
NOTE:
*
When a custom keyboard is set, activating the text box opens the specified custom component,
* instead of the system input method.
*
The custom keyboard's height can be set through the height attribute of the custom component's root node,
* and its width is fixed at the default value.
*
The custom keyboard is presented by overlaying the original screen,
* which is not compressed or lifted if avoid mode is not enabled or avoidance is not needed for the text box.
*
The custom keyboard cannot obtain the focus, but it blocks gesture events.
*
By default, the custom keyboard is closed when the input component loses the focus.
*
You can also use the TextInputController.stopEditing API to close the keyboard.
*
When a custom keyboard is set, the text box does not support camera input, even when the device supports.
*
When setting a custom keyboard, you can bind the onKeyPrelme event to prevent input from the physical keyboard.
*
NOTE:
*
options can be set only when value is set to true, in which case a character counter is displayed below the text box.
*
This attribute must be used together with maxLength.
*
The character counter is displayed in this format: Number of characters entered/Character limit.
*
It is visible when the number of characters entered is greater than the character limit multiplied by the threshold percentage value.
*
If options is not set, the text box border and character counter subscript turn red
* when the number of characters entered exceeds the limit.
*
If value is set to true and options is set, the text box border and character counter subscript turn red
* and the text box shakes when the number of characters entered reaches the limit,
* provided that the value of thresholdPercentage is valid.
*
If highlightBorder is set to false, the text box border does not turn red.
*
By default, highlightBorder is set to true.
*
The character counter is not displayed for text boxes in inline or password input style.
*
NOTE:
*
This attribute is not available for the inline input style.
*
The default value is 28fp on wearable devices.
*
NOTE:
*
This attribute is not available for the inline input style.
*
NOTE:
*
This attribute is not available for the inline input style.
*
NOTE:
*
For the string type, numeric string values with optional units,
* for example, "10" or "10fp", are supported.
*
For the setting to take effect, this attribute must be used together with maxFontSize
* and maxLines (when the component is in editing state in the inline input style), or layout constraint settings.
*
When the adaptive font size is used, the fontSize settings do not take effect.
*
NOTE:
*
For the string type, numeric string values with optional units,
* for example, "10" or "10fp", are supported.
*
For the setting to take effect, this attribute must be used together with minFontSize
* and maxLines (when the component is in editing state in the inline input style), or layout constraint settings.
*
When the adaptive font size is used, the fontSize settings do not take effect.
*
NOTE: *
NOTE:
*
This attribute does not take effect for the password input mode.
*
NOTE:
*
If the value specified is a percentage or 0, the default value is used.
*
For the string type, numeric string values with optional units,
* for example, "10" or "10fp", are supported.
*
If the value specified is a negative value, the text is compressed.
*
A negative value too small may result in the text being compressed to 0
* and no content being displayed.
*
NOTE:
*
If the value is less than or equal to 0, the line height is not limited and the font size is adaptive.
*
If the value is of the number type, the unit fp is used.
*
For the string type, numeric string values with optional units, for example, "10" or "10fp", are supported.
*
NOTE:
*
When autofill is used, these rules are transparently transmitted to Password Vault for generating a new password.
*
NOTE:
*
This attribute is not available when type is set to an enum value that indicates the password input mode,
* such as Password, NEW_PASSWORD, or NUMBER_PASSWORD.
*
NOTE:
*
This API has effect only when the input type is set to Password, NEWPASSWORD, or NUMBERPASSWORD mode.
*
It does not work in other modes.
*
When in password mode, there may be inconsistency between the backend state of the text box
* and the frontend application's state management variables.
*
This can cause issues with the icon at the end of the password text box.
*
To avoid such issues, use the onSecurityStateChange callback to sync the states.
*
NOTE:
*
It returns true if the text is inserted; returns false otherwise.
*
This callback is not triggered for pre-edit or candidate word operations.
*
It is available only for system input methods.
*
NOTE:
*
It is available only for system input methods.
*
NOTE:
*
It returns true if the text is deleted; returns false otherwise.
*
This callback is not called for text preview.
*
It is available only for system input methods.
*
NOTE:
*
It is available only for system input methods.
*
NOTE:
*
Preview text is in a temporary state and does not support text interception.
*
As such, it does not trigger onWillInsert, onDidInsert, onWillDelete, or onDidDelete callbacks.
*