企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

Counter 是仓颉 ArkUI（方舟 UI 框架）信息展示类组件中专门用于数值增减计数的轻量组件，核心能力是围绕"增加"与"减少"两个按钮提供计数交互，并允许开发者通过事件回调接管数值变化逻辑。本文以 cj-information-display-counter.md 为主干，结合仓库中状态管理、公共类型定义等关联文档，完整梳理 Counter 的创建方式、属性控制、事件监听与可运行的实战示例，帮助开发者在鸿蒙应用（仓颉语言）中快速实现购物车数量、步进器等典型场景。

Counter 组件概述与典型应用场景

Counter 计数器组件提供相应的增加或者减少的计数操作。在仓颉 ArkUI 组件体系中，它归属于"信息展示"类别，与 Badge、Progress、Gauge 等组件并列，详见 ARKUI 组件索引。

从组件能力上看，Counter 由"+"与"−"两个操作按钮构成（文档在 enableInc 的参数说明中明确"true 表示 + 按钮使能"、"true 表示按钮使能"），中间内容区由开发者通过content闭包自定义渲染。它适合承载以下交互形态：

• 购物车中商品数量的增减；
• 表单中的步进输入（数量、份数、期数等）；
• 需要"加一/减一"且伴随按钮禁用边界的数值控件。

Counter 本身不维护计数值，只负责提供按钮与事件出口，数值的存储与更新完全由开发者在事件回调中自行完成，这与仓颉 ArkUI 声明式状态管理（@State）天然契合。

导入模块与创建组件

Counter 属于kit.ArkUI包，使用前需导入：

import kit.ArkUI.*

子组件能力

与仅支持单个子组件的 Badge 不同，Counter可以包含子组件。开发者可以在内容区自由放置 Text、Image、Row/Column 布局乃至自定义组件，用于展示当前计数值或装饰性内容。

init(content: () -> Unit)

创建计数器组件的入口为init：

public init(content: () -> Unit)

content是一个无参无返回的闭包，用于声明计数器组件的内容区。计数内容区可以是一个动态绑定的数值文本，例如将@State状态变量通过Text展示出来：

Counter() { Text(this.value.toString()) }

系统能力：SystemCapability.ArkUI.ArkUI.Full

起始版本：22

也就是说，该接口要求目标设备的系统能力集包含SystemCapability.ArkUI.ArkUI.Full，且起始版本为 22（HarmonyOS NEXT 基于 API 22 及以上的仓颉 ArkUI 环境）。关于系统能力（SysCap）的概念与运行时查询方式，可参考 SysCap（系统能力）。

通用属性与通用事件支持

Counter 对 ArkUI 通用能力支持情况如下：

• 通用属性：全部支持。尺寸（尺寸设置）、边框、背景、显隐控制、禁用控制、图形变换 等均可直接作用于 Counter；
• 通用事件：全部支持。包括 点击事件、触摸事件、挂载/卸载事件、焦点事件 等通用事件能力（完整清单见 通用事件）。

因此，开发者可以像对待普通组件一样对 Counter 使用.margin()、.height()、.width()等链式修饰，也可以为其注册点击等通用事件。需要特别注意的是：通用禁用控制（enable）与组件自身的 enableInc/enableDec 是两套独立能力，前者整体禁掉组件交互，后者仅针对单个按钮。

组件属性：增减按钮的使能与禁用

Counter 提供了两个组件专属属性，用于独立控制"减少按钮"和"增加按钮"的使能状态。

func enableDec(?Bool)：减少按钮控制

public func enableDec(value: ?Bool): This

系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

?Bool为仓颉可选类型，传None时按初始值 true 处理。传入false后，用户点击"减少"按钮不会触发onDec事件，按钮呈现禁用态。

func enableInc(?Bool)：增加按钮控制

public func enableInc(value: ?Bool): This

系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

典型用法：库存/上限边界控制

两个属性最常见的组合用法是配合业务边界：当计数值已达到上限时禁用enableInc，当计数值已降到最小值时禁用enableDec，从交互层面阻止越界：

Counter() { Text(this.value.toString()) } .enableInc(this.value < this.maxValue) .enableDec(this.value > this.minValue)

组件事件：onInc / onDec 数值增减回调

Counter 通过两个专属事件将"按钮被点击"转化为"数值增减"语义，回调类型为 VoidCallback。

func onDec(?VoidCallback)：数值减少事件

