HarmonyKit | 鸿蒙新特性 API：文本统计 util.TextEncoder 字节计数与多维分析

引言

文本统计是开发者在处理字符串时频繁需要的工具——文件大小按字节计算而非字符数，代码行数统计，中英文混合文本的字符粒度分析，这些需求在标准编辑器中往往分散在不同菜单里。HarmonyKit 的文本统计工具将六个维度的统计聚合在一个页面内，实时响应用户输入，并利用鸿蒙的 util.TextEncoder API 进行精确的 UTF-8 字节计数。本文深入剖析文本统计的实现机制，包括正则表达式的 CJK 字符检测策略、字节编码的内部原理以及 @Builder 统计卡片的设计模式。

util.TextEncoder：鸿蒙的字节编码 API

鸿蒙的 util.TextEncoder 属于 @kit.ArkTS 工具包，提供了字符串到字节数组的编码能力。在使用前需要显式引入：

import { util } from '@kit.ArkTS';

TextEncoder 的构造函数接受编码名称作为参数。对于文本统计场景，UTF-8 是最合理的选择——它是 Web 和大多数现代系统的标准编码，也是字节计数的通用基准。创建编码器实例并编码文本只需要两行代码：

let encoder = new util.TextEncoder('utf-8');
this.byteCount = encoder.encodeInto(this.input).length;

encodeInto 方法接受一个字符串，返回 Uint8Array 类型的字节数组。数组的 length 属性即该字符串在 UTF-8 编码下占用的字节数。UTF-8 是一种变长编码：ASCII 字符（英文、数字、标点）占 1 个字节，中文汉字占 3 个字节，某些特殊符号（如 emoji）可能占 4 个字节。这解释了为什么"文本统计"工具中的字节数通常大于字符数。

TextEncoder 与 TextDecoder 的配对使用

在 HarmonyKit 的 Base64Utils 中，TextEncoder 和 TextDecoder 是配对使用的：

import { util } from '@kit.ArkTS';

export class Base64Utils {
  static encode(input: string): string {
    let encoder = new util.TextEncoder('utf-8');
    let uint8Array: Uint8Array = encoder.encodeInto(input);
    let helper = new util.Base64Helper();
    return helper.encodeToStringSync(uint8Array);
  }

  static decode(input: string): string {
    let helper = new util.Base64Helper();
    let uint8Array: Uint8Array = helper.decodeSync(input);
    let decoder = util.TextDecoder.create('utf-8');
    return decoder.decodeToString(uint8Array);
  }
}

这里展示了鸿蒙 util 模块的完整编码生态：TextEncoder 负责字符串→字节数组（编码），TextDecoder.create() 负责字节数组→字符串（解码），Base64Helper 负责字节数组↔Base64 字符串。这三者构成了一个完整的二进制数据与文本表示之间的转换管线。

值得注意的是 TextDecoder.create() 是一个工厂方法而非构造函数，返回 TextDecoder 实例。其 decodeToString 方法接受 Uint8Array 并返回解码后的字符串。这与 Web 标准的 TextDecoder API 保持一致——鸿蒙在设计 util 模块时刻意遵循了 Web 标准，降低了 Web 开发者的学习成本。

六维统计指标的实现

TextCounter 页面使用 @State 管理六个统计指标：

@State charCount: number = 0;
@State charNoSpace: number = 0;
@State byteCount: number = 0;
@State lineCount: number = 0;
@State wordCount: number = 0;
@State cnCharCount: number = 0;

doCount() 方法在每次输入变化时被调用，执行全量统计：

doCount() {
  if (!this.input) {
    this.charCount = 0;
    this.charNoSpace = 0;
    this.byteCount = 0;
    this.lineCount = 0;
    this.wordCount = 0;
    this.cnCharCount = 0;
    return;
  }
  this.charCount = this.input.length;
  this.charNoSpace = this.input.replace(/\s/g, '').length;
  let encoder = new util.TextEncoder('utf-8');
  this.byteCount = encoder.encodeInto(this.input).length;
  this.lineCount = this.input.split(/\r?\n/).length;
  this.wordCount = this.input.match(/[\w一-鿿]+/g)?.length ?? 0;
  this.cnCharCount = this.input.match(/[一-鿿]/g)?.length ?? 0;
}

