From ac16a819d0cbef4c60fc748b67d0a16d3229ea6b Mon Sep 17 00:00:00 2001 From: Caoruihong Date: Sun, 6 Jul 2025 22:45:07 +0800 Subject: [PATCH 1/2] add java-like overload accessibility apis Signed-off-by: Caoruihong Change-Id: I4cf00e2e1ca4e8b631ee2c7f6906128af4a99e1d --- api/@internal/component/ets/common.d.ts | 130 +++++++++++++++++++++--- 1 file changed, 118 insertions(+), 12 deletions(-) diff --git a/api/@internal/component/ets/common.d.ts b/api/@internal/component/ets/common.d.ts index f1c6d2eaab..00d614240b 100644 --- a/api/@internal/component/ets/common.d.ts +++ b/api/@internal/component/ets/common.d.ts @@ -29929,11 +29929,29 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'12','1.2':'20'} - * @arkts 1.1&1.2 + * @since 12 */ accessibilityGroup(value: boolean): T; + /** + * Sets whether to enable accessibility grouping. + * + *

NOTE + *
Whether to enable accessibility grouping. When accessibility grouping is enabled, + *
the component and all its children are treated as a single selectable unit, and the accessibility + *
service will no longer focus on the individual child components.

+ * + * @param { boolean } value - set group with accessibility, default value is false. + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityGroupWithValue(value: boolean): T; + /** * Sets whether to enable accessibility grouping. * @@ -29955,11 +29973,32 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'14','1.2':'20'} - * @arkts 1.1&1.2 + * @since 14 */ accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions): T; + /** + * Sets accessibilityGroup + * + * @param { boolean } isGroup - set group with accessibility + * @param { AccessibilityOptions } accessibilityOptions - accessibilityOptions for accessibility + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityGroupWithIsGroupAccessibilityOptions(isGroup: boolean, accessibilityOptions: AccessibilityOptions): T; + + /** + * Sets accessibilityGroup + * + * @since 20 + */ + overload accessibilityGroup { accessibilityGroupWithValue, accessibilityGroupWithIsGroupAccessibilityOptions } + /** * Sets the accessibility text. * @@ -29990,11 +30029,24 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'12','1.2':'20'} - * @arkts 1.1&1.2 + * @since 12 */ accessibilityText(value: string): T; + /** + * Sets accessibilityText + * + * @param { string } value - set accessibility text + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityTextWithValue(value: string): T; + /** * Sets accessibility next focus id * @param { string } nextId - set component next accessibility focus id @@ -30061,11 +30113,32 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'12','1.2':'20'} - * @arkts 1.1&1.2 + * @since 12 */ accessibilityText(text: Resource): T; + /** + * Sets accessibilityText + * + * @param { Resource } text - set accessibility text + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityTextWithText(text: Resource): T; + + /** + * Sets accessibilityText + * + * @since 20 + */ + overload accessibilityText { accessibilityTextWithValue, accessibilityTextWithText } + + /** * Sets accessibility role,role indicates the custom type of the component * @param { AccessibilityRoleType } role - set accessibility component type @@ -30147,11 +30220,24 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'12','1.2':'20'} - * @arkts 1.1&1.2 + * @since 12 */ accessibilityDescription(value: string): T; + /** + * Sets accessibilityDescription + * + * @param { string } value - set description of accessibility + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityDescriptionWithValue(value: string): T; + /** * Sets accessibilityDescription * @@ -30170,11 +30256,31 @@ declare class CommonMethod { * @crossplatform * @form * @atomicservice - * @since arkts {'1.1':'12','1.2':'20'} - * @arkts 1.1&1.2 + * @since 12 */ accessibilityDescription(description: Resource): T; + /** + * Sets accessibilityDescription + * + * @param { Resource } description - set description of accessibility + * @returns { T } + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @crossplatform + * @form + * @atomicservice + * @since 20 + * @arkts 1.2 + */ + accessibilityDescriptionWithDescription(description: Resource): T; + + /** + * Sets accessibilityDescription + * + * @since 20 + */ + overload accessibilityDescription { accessibilityDescriptionWithValue, accessibilityDescriptionWithDescription } + /** * Sets the accessibility level. * This property determines whether the component can be recognized by accessibility services. -- Gitee From 8b7577c33fb81ce8d7a077915c0c9b15c09fe379 Mon Sep 17 00:00:00 2001 From: Caoruihong Date: Fri, 15 Aug 2025 03:14:01 +0800 Subject: [PATCH 2/2] use more concise overload names Signed-off-by: Caoruihong Change-Id: I5565862c8aedc612a4bbfdafeee90f1b60ae195a --- api/@internal/component/ets/common.d.ts | 72 ++++++++++++++++--------- 1 file changed, 48 insertions(+), 24 deletions(-) diff --git a/api/@internal/component/ets/common.d.ts b/api/@internal/component/ets/common.d.ts index 00d614240b..7970ba0618 100644 --- a/api/@internal/component/ets/common.d.ts +++ b/api/@internal/component/ets/common.d.ts @@ -29950,7 +29950,7 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityGroupWithValue(value: boolean): T; + accessibilityGroupWithValue(value: boolean | undefined): T; /** * Sets whether to enable accessibility grouping. @@ -29978,10 +29978,21 @@ declare class CommonMethod { accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions): T; /** - * Sets accessibilityGroup + * Sets whether to enable accessibility grouping. + * + *

NOTE + *
If accessibility grouping is enabled and the component does not contain a universal text attribute + *
or an accessibility text attribute, the system will concatenate the universal text attributes of + *
its child components to form a merged text for the component. If a child component lacks a universal + *
text attribute, it will be ignored in the concatenation process. + * + *
When accessibilityPreferred is set to true, the system will prioritize concatenating the accessibility + *
text attributes of the child components to form the merged text. If a child component lacks an + *
accessibility text attribute, the system will continue to concatenate its universal text attribute. + *
If a child component lacks both, it will be ignored.

* - * @param { boolean } isGroup - set group with accessibility - * @param { AccessibilityOptions } accessibilityOptions - accessibilityOptions for accessibility + * @param { boolean } isGroup - set group with accessibility, default value is false. + * @param { AccessibilityOptions } config - accessibilityOptions for accessibility, default value is false. * @returns { T } * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform @@ -29990,14 +30001,13 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityGroupWithIsGroupAccessibilityOptions(isGroup: boolean, accessibilityOptions: AccessibilityOptions): T; + accessibilityGroupWithConfig(isGroup: boolean | undefined, config: AccessibilityOptions | undefined): T; /** - * Sets accessibilityGroup - * * @since 20 + * @arkts 1.2 */ - overload accessibilityGroup { accessibilityGroupWithValue, accessibilityGroupWithIsGroupAccessibilityOptions } + overload accessibilityGroup { accessibilityGroupWithValue, accessibilityGroupWithConfig }; /** * Sets the accessibility text. @@ -30034,9 +30044,11 @@ declare class CommonMethod { accessibilityText(value: string): T; /** - * Sets accessibilityText - * - * @param { string } value - set accessibility text + * Sets the accessibility text. + * When a component does not contain a text attribute, you can use this API to set an accessibility + * text attribute, so that accessibility services can announce the specified content for the component. + * + * @param { string } value - set accessibility text, default value is "". * @returns { T } * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform @@ -30045,7 +30057,7 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityTextWithValue(value: string): T; + accessibilityTextOfStringType(value: string | undefined): T; /** * Sets accessibility next focus id @@ -30118,8 +30130,13 @@ declare class CommonMethod { accessibilityText(text: Resource): T; /** - * Sets accessibilityText - * + * Sets the accessibility text. + *

NOTE + * If a component has both text content and accessibility text, only the accessibility text is announced. + *
If a component is grouped for accessibility purposes but lacks both text content and accessibility + *
text, the screen reader will concatenate text from its child components (depth-first traversal). + *
To prioritize accessibility text concatenation, set accessibilityPreferred in accessibilityGroup. + *

* @param { Resource } text - set accessibility text * @returns { T } * @syscap SystemCapability.ArkUI.ArkUI.Full @@ -30129,14 +30146,13 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityTextWithText(text: Resource): T; + accessibilityTextOfResourceType(text: Resource | undefined): T; /** - * Sets accessibilityText - * * @since 20 + * @arkts 1.2 */ - overload accessibilityText { accessibilityTextWithValue, accessibilityTextWithText } + overload accessibilityText { accessibilityTextOfStringType, accessibilityTextOfResourceType }; /** @@ -30227,7 +30243,7 @@ declare class CommonMethod { /** * Sets accessibilityDescription * - * @param { string } value - set description of accessibility + * @param { string } value - set description of accessibility, default value is "". * @returns { T } * @syscap SystemCapability.ArkUI.ArkUI.Full * @crossplatform @@ -30236,7 +30252,7 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityDescriptionWithValue(value: string): T; + accessibilityDescriptionOfStringType(value: string | undefined): T; /** * Sets accessibilityDescription @@ -30263,6 +30279,15 @@ declare class CommonMethod { /** * Sets accessibilityDescription * + * with support for resource references using Resource. + * This property provides additional context or explanation for the component, + * helping users understand the action or function it performs. + *

NOTE: + *
Reference resource of the accessibility description. You can specify further explanation + *
of the current component, for example, possible operation consequences, especially those that + *
cannot be learned from component attributes and accessibility text. If a component contains + *
both text information and the accessibility description, the text is read first and then the + *
accessibility description, when the component is selected.

* @param { Resource } description - set description of accessibility * @returns { T } * @syscap SystemCapability.ArkUI.ArkUI.Full @@ -30272,14 +30297,13 @@ declare class CommonMethod { * @since 20 * @arkts 1.2 */ - accessibilityDescriptionWithDescription(description: Resource): T; + accessibilityDescriptionOfResourceType(description: Resource | undefined): T; /** - * Sets accessibilityDescription - * * @since 20 + * @arkts 1.2 */ - overload accessibilityDescription { accessibilityDescriptionWithValue, accessibilityDescriptionWithDescription } + overload accessibilityDescription { accessibilityDescriptionOfStringType, accessibilityDescriptionOfResourceType }; /** * Sets the accessibility level. -- Gitee