PHP IntlPartsIterator 怎样保留文本片段的边界索引

我在需要把多语言文本切成词语、句子或可定位片段时，最容易先写出一段“只保存片段内容”的 foreach。这样展示看起来没问题，但后面一旦要把片段回写到原文、标记命中范围或定位解析错误，就会发现顺序编号不够用。PHP 的 IntlPartsIterator 正好提供了这个缺口：通过 IntlBreakIterator::getPartsIterator() 选择 KEY_LEFT 或 KEY_RIGHT，让迭代器的 key 保留片段边界索引。

官方地址：https://www.php.net/manual/en/class.intlpartsiterator.php

相关方法：https://www.php.net/manual/en/intlbreakiterator.getpartsiterator.php

如果后续需要回到原始文本的位置，默认的顺序编号不是索引；应使用 KEY_LEFT 保存片段起点，或使用 KEY_RIGHT 保存片段终点。这里的偏移量按 UTF-8 字节计算，不是“第几个字符”。

先把“片段”与“边界”分开理解

IntlBreakIterator 负责找到文本边界，例如词边界、句子边界或字符边界。它本身遍历时更像是在告诉你“下一个边界位于哪里”；IntlPartsIterator 是一个方便层，把两个相邻边界之间的文本直接作为 current() 返回。

因此，一次迭代至少有两份信息：current() 是片段内容，key() 是这个片段对应的索引。默认的 KEY_SEQUENTIAL 只给出 0、1、2 这样的连续编号，适合单纯展示列表；它不表达片段在原始字符串中的位置。

用 KEY_LEFT 保留每个片段的起点

最常用的做法是把 KEY_LEFT 传给 getPartsIterator()。此时 foreach 收到的 key 表示当前片段左侧边界的 UTF-8 字节偏移，片段内容仍由 value 提供。把 key 转成整数后，就可以把它作为原文中的起点保存下来。

setText($text);
$parts = [];

// KEY_LEFT 保留每个片段在原文中的左侧字节偏移。
foreach ($breakIterator->getPartsIterator(IntlPartsIterator::KEY_LEFT) as $leftOffset => $part) {
    $left = (int) $leftOffset;
    $parts[] = [
        'left' => $left,
        'text' => $part,
        // strlen 返回字节数，正好适合与 UTF-8 字节偏移配合。
        'right' => $left + strlen($part),
    ];
}

// 这里可以把 $parts 保存给高亮、审计或回写逻辑使用。
foreach ($parts as $item) {
    echo $item['left'] . ' - ' . $item['right'] . ': ' . $item['text'] . PHP_EOL;
}

这段写法的重点不是把片段打印出来，而是把 left 和 right 一起固化。right 使用片段的字节长度推导，因此与当前片段相邻的边界能够成对保存。若业务需要更严格地保留边界，也可以同时选择 KEY_RIGHT 做一次直接记录，见下一节。

需要结束位置时改用 KEY_RIGHT

KEY_RIGHT 让 key 表示当前片段右侧边界的字节偏移。它更适合“扫描到这里就结束”的场景，例如把片段交给另一个按原文区间工作的解析器。不要把它误认为片段长度：结束偏移是相对于整个原始文本的累计位置。

setText($text)) {
    throw new RuntimeException('无法准备文本边界迭代器');
}

$partsWithRightBoundary = [];
foreach ($breakIterator->getPartsIterator(IntlPartsIterator::KEY_RIGHT) as $rightOffset => $part) {
    $right = (int) $rightOffset;

    // 右边界减去当前片段的字节长度即可得到左边界。
    $left = $right - strlen($part);
    $partsWithRightBoundary[] = [
        'left' => $left,
        'right' => $right,
        'text' => $part,
    ];
}

// 记录区间时使用字节偏移；不要把它当作 mb_strlen 的字符位置。
foreach ($partsWithRightBoundary as $part) {
    echo '[' . $part['left'] . ', ' . $part['right'] . ') ' . $part['text'] . PHP_EOL;
}