空输入检查放在方法体最前面——如果输入为空字符串或 undefined，所有指标归零并直接返回，避免后续的正则和编码操作在空字符串上消耗资源。这种"早期返回"（early return）的防御式编程减少了不必要的计算。

字符数：String.length 的语义

this.charCount = this.input.length 是最直接的统计维度。JavaScript 的 String.length 返回的是 UTF-16 编码单元的数量，而非用户感知的"字符数"。对于 BMP（基本多语言平面，U+0000 到 U+FFFF）内的字符，每个字符占 1 个 UTF-16 编码单元，length 与视觉字符数一致；但对于补充平面字符（如 emoji \u{1F600}），每个字符占 2 个 UTF-16 编码单元（代理对），length 会是 2。

在 HarmonyKit 的使用场景中，字符串主要来自编程相关的文本输入，极少涉及 emoji，因此 length 的行为基本符合预期。但如果需要精确的"字位簇"（grapheme cluster）计数——例如正确处理带变音符号的拉丁字母或组合 emoji——则需要使用 Intl.Segmenter API（鸿蒙最新版本支持）。

不含空格字符数：正则排除空白

this.charNoSpace = this.input.replace(/\s/g, '').length;

\s 匹配所有空白字符，包括空格、制表符（tab）、换行符、回车符等。replace(/\s/g, '') 将所有空白替换为空字符串，然后取 length。全局标志 g 确保匹配所有出现的空白字符而非仅第一个。

这个统计指标对中文文本特别有意义——中文通常不在词之间加空格，所以 charNoSpace 约等于"实际内容长度"。而对英文来说，排除空格后得到的是"字母和标点总数"，接近传统打字机时代的"字符计数"。

字节数：UTF-8 编码的实现细节

TextEncoder.encodeInto() 的内部实现对应用透明，但理解其原理有助于解释为什么同一个字符在不同编码下的字节数不同。UTF-8 的编码规则：

1. U+0000 到 U+007F（ASCII）：1 字节，格式 0xxxxxxx
2. U+0080 到 U+07FF：2 字节，格式 110xxxxx 10xxxxxx
3. U+0800 到 U+FFFF（含 CJK 基本区）：3 字节，格式 1110xxxx 10xxxxxx 10xxxxxx
4. U+10000 到 U+10FFFF：4 字节，格式 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

因此，纯英文文本的字节数等于字符数，混合中英文文本的字节数约为"英文字符数 + 中文字符数*3"，纯中文文本的字节数约为字符数的 3 倍。文本统计工具中同时展示字符数和字节数，帮助开发者在估算存储空间和网络传输量时做出准确判断。

行数：跨平台换行符处理

this.lineCount = this.input.split(/\r?\n/).length;

正则 \r?\n 匹配两种换行符：Unix/Linux/macOS 使用的 \n（LF）和 Windows 使用的 \r\n（CR+LF）。\r? 表示回车符可选，\n 表示换行符必需。按此模式分割字符串后，数组的 length 就是行数。

需要特别注意的是：空字符串 split 后得到 ['']，length 为 1，这意味着空文本被计为 1 行——这在多数场景下是合理的，因为空文本仍然占据"一行"。但如果用户期望空文本显示 0 行，需要额外处理。当前的实现选择了与常见代码编辑器一致的"空文本 = 1 行"约定。

对于 split 可能产生的末尾空字符串问题（如文本以换行符结尾时），这里的行数计算是准确的——"hello\n".split(/\r?\n/) 返回 ['hello', '']，length 为 2，确实对应了 hello 和空行两行。

单词数：中英文混合的正则策略

this.wordCount = this.input.match(/[\w一-鿿]+/g)?.length ?? 0;

正则 [\w一-鿿]+ 定义了一个"单词"的匹配规则：

