一、插件介绍

string_scanner_test是一个基于Flutter的字符串扫描测试工具，专为OpenHarmony跨平台开发优化。该工具提供了强大的字符串解析、标记化和验证功能，适用于需要对字符串进行精确控制和操作的场景，如解析器开发、配置文件处理、代码生成等。

主要功能特性：

1. 基础字符串扫描：提供精确的字符串定位、字符匹配和正则表达式扫描功能
2. 行扫描器：支持基于行和列的位置跟踪，便于处理多行文本
3. 范围扫描器：支持在特定文本范围内进行扫描，并提供源位置信息
4. 错误处理：内置完善的错误检测和报告机制
5. Unicode支持：全面支持Unicode字符和代理对

OpenHarmony适配亮点：

• 兼容OpenHarmony API 9+及以上版本
• 优化了UI组件以适配鸿蒙系统特性
• 支持通过AtomGit进行自定义修改版本的依赖管理
• 提供完整的测试用例，便于开发者验证功能

二、环境配置

系统要求

• OpenHarmony API 9+
• Flutter SDK 3.0+
• Dart SDK 2.19.6+

依赖引入

由于该三方库为自定义修改版本，需要以git形式通过AtomGit引入：

在项目的pubspec.yaml文件中添加以下依赖配置：

dependencies:
  flutter:
    sdk: flutter
  string_scanner:
    git:
      url: "https://atomgit.com/flutter/packages"
      path: "packages/string_scanner/string_scanner"

然后执行flutter pub get命令获取依赖：

flutter pub get

三、API使用示例

1. 基础字符串扫描（StringScanner）

StringScanner是最基础的扫描器类，用于在字符串中进行精确的定位和匹配操作。

import 'package:string_scanner/string_scanner.dart';

void basicStringScannerExample() {
  // 创建一个字符串扫描器
  StringScanner scanner = StringScanner('foo bar baz');
  
  // 检查扫描器状态
  print('是否完成扫描: ${scanner.isDone}'); // false
  print('当前位置: ${scanner.position}'); // 0
  print('剩余字符串: ${scanner.rest}'); // "foo bar baz"
  
  // 使用正则表达式扫描
  if (scanner.scan(RegExp(r'f(..)'))) {
    print('匹配到: ${scanner.lastMatch![0]}'); // "foo"
    print('捕获组1: ${scanner.lastMatch![1]}'); // "oo"
    print('扫描后位置: ${scanner.position}'); // 3
  }
  
  // 跳过空格
  scanner.scan(' ');
  
  // 扫描特定字符串
  if (scanner.scan('bar')) {
    print('匹配到bar，当前位置: ${scanner.position}'); // 7
  }
  
  // 检查是否匹配但不移动位置
  if (scanner.matches(' baz')) {
    print('下一个匹配: " baz"');
  }
  
  // 期望匹配特定字符串，否则抛出异常
  scanner.expect(' baz');
  print('扫描完成后位置: ${scanner.position}'); // 11
  print('是否完成扫描: ${scanner.isDone}'); // true
}

2. 行扫描器（LineScanner）

LineScanner继承自StringScanner，增加了行和列的位置跟踪功能，便于处理多行文本。

import 'package:string_scanner/string_scanner.dart';

void lineScannerExample() {
  // 创建行扫描器
  LineScanner scanner = LineScanner('Hello\nWorld\nOpenHarmony');
  
  print('初始行: ${scanner.line}, 初始列: ${scanner.column}'); // 0, 0
  
  // 扫描第一行
  scanner.expect('Hello');
  print('扫描Hello后 - 行: ${scanner.line}, 列: ${scanner.column}'); // 0, 5
  
  // 扫描换行符
  scanner.scan('\n');
  print('扫描换行符后 - 行: ${scanner.line}, 列: ${scanner.column}'); // 1, 0
  
  // 扫描第二行部分内容
  scanner.scan('Wor');
  print('扫描Wor后 - 行: ${scanner.line}, 列: ${scanner.column}'); // 1, 3
  
  // 设置位置
  scanner.position = 13; // 移动到第二行末尾
  print('设置位置后 - 行: ${scanner.line}, 列: ${scanner.column}'); // 1, 5
}

3. 范围扫描器（SpanScanner）

SpanScanner提供了在特定文本范围内进行扫描的功能，并能提供源位置信息，适用于需要精确错误报告的场景。

import 'package:source_span/source_span.dart';
import 'package:string_scanner/string_scanner.dart';