我更倾向于在需要区间回溯的代码里统一保存半开区间 [left, right)。这种约定让相邻片段不会重复计算边界，也方便用 substr($text, $left, $right - $left) 从原文取回对应字节段；前提是两个偏移确实来自 ICU 的 UTF-8 边界。

顺序编号、左边界和右边界该怎么选

三个 key 模式并不是同一个索引换了名字，而是三个不同的消费契约。只渲染列表、只统计片段数量时，顺序编号最直观；需要从片段回到原文时，左边界通常更自然；已有下游函数以“扫描结束位置”作为游标时，右边界可以减少一次加法。

一个实用原则是：只要片段会离开当前 foreach 的作用域，就不要只保存 value。把 text、left、right 封装成一条记录，后续即使排序、过滤或合并，也不会把“第几个片段”和“原文第几个字节”混为一谈。

UTF-8 字节偏移不是字符下标

PHP 手册说明，IntlBreakIterator 的边界以 UTF-8 code unit，也就是字节计数表示。中文、emoji 和组合字符都可能让“一个视觉字符”占用多个字节。因此不要拿 key() 的结果直接传给按字符数理解位置的业务函数，也不要用 mb_substr() 把字节偏移当成字符下标。

如果业务接口需要字符位置，可以在明确的边界转换层把 UTF-8 字节区间换算成字符区间；如果接口只是对原始 UTF-8 字符串切片，则保留字节区间更直接。无论选择哪一种，都要让字段名带上 byte 或 char，避免调用方猜测。

上面的函数只表达一种边界契约：输入偏移必须是 UTF-8 字节边界。若外部请求传入的是字符序号，应先在输入层转换，不能让这个函数同时猜测两种单位。

intl 不可用或文本为空时的处理

IntlPartsIterator 依赖 PHP 的 intl 扩展以及 ICU 的断词能力。部署前应确认目标环境启用了 intl；运行时创建实例返回 null 时，要把它当作能力不可用处理，而不是继续调用方法。

文本为空时，应用应先决定空输入是“没有片段”还是“参数错误”。如果是搜索高亮，通常返回空片段集合即可；如果是必须有正文的解析任务，则在调用迭代器之前拒绝输入。这个业务判断不应该由 KEY_LEFT 或 KEY_RIGHT 代替。

还要注意，片段迭代可能包含空白、标点或其他边界之间的文本。若要过滤非词片段，请先把原始的 left/right/text 记录保存下来，再生成过滤视图；不要在第一次遍历时丢掉它们，否则后面无法解释原文区间为什么不连续。

常见问题

IntlPartsIterator 的 key 默认就是原文位置吗？不是。默认参数是 KEY_SEQUENTIAL，得到的是连续序号。需要位置时显式传入 KEY_LEFT 或 KEY_RIGHT。

KEY_LEFT 返回的是字符数还是字节数？是 UTF-8 字节偏移。中文和 emoji 会让字节数与字符数不同，字段名和后续切片函数应明确单位。

只保留片段内容，之后再用 strpos 查位置可以吗？不稳妥。重复片段会命中错误位置，过滤或合并后也难以恢复原始边界。若位置有业务意义，应在第一次迭代时保存 key 与片段内容。

什么时候应该使用 KEY_RIGHT？当下游逻辑天然以扫描结束位置或区间终点为游标时。否则保存左边界并用片段字节长度推导右边界通常更容易阅读。

结语

IntlPartsIterator 的价值不只是把边界之间的文字交给 foreach，而是把“内容”和“位置”放在同一次迭代里。默认顺序 key 适合展示；KEY_LEFT 适合保留起点；KEY_RIGHT 适合保留终点。只要在数据结构中同时标明 UTF-8 字节单位，并把 intl 不可用、空文本和过滤策略留在业务层处理，片段就能安全地回到原文上下文中。