• \w：匹配英文单词字符（字母、数字、下划线），等价于 [a-zA-Z0-9_]
• 一-鿿：匹配 CJK 统一汉字区块（Unicode U+4E00 到 U+9FFF），覆盖常用中文汉字
• +：至少一个字符
• g：全局匹配，找出所有非重叠的匹配项

match 方法返回匹配结果数组或 null。当没有匹配项时，?.length 返回 undefined，通过 ?? 0 兜底为 0。这种链式空值处理在 ArkTS 中完全合法，比 if (result) result.length else 0 更简洁。

这个正则有一个设计决策值得讨论：中文串被视为一个"单词"。例如"你好世界"是一个单词，而"hello world"是两个单词。这是因为中文的词边界不像英文那样由空格界定，分词需要 NLP 工具的支持，远远超出正则表达式的能力范围。当前实现选择将连续的中文字符视为一个单元，是一种务实折中。

中文字符数：Unicode 范围检测

this.cnCharCount = this.input.match(/[一-鿿]/g)?.length ?? 0;

[一-鿿] 精确匹配单个 CJK 统一汉字。与单词数的正则不同，这里没有 + 量词——我们需要统计每个汉字个体，而非连续汉字段。\w 也从正则中移除了，因为中文统计只关心汉字，不关心中文文本中可能夹杂的英文或数字。

Unicode 的 CJK 统一汉字区块（U+4E00 到 U+9FFF）包含了 20,992 个码位，涵盖简体和繁体中文的常用汉字。但需要注意一些中文标点（如句号 。、引号 ""）不在这个范围内，而是位于 CJK 标点区块（U+3000 到 U+303F）。如果用户需要统计"包括中文标点在内的所有 CJK 字符"，正则应该扩展为 [　-鿿]。

@Builder StatCard：统计卡片的声明式组件

文本统计的结果使用 Grid 布局以 3 列展示六个统计维度。每个统计单元是一个使用 @Builder 定义的卡片：

@Builder
StatCard(label: string, value: string, color: string) {
  Column() {
    Text(value)
      .fontSize(20).fontWeight(FontWeight.Bold)
      .fontColor(color).fontFamily('monospace');

    Text(label)
      .fontSize(10).fontColor('#999').margin({ top: 4 });
  }
  .width('100%')
  .padding({ top: 14, bottom: 14 })
  .backgroundColor('#ffffff')
  .borderRadius(10);
}

选择 @Builder 而非 @Component 的原因有三：一是 StatCard 不需要生命周期管理（无 aboutToAppear 等需求）；二是 StatCard 不需要 @State 状态管理（所有数据通过参数传入）；三是 @Builder 的性能开销低于 @Component（构建函数内联而非创建独立组件节点）。

每个卡片接受三个参数：label（标签文本）、value（统计数值）和 color（数值颜色）。六个维度使用六种不同颜色，形成一目了然的视觉区分：

Grid() {
  GridItem() { this.StatCard('总字符数', String(this.charCount), '#007aff'); }
  GridItem() { this.StatCard('不含空格', String(this.charNoSpace), '#5856d6'); }
  GridItem() { this.StatCard('字节数', String(this.byteCount), '#34c759'); }
  GridItem() { this.StatCard('行数', String(this.lineCount), '#ff9500'); }
  GridItem() { this.StatCard('单词数', String(this.wordCount), '#af52de'); }
  GridItem() { this.StatCard('中文字符', String(this.cnCharCount), '#ff3b30'); }
}
.columnsTemplate('1fr 1fr 1fr')
.columnsGap(8).rowsGap(8)

columnsTemplate('1fr 1fr 1fr') 将网格等分为三列，每个格子占据 1/3 宽度。columnsGap 和 rowsGap 分别控制列间距和行间距。Grid 组件的尺寸管理会自动根据列数和间距计算每个 GridItem 的实际渲染尺寸。

TextArea 的 onChange 事件优化