void spanScannerExample() {
  // 创建源文件
  final file = SourceFile.fromString(
    '完整文本内容\n需要扫描的内容: Flutter on OpenHarmony\n其他内容',
    url: 'example.txt'
  );
  
  // 定义需要扫描的范围
  final startOffset = file.getText(0).indexOf('Flutter');
  final endOffset = file.getText(0).indexOf('OpenHarmony') + 'OpenHarmony'.length;
  
  // 在指定范围内创建扫描器
  SpanScanner scanner = SpanScanner.within(file.span(startOffset, endOffset));
  
  print('扫描范围内容: ${scanner.string}'); // "Flutter on OpenHarmony"
  
  // 扫描并获取范围信息
  scanner.scan('Flutter');
  if (scanner.lastSpan != null) {
    print('Flutter 起始位置: ${scanner.lastSpan!.start.offset}');
    print('Flutter 结束位置: ${scanner.lastSpan!.end.offset}');
    print('Flutter 行: ${scanner.lastSpan!.start.line}, 列: ${scanner.lastSpan!.start.column}');
  }
  
  // 保存当前状态
  final state = scanner.state;
  
  // 继续扫描
  scanner.scan(' on ');
  scanner.scan('OpenHarmony');
  
  // 获取从保存状态到当前位置的范围
  final fullSpan = scanner.spanFrom(state);
  print('完整匹配范围: ${fullSpan.text}'); // " on OpenHarmony"
}

4. 错误处理

StringScanner提供了完善的错误处理机制，当预期的匹配失败时会抛出异常。

import 'package:string_scanner/string_scanner.dart';

void errorHandlingExample() {
  StringScanner scanner = StringScanner('Hello World');
  
  try {
    // 尝试匹配不存在的内容
    scanner.expect('Hi');
  } catch (e) {
    print('捕获到错误: $e');
  }
  
  try {
    // 先扫描部分内容
    scanner.scan('Hello');
    // 然后尝试匹配错误的内容
    scanner.expect('Universe');
  } catch (e) {
    print('捕获到错误: $e');
    print('错误发生位置: ${scanner.position}');
  }
}

四、完整示例应用

以下是一个完整的Flutter应用示例，展示如何在鸿蒙平台上使用string_scanner_test工具：

import 'package:flutter/material.dart';
import 'package:string_scanner/string_scanner.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'String Scanner Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const ScannerDemoPage(),
    );
  }
}

class ScannerDemoPage extends StatefulWidget {
  const ScannerDemoPage({Key? key}) : super(key: key);

  @override
  State<ScannerDemoPage> createState() => _ScannerDemoPageState();
}

class _ScannerDemoPageState extends State<ScannerDemoPage> {
  String _input = 'Flutter on OpenHarmony 2025';
  String _result = '';

  void _scanString() {
    StringScanner scanner = StringScanner(_input);
    StringBuffer buffer = StringBuffer();

    buffer.writeln('=== 扫描结果 ===');
    buffer.writeln('输入字符串: $_input');
    buffer.writeln('初始位置: ${scanner.position}');

    // 扫描Flutter
    if (scanner.scan('Flutter')) {
      buffer.writeln('匹配到: Flutter, 位置: ${scanner.position}');
    }

    // 跳过空格和on
    scanner.scan(' on ');
    buffer.writeln('跳过空格和on后位置: ${scanner.position}');

    // 扫描OpenHarmony
    if (scanner.scan('OpenHarmony')) {
      buffer.writeln('匹配到: OpenHarmony, 位置: ${scanner.position}');
    }

    // 跳过空格
    scanner.scan(' ');

    // 扫描年份
    if (scanner.scan(RegExp(r'\d{4}'))) {
      buffer.writeln('匹配到年份: ${scanner.lastMatch![0]}, 位置: ${scanner.position}');
    }

    buffer.writeln('扫描完成，是否结束: ${scanner.isDone}');

    setState(() {
      _result = buffer.toString();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('String Scanner Demo'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            TextField(
              decoration: const InputDecoration(
                labelText: '输入字符串',
                border: OutlineInputBorder(),
              ),
              onChanged: (value) {
                setState(() {
                  _input = value;
                });
              },
              controller: TextEditingController(text: _input),
            ),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: _scanString,
              child: const Text('执行扫描'),
            ),
            const SizedBox(height: 16),
            Expanded(
              child: SingleChildScrollView(
                child: Text(_result),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

五、总结

string_scanner_test是一个功能强大的字符串扫描测试工具，通过OpenHarmony的适配，为Flutter开发者提供了在鸿蒙平台上进行精确字符串操作的能力。其主要优势包括：

1. 精确的位置控制：提供了丰富的API来精确定位和操作字符串
2. 多维度扫描支持：从基础字符到行、列位置，再到范围扫描，满足不同场景需求
3. 完善的错误处理：便于开发健壮的字符串处理逻辑
4. 良好的Unicode支持：确保在处理各种语言文本时的正确性

通过本文的介绍，您应该已经了解了如何在OpenHarmony平台上引入和使用string_scanner_test工具。无论是开发解析器、处理配置文件还是进行其他字符串操作，这个工具都能为您提供强大的支持。

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net