Flutter调用ensureSemantics时TextSpan生成错误href的问题

问题原因 #

启用SemanticsBinding.instance.ensureSemantics()后，带有TapGestureRecognizer的TextSpan会被语义系统默认识别为链接类型，自动生成href='#'的语义属性。点击这类元素时，除了触发onTap方法打开目标链接，还会触发默认的锚点跳转行为，导致页面栈异常（打开链接后随即返回首页）。

解决方案 #

以下两种方法均可保留语义支持（满足自动化测试需求），同时解决错误跳转问题：

方法1：给TextSpan配置自定义语义属性 #

直接修改TextSpan，通过semantics参数覆盖默认的href配置，同时保留链接语义标识：

TextSpan(
  text: 'Learn More',
  style: AppTextStyle.body.copyWith(
    color: Colors.blue,
    decoration: TextDecoration.underline,
  ),
  recognizer: TapGestureRecognizer()..onTap = () => launch(learnMoreUrl),
  semantics: const SemanticsProperties(
    href: null, // 移除默认生成的href='#'
    label: 'Learn More',
    isLink: true, // 保留链接语义，支持自动化测试识别
  ),
)

方法2：用WidgetSpan替换TextSpan，精确控制语义与手势 #

将可点击文本封装为WidgetSpan，通过Semantics组件手动定义语义规则，完全避免默认href的生成：

RichText(
  text: TextSpan(
    style: AppTextStyle.body.copyWith(color: AppColor.gray3),
    children: [
      TextSpan(text: subtitle),
      WidgetSpan(
        child: Semantics(
          label: 'Learn More',
          isLink: true,
          child: GestureDetector(
            onTap: () => launch(learnMoreUrl),
            child: Text(
              'Learn More',
              style: AppTextStyle.body.copyWith(
                color: Colors.blue,
                decoration: TextDecoration.underline,
              ),
            ),
          ),
        ),
      ),
    ],
  ),
)

内容的提问来源于stack exchange，提问作者Jennifer Hickey