文本统计工具的输入使用 TextArea 而非 TextInput，因为统计场景通常需要粘贴多行文本：

TextArea({ text: this.input, placeholder: '输入或粘贴文本...' })
  .height(180).fontSize(13).fontFamily('monospace')
  .backgroundColor('#ffffff').borderRadius(8).padding(12)
  .margin({ left: 16, right: 16 })
  .onChange((v: string) => {
    this.input = v;
    this.doCount();
  });

每次输入变化都触发 doCount() 进行全量统计——包括正则匹配和 TextEncoder 编码。对于数百字符的短文本，这个过程的耗时在微秒级别，用户感知不到延迟。但对于数千甚至数万字符的长文本，频繁的正则匹配可能影响输入流畅度。

优化策略可以考虑节流（throttle）——使用定时器延迟统计操作，在用户停止输入后（如 300ms 无新输入）才执行统计。但对于一个开发者工具而言，实时反馈的用户体验价值大于极罕见的性能开销。如果确实遇到性能问题，鸿蒙的 util.TextEncoder 本身就非常高效（底层是 C++ 实现），真正的瓶颈在正则匹配上——对于极长文本，可以先执行轻量的字符数和行数统计，将正则匹配的字节数和单词数延迟到用户停止输入后执行。

颜色系统的语义映射

六个统计卡片的颜色不是随意选取的，而是遵循了语义映射：

• 蓝色 #007aff：总字符数，最基础的统计维度，使用系统主色调
• 紫色 #5856d6：不含空格字符数，次重要的派生指标
• 绿色 #34c759：字节数，与存储/网络相关，"绿色"象征效率
• 橙色 #ff9500：行数，与代码结构相关
• 紫罗兰 #af52de：单词数
• 红色 #ff3b30：中文字符数，醒目的红色提醒这是一个细分指标

这些颜色与 HarmonyKit 中工具卡片使用的颜色系统一致（JSON 蓝色、Base64 绿色、URL 紫色、时间戳橙色、哈希红色、UUID 青色、颜色转换紫色、进制转换粉色、正则绿色、文本统计橙色），形成了统一的视觉语言。

TextEncoder 与性能考量

每次 doCount 调用都创建一个新的 TextEncoder 实例——这是否有性能问题？答案是：创建 TextEncoder 是一个轻量操作，分配的内部缓冲很小。在实际测试中，千次循环创建 TextEncoder 的总耗时仅几十毫秒。但对于高频调用场景（如每次按键都触发），可以将 encoder 缓存为类属性：

private encoder: util.TextEncoder = new util.TextEncoder('utf-8');

然后在 doCount 中直接使用 this.encoder.encodeInto(this.input).length。encodeInto 方法可以重复调用而不需要重新创建实例。但由于当前工具中 doCount 的调用频率远低于性能阈值，保留每次创建的方式使代码更简洁。

小结

文本统计工具是 HarmonyKit 中展示鸿蒙原生 API 能力的一个窗口。util.TextEncoder 提供了精确的 UTF-8 字节计数，正则表达式实现了灵活的多语言文本分析，@Builder 构建器让统计卡片既有结构化的数据展示又有轻盈的性能特征。六个维度的统计覆盖了从字符到字节、从行到词、从通用到中文的完整需求谱系。

从架构角度看，TextCounter 是整个工具集中唯一不需要 utils 工具类的页面——所有统计逻辑都内联在组件中。这是因为统计逻辑与 DOM/UI 的耦合度极高：统计结果直接驱动 UI 状态，没有跨页面复用的需求。这种"不需要抽象时就不抽象"的务实态度，是工程经验的体现。

TextEncoder 不止用于文本统计。在 Base64Utils 中也用它进行字符串到字节数组的编码，在 HashUtils 中类似的 buffer 操作也在底层依赖编码转换。它是鸿蒙 @kit.ArkTS 中最基础也最强大的 API 之一，理解它等于掌握了鸿蒙系统中文本与二进制数据之间的桥梁。

---

项目仓库：https://atomgit.com/VON-/harmony-kit