public func onDec(event: ?VoidCallback): This

系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

func onInc(?VoidCallback)：数值增加事件

public func onInc(event: ?VoidCallback): This

系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

VoidCallback 类型说明

VoidCallback在 基础类型定义 中定义，本质上是() -> Unit的类型别名：

public type VoidCallback = () -> Unit

也就是说，onInc/onDec接收的是一个无参无返回值的闭包。由于组件本身不保存计数值，回调中必须显式更新状态变量（如this.value++、this.value--），由状态驱动 UI 重新渲染。

完整示例代码：基于 @State 的计数器

以下是文档提供的可直接运行示例（<!-- run -->标注表示该代码片段可在仓库对应工程中直接运行验证），完整路径见 cj-information-display-counter.md：

package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* @Entry @Component class EntryView { @State var value: Int64 = 0 func build() { Column { Counter() {Text(this.value.toString())} .margin(100.0) .height(10.percent) .onInc({ => this.value++ }) .onDec({ => this.value-- }) } } }

该示例的关键点拆解：

1. @State var value: Int64 = 0：声明组件级状态变量作为计数值。@State是仓颉 ArkUI 中最基础的状态管理宏，被装饰的变量一旦变更，会触发其直接绑定的 UI 组件刷新（详见 @State宏：组件内状态）。注意状态变量的初始化要求本地初始化，且声明时必须指定类型（示例使用Int64）。
2. Counter() { Text(this.value.toString()) }：在内容区将状态变量渲染为文本，实现"计数显示"。
3. 链式属性：.margin(100.0)设置外边距，.height(10.percent)使用百分比单位设置高度（百分比写法与像素单位规则可参考 像素单位）。
4. 事件驱动状态更新：.onInc中执行this.value++，.onDec中执行this.value--。每一次按钮点击修改@State变量，UI 自动刷新出最新数值。

增强示例：带边界禁用与文本提示

在文档示例基础上，可进一步叠加enableInc/enableDec形成完整的生产级交互（合理推断自上述 API 组合，代码结构基于文档示例扩展）：

@Entry @Component class EntryView { @State var value: Int64 = 0 let maxValue: Int64 = 10 func build() { Column { Counter() { Text(this.value.toString()) } .margin(100.0) .height(10.percent) .enableInc(this.value < this.maxValue) .enableDec(this.value > 0) .onInc({ => if (this.value < this.maxValue) { this.value++ } }) .onDec({ => if (this.value > 0) { this.value-- } }) } } }

这样当value达到 10 时"+"按钮禁用，降为 0 时"−"按钮禁用，从 UI 与逻辑双重层面保证数值不越界。

进阶要点：状态管理、渲染控制与条件逻辑

• 状态驱动刷新：Counter 的数值显示依赖@State的观察与刷新机制。对Int64这类基础数据类型，框架可以完整观察到值的每一次变化（观察变化一节有对应说明）。若内容区需要更复杂的数据结构，则需配合@Observed/@Publish或ObservedArrayList<T>等能力。
• 内容区渲染控制：Counter 内容区同样支持仓颉 ArkUI 的渲染控制能力，例如用 if/else 按数值区间切换展示样式，或用 ForEach 渲染序列化内容。
• 事件可选性：onInc/onDec的参数类型为?VoidCallback（可空），初始值为空闭包{ => }，即不注册回调时点击按钮也不会报错，只是数值不会变化。实际使用中必须至少为需要生效的方向注册回调。
• 系统能力前提：Counter 全量 API 依赖SystemCapability.ArkUI.ArkUI.Full，在裁剪系统能力的设备上可能出现接口不可用的情况，可通过 canIUse 在运行期做能力探测后再决定是否渲染 Counter。

小结

Counter 是仓颉 ArkUI 中结构最精简的计数交互组件之一：创建（init+content）— 按钮控制（enableInc/enableDec）— 事件处理（onInc/onDec）— 状态驱动刷新（@State）四个环节构成了它的完整使用闭环。它不承担数据存储职责，而是把"加一/减一"的交互语义标准化，配合通用属性、通用事件的全量支持，能够灵活嵌入购物车、步进表单等各类计数场景。开发时牢记两点即可：数值必须通过事件回调回写状态变量，越界保护既要做逻辑判断（回调内判断）也要做视觉禁用（enableInc/enableDec），双管齐下才能保证体验完整。

• 文档
• 知识库
• 教程
• OpenHarmony