From 97ebeaba09678a806bf831d097d09da0345f01d4 Mon Sep 17 00:00:00 2001 From: qlxie Date: Mon, 16 Jun 2025 15:34:43 +0800 Subject: [PATCH] =?UTF-8?q?=E7=84=A6=E7=82=B9=E6=96=87=E6=A1=A3=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0=E4=BF=AE=E6=94=B904?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: qlxie --- .../arkui-ts/ts-universal-attributes-focus.md | 12 ++++---- .../ui/arkts-common-events-focus-event.md | 28 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md b/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md index 3f4c775292d..e14bcec3593 100644 --- a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md +++ b/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md @@ -10,7 +10,7 @@ > > - 组件主动获取焦点不受窗口焦点的控制。 > -> - 焦点开发参考[焦点开发指南](../../../ui/arkts-common-events-focus-event.md)。 +> - 焦点基础概念和开发参考[焦点开发指南](../../../ui/arkts-common-events-focus-event.md)。 ## focusable @@ -48,7 +48,7 @@ tabIndex(index: number): T | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | -| index | number | 是 | 自定义组件tab键走焦能力。若有配置了tabIndex大于0的组件，则tab键走焦只会在tabIndex大于0的组件内按照tabIndex的值从小到大并循环依次走焦。若没有配置tabIndex大于0的组件，则tabIndex等于0的组件按照组件预设的走焦规则走焦。
[UiExtension](../js-apis-arkui-uiExtension.md)组件未适配tabIndex，在含有[UiExtension](../js-apis-arkui-uiExtension.md)组件的页面使用tabIndex会导致走焦错乱。
- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素。
- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。
默认值：0
**说明：**
tabIndex与focusScopeId不能混用。 +| index | number | 是 | 自定义组件tab键走焦能力。若有配置了tabIndex大于0的组件，则tab键走焦只会在tabIndex大于0的组件内按照tabIndex的值从小到大并循环依次走焦。若没有配置tabIndex大于0的组件，则tabIndex等于0的组件按照组件预设的走焦规则走焦。
[UiExtension](../js-apis-arkui-uiExtension.md)组件未适配tabIndex，在含有[UiExtension](../js-apis-arkui-uiExtension.md)组件的层级页面使用tabIndex会导致走焦错乱。
- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素。
- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。
默认值：0
**说明：**
tabIndex与focusScopeId不能混用。 | **返回值：** @@ -61,7 +61,7 @@ tabIndex(index: number): T defaultFocus(value: boolean): T -设置当前组件是否为当前页面上的默认焦点。 +设置当前组件是否为当前层级页面上的默认焦点。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 @@ -71,7 +71,7 @@ defaultFocus(value: boolean): T | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| value | boolean | 是 | 设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。
默认值：false
**说明：**
值为true则表示为默认焦点，值为false时无效。
若页面内无任何组件设置defaultFocus(true)，API version 11及之前，页面的默认焦点是当前页面上首个可获焦的非容器组件，API version 11之后，页面的默认焦点就是页面的根容器。
若某页面内有多个组件设置了defaultFocus(true)，则以组件树深度遍历找到的第一个组件为默认焦点。 | +| value | boolean | 是 | 设置当前组件是否为当前层级页面上的默认焦点，仅在初次创建的层级页面第一次进入时生效。
默认值：false
**说明：**
值为true则表示为默认焦点，值为false时无效。
若层级页面内无任何组件设置defaultFocus(true)，API version 11及之前，层级页面的默认焦点是当前层级页面上首个可获焦的非容器组件，API version 11之后，层级页面的默认焦点就是层级页面的根容器。
若某层级页面内有多个组件设置了defaultFocus(true)，则以组件树深度遍历找到的第一个组件为默认焦点。 | **返回值：** @@ -349,7 +349,7 @@ nextFocus(nextStep: Optional\): T ### 示例1（设置组件获焦和走焦的效果） -该示例通过配置defaultFocus可以使绑定的组件成为页面创建后首次获焦的焦点，配置groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点，配置focusOnTouch可以使绑定的组件点击后立即获焦。 +该示例通过配置defaultFocus可以使绑定的组件成为层级页面创建后首次获焦的焦点，配置groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点，配置focusOnTouch可以使绑定的组件点击后立即获焦。 ```ts // focusTest.ets @@ -426,7 +426,7 @@ struct FocusableExample { this.inputValue = value }) .width(156) - .defaultFocus(true) // 该TextInput组件为页面的初始默认焦点 + .defaultFocus(true) // 该TextInput组件为层级页面的初始默认焦点 Button('Group3') .width(165) .height(40) diff --git a/zh-cn/application-dev/ui/arkts-common-events-focus-event.md b/zh-cn/application-dev/ui/arkts-common-events-focus-event.md index cd46692a9ea..35f4d9a882f 100644 --- a/zh-cn/application-dev/ui/arkts-common-events-focus-event.md +++ b/zh-cn/application-dev/ui/arkts-common-events-focus-event.md @@ -68,7 +68,7 @@ struct FocusActiveExample { **根容器** -根容器是层级页面内的概念，当某个层级页面首次创建并展示时，根据层级页面的特性，焦点会立即被该页面抢占。此时，该层级页面所在焦点链的末端节点将成为默认焦点，而这个默认焦点通常位于该层级页面的根容器上。 +根容器是层级页面内的概念，当某个层级页面首次创建并展示时，根据层级页面的特性，焦点会立即被该层级页面抢占。此时，该层级页面所在焦点链的末端节点将成为默认焦点，而这个默认焦点通常位于该层级页面的根容器上。 在缺省状态下，层级页面的默认焦点位于其根容器上，但开发者可以通过defaultFocus属性来自定义这一行为。 @@ -114,7 +114,7 @@ Shift+Tab键：与Tab键具有相反的焦点转移效果。 - 组件删除：当处于焦点状态的组件被删除时，焦点框架首先尝试将焦点转移到相邻的兄弟组件上，遵循先向后再向前的顺序。若所有兄弟组件均不可获焦，则焦点将释放，并通知其父组件进行焦点处理。 - 属性变更：若将处于焦点状态的组件的focusable或enabled属性设置为false，或者将visibility属性设置为不可见，系统将自动转移焦点至其他可获焦组件，转移方式与1中相同。 -- 层级页面切换：当发生层级页面切换时，如从一个页面跳转到另一个页面，当前页面的焦点将自动释放，新页面可能会根据预设逻辑自动获得焦点。 +- 层级页面切换：当发生层级页面切换时，如从一个层级页面跳转到另一个层级页面，当前层级页面的焦点将自动释放，新层级页面可能会根据预设逻辑自动获得焦点。 - Web组件初始化：对于Web组件，当其被创建时，若其设计需要立即获得焦点（如某些弹出框或输入框），则可能触发焦点转移至该Web组件，其行为属于组件自身的行为逻辑，不属于焦点框架的规格范围。 ### 走焦算法 @@ -637,13 +637,13 @@ struct TabStopExample { ## 默认焦点 -### 页面的默认焦点 +### 层级页面的默认焦点 ```ts defaultFocus(value: boolean) ``` -设置当前组件是否为当前页面上的默认焦点。 +设置当前组件是否为当前层级页面上的默认焦点。 ```ts @@ -710,7 +710,7 @@ struct morenjiaodian { 上述示例包含以下2步： -- 在第三个Button组件上设置了defaultFocus(true)，进入页面后第三个Button默认获焦，显示为绿色。 +- 在第三个Button组件上设置了defaultFocus(true)，进入层级页面后第三个Button默认获焦，显示为绿色。 - 按下Tab键，触发走焦，第三个Button正处于获焦状态，会出现焦点框。 ### 容器的默认焦点 @@ -719,7 +719,7 @@ struct morenjiaodian { **defaultFocus与FocusPriority的区别** -[defaultFocus](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9)是用于指定页面首次展示时的默认获焦节点，[FocusPriority](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focuspriority12)是用于指定某个容器首次获焦时其子节点的获焦优先级。上述两个属性在某些场景同时配置时行为未定义，例如下面的场景，页面首次展示无法同时满足defaultFocus获焦和高优先级组件获焦。 +[defaultFocus](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9)是用于指定层级页面首次展示时的默认获焦节点，[FocusPriority](../reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focuspriority12)是用于指定某个容器首次获焦时其子节点的获焦优先级。上述两个属性在某些场景同时配置时行为未定义，例如下面的场景，层级页面首次展示无法同时满足defaultFocus获焦和高优先级组件获焦。 示例 @@ -738,23 +738,23 @@ struct Index { } ``` -### 页面/容器整体获焦时的焦点链 +### 层级页面/容器整体获焦时的焦点链 **整体获焦与非整体获焦** -- 整体获焦是页面/容器自身作为焦点链的叶节点获焦，获焦后再把焦点链叶节点转移到子孙组件。例如，页面切换、Navigation组件中的路由切换、焦点组走焦、容器组件主动调用requestFocusById等。 +- 整体获焦是层级页面/容器自身作为焦点链的叶节点获焦，获焦后再把焦点链叶节点转移到子孙组件。例如，层级页面切换、Navigation组件中的路由切换、焦点组走焦、容器组件主动调用requestFocusById等。 - 非整体获焦是某个组件作为焦点链叶节点获焦，导致其祖先节点跟着获焦。例如TextInput组件主动获取焦点、Tab键在非焦点组场景下走焦等。 **整体获焦的焦点链形成** -1.页面首次获焦： +1.层级页面首次获焦： - 焦点链叶节点为配置了defaultFocus的节点。 -- 未配置defaultFocus时，焦点停留在页面的根容器上。 +- 未配置defaultFocus时，焦点停留在层级页面的根容器上。 -2.页面非首次获焦：由上次获焦的节点获焦。 +2.层级页面非首次获焦：由上次获焦的节点获焦。 3.获焦链上存在配置了获焦优先级的组件和容器： @@ -807,7 +807,7 @@ struct RequestFocusExample { 上述示例包含以下2步： -- 进入页面，按下Tab键触发走焦，第一个Button获焦，焦点框样式为紧贴边缘的蓝色细框。 +- 进入层级页面，按下Tab键触发走焦，第一个Button获焦，焦点框样式为紧贴边缘的蓝色细框。 - 按下Tab键，走焦到第二个Button，焦点框样式为远离边缘的红色粗框。 ## 主动获焦/失焦 @@ -829,7 +829,7 @@ struct RequestFocusExample { ```ts clearFocus(): void ``` - 清除焦点，将焦点强制转移到页面根容器节点，焦点链路上其他节点失焦。 + 清除焦点，将焦点强制转移到层级页面根容器节点，焦点链路上其他节点失焦。 - 使用focusControl中的方法 ```ts @@ -932,7 +932,7 @@ tabIndex(index: number) > **说明：** > > 不能同时设置tabIndex与focusScopeId属性。 -> 不建议在页面中通过单独设置组件的tabIndex属性为负数来控制获焦能力，可以使用focusable属性代替。 +> 不建议在层级页面中通过单独设置组件的tabIndex属性为负数来控制获焦能力，可以使用focusable属性代替。 ```ts @Entry -- Gitee