在 Flutter 开发中，标签（Tag）是筛选分类、状态标记、兴趣选择的高频场景（如电商筛选、内容分类、用户兴趣标签、订单状态标记）。原生无统一标签组件，重复开发易导致样式混乱、单选 / 多选逻辑冗余、交互体验不一致。本文封装的CommonTagWidget整合 “单选 / 多选自由切换 + 可关闭标签 + 全样式自定义 + 深色模式适配” 四大核心能力，支持流式布局、自定义图标、禁用状态适配，一行代码调用，覆盖 90%+ 标签使用场景，彻底解决重复编码痛点！

一、核心优势（精准解决开发痛点）

✅ 单选 / 多选自由切换：内置单选（互斥选中）、多选（任意组合）逻辑，内部维护选中状态，无需外部手动管理✅ 样式全自定义：标签颜色（纯色 / 渐变）、圆角、边框、文本样式、选中效果均可配置，适配不同设计风格✅ 可关闭标签支持：内置标签删除功能，点击关闭图标自动移除标签并回调，适配筛选已选标签场景✅ 布局自适应：基于Wrap实现流式布局，自动换行，支持最大行数限制 + 滚动，适配不同屏幕宽度✅ 交互体验优化：选中状态实时反馈、点击区域扩大、禁用状态样式适配、关闭事件隔离（避免触发标签点击）✅ 深色模式兼容：所有可视化参数自动适配亮色 / 深色主题，无需额外配置✅ 边界条件鲁棒：初始选中标签去重、禁用标签过滤、标签文本 / ID 唯一性校验，避免逻辑异常

二、核心配置速览（关键参数一目了然）

三、生产级完整代码（可直接复制，开箱即用）

dart

import 'package:flutter/material.dart';

/// 标签模型（支持ID+文本，避免文本重复导致选中状态混乱）
class TagModel {
  final String id; // 标签唯一标识（核心）
  final String text; // 标签显示文本
  final dynamic extra; // 扩展字段（如标签颜色、图标等）

  const TagModel({
    required this.id,
    required this.text,
    this.extra,
  });

  // 快捷创建纯文本标签
  factory TagModel.fromText(String text) => TagModel(id: text, text: text);
}

/// 通用标签组件（支持单选/多选、可关闭、样式自定义）
class CommonTagWidget extends StatefulWidget {
  // 必选参数（支持文本/实体类标签）
  final List<dynamic> tags; // 标签列表（String/TagModel）
  final Function(List<dynamic>) onSelected; // 选中回调（返回选中标签：String/TagModel）

  // 功能配置
  final bool isMultiple; // 是否多选（默认true）
  final List<dynamic> initialSelected; // 初始选中标签（String/TagModel）
  final bool isClosable; // 标签是否可关闭（默认false）
  final int? maxLines; // 最大行数（默认无限制，超出滚动）
  final List<dynamic> disableTags; // 禁用标签列表（String/TagModel）

  // 样式配置
  final double tagHeight; // 标签高度（默认32px）
  final double borderRadius; // 标签圆角（默认16px）
  final Color bgColor; // 未选中背景色（默认浅灰）
  final Color selectedBgColor; // 选中背景色（默认蓝色）
  final Gradient? bgGradient; // 未选中渐变背景（优先级高于bgColor）
  final Gradient? selectedBgGradient; // 选中渐变背景（优先级高于selectedBgColor）
  final Color borderColor; // 未选中边框色（默认透明）
  final Color selectedBorderColor; // 选中边框色（默认蓝色）
  final TextStyle textStyle; // 未选中文本样式
  final TextStyle selectedTextStyle; // 选中文本样式
  final double horizontalPadding; // 水平内边距（默认16px）
  final double spacing; // 标签水平间距（默认8px）
  final double runSpacing; // 标签垂直间距（默认8px）

  // 扩展配置
  final Widget? prefixIcon; // 标签前缀图标（所有标签统一）
  final Widget? suffixIcon; // 标签后缀图标（所有标签统一）
  final Color closeIconColor; // 关闭图标颜色（默认灰色）
  final bool adaptDarkMode; // 适配深色模式（默认true）

  const CommonTagWidget({
    super.key,
    required this.tags,
    required this.onSelected,
    // 功能配置
    this.isMultiple = true,
    this.initialSelected = const [],
    this.isClosable = false,
    this.maxLines,
    this.disableTags = const [],
    // 样式配置
    this.tagHeight = 32.0,
    this.borderRadius = 16.0,
    this.bgColor = const Color(0xFFF5F5F5),
    this.selectedBgColor = Colors.blue,
    this.bgGradient,
    this.selectedBgGradient,
    this.borderColor = Colors.transparent,
    this.selectedBorderColor = Colors.blue,
    this.textStyle = const TextStyle(fontSize: 14, color: Colors.black87),
    this.selectedTextStyle = const TextStyle(fontSize: 14, color: Colors.white),
    this.horizontalPadding = 16.0,
    this.spacing = 8.0,
    this.runSpacing = 8.0,
    // 扩展配置
    this.prefixIcon,
    this.suffixIcon,
    this.closeIconColor = Colors.grey,
    this.adaptDarkMode = true,
  })  : assert(tags.isNotEmpty, "标签列表不可为空"),
        assert(_validateTagType(tags), "标签仅支持String或TagModel类型"),
        assert(_validateTagType(initialSelected), "初始选中标签仅支持String或TagModel类型"),
        assert(_validateTagType(disableTags), "禁用标签仅支持String或TagModel类型");

  // 校验标签类型合法性
  static bool _validateTagType(List<dynamic> list) {
    return list.every((item) => item is String || item is TagModel);
  }

  @override
  State<CommonTagWidget> createState() => _CommonTagWidgetState();
}

class _CommonTagWidgetState extends State<CommonTagWidget> {
  late List<dynamic> _selectedTags; // 当前选中标签（统一转为TagModel）
  late List<TagModel> _tagList; // 标准化标签列表（统一为TagModel）
  late List<String> _disableTagIds; // 禁用标签ID列表

  @override
  void initState() {
    super.initState();
    // 标准化标签列表（String→TagModel）
    _tagList = widget.tags.map((tag) => _normalizeTag(tag)).toList();
    // 标准化禁用标签ID
    _disableTagIds = widget.disableTags.map((tag) => _normalizeTag(tag).id).toList();
    // 初始化选中标签（去重+单选限制）
    _selectedTags = widget.initialSelected
        .map((tag) => _normalizeTag(tag))
        .where((tag) => _tagList.any((t) => t.id == tag.id)) // 仅保留存在于标签列表的项
        .toSet()
        .toList();
    // 单选模式下最多保留1个选中项
    if (!widget.isMultiple && _selectedTags.length > 1) {
      _selectedTags = [_selectedTags.first];
    }
  }

  @override
  void didUpdateWidget(covariant CommonTagWidget oldWidget) {
    super.didUpdateWidget(oldWidget);
    // 标签列表变化时更新标准化列表+选中状态
    if (widget.tags != oldWidget.tags) {
      _tagList = widget.tags.map((tag) => _normalizeTag(tag)).toList();
      _disableTagIds = widget.disableTags.map((tag) => _normalizeTag(tag).id).toList();
      // 过滤选中标签（仅保留当前标签列表中存在的项）
      _selectedTags = _selectedTags
          .where((tag) => _tagList.any((t) => t.id == (tag as TagModel).id))
          .toList();
      // 回调外部更新后的选中状态
      widget.onSelected(_convertResult(_selectedTags));
    }
  }

  /// 标准化标签（String→TagModel，TagModel直接返回）
  TagModel _normalizeTag(dynamic tag) {
    if (tag is TagModel) return tag;
    if (tag is String) return TagModel.fromText(tag);
    throw ArgumentError("标签仅支持String或TagModel类型");
  }

  /// 转换返回结果（TagModel→原始类型：String/TagModel）
  List<dynamic> _convertResult(List<TagModel> tags) {
    // 若原始标签是String，返回text；否则返回TagModel
    final isStringTag = widget.tags.first is String;
    return isStringTag ? tags.map((tag) => tag.text).toList() : tags;
  }

  /// 检查标签是否禁用
  bool _isTagDisabled(TagModel tag) => _disableTagIds.contains(tag.id);

  /// 检查标签是否选中
  bool _isTagSelected(TagModel tag) => _selectedTags.any((t) => (t as TagModel).id == tag.id);

  /// 深色模式颜色适配
  Color _adaptDarkMode(Color lightColor, Color darkColor) {
    if (!widget.adaptDarkMode) return lightColor;
    return MediaQuery.platformBrightnessOf(context) == Brightness.dark
        ? darkColor
        : lightColor;
  }

  /// 标签点击逻辑
  void _onTagTap(TagModel tag) {
    if (_isTagDisabled(tag)) return; // 禁用标签不响应点击

    setState(() {
      if (widget.isMultiple) {
        // 多选：切换选中状态
        final isSelected = _isTagSelected(tag);
        if (isSelected) {
          _selectedTags.removeWhere((t) => (t as TagModel).id == tag.id);
        } else {
          _selectedTags.add(tag);
        }
      } else {
        // 单选：替换选中标签
        _selectedTags = [tag];
      }
      // 回调外部选中结果（转换为原始类型）
      widget.onSelected(_convertResult(_selectedTags));
    });
  }

  /// 标签关闭逻辑（阻止事件冒泡）
  void _onTagClose(TagModel tag, TapDownDetails details) {
    details.stopPropagation(); // 避免触发标签点击
    if (_isTagDisabled(tag)) return;

    setState(() {
      // 从标签列表移除
      _tagList.removeWhere((t) => t.id == tag.id);
      // 从选中列表移除
      _selectedTags.removeWhere((t) => (t as TagModel).id == tag.id);
      // 回调外部更新后的状态
      widget.onSelected(_convertResult(_selectedTags));
    });
  }

  /// 构建单个标签
  Widget _buildSingleTag(TagModel tag) {
    final isSelected = _isTagSelected(tag);
    final isDisabled = _isTagDisabled(tag);

    // 适配深色模式颜色
    final adaptedBgColor = _adaptDarkMode(
      isSelected ? widget.selectedBgColor : widget.bgColor,
      isSelected ? const Color(0xFF3A5F88) : const Color(0xFF4A4A4A),
    );
    final adaptedBorderColor = _adaptDarkMode(
      isSelected ? widget.selectedBorderColor : widget.borderColor,
      isSelected ? Colors.blueAccent : const Color(0xFF555555),
    );
    final adaptedTextStyle = isSelected
        ? widget.selectedTextStyle.copyWith(
            color: _adaptDarkMode(
              widget.selectedTextStyle.color ?? Colors.white,
              Colors.white70,
            ),
          )
        : widget.textStyle.copyWith(
            color: isDisabled
                ? _adaptDarkMode(const Color(0xFFCCCCCC), const Color(0xFF777777))
                : _adaptDarkMode(
                    widget.textStyle.color ?? Colors.black87,
                    Colors.white70,
                  ),
          );
    final adaptedCloseColor = _adaptDarkMode(widget.closeIconColor, Colors.grey[400]!);

    // 背景装饰（渐变优先）
    final background = isSelected
        ? (widget.selectedBgGradient ?? BoxDecoration(color: adaptedBgColor))
        : (widget.bgGradient ?? BoxDecoration(color: adaptedBgColor));
    final decoration = BoxDecoration(
      gradient: background is Gradient ? background : null,
      color: background is BoxDecoration ? background.color : adaptedBgColor,
      border: Border.all(
        color: isDisabled ? _adaptDarkMode(const Color(0xFFEEEEEE), const Color(0xFF555555)) : adaptedBorderColor,
        width: 1.0,
      ),
      borderRadius: BorderRadius.circular(widget.borderRadius),
    );

    // 标签内容（前缀图标+文本+后缀图标+关闭图标）
    final List<Widget> tagContent = [];
    if (widget.prefixIcon != null) {
      tagContent.add(widget.prefixIcon!);
      tagContent.add(const SizedBox(width: 6));
    }
    tagContent.add(
      Text(
        tag.text,
        style: adaptedTextStyle,
        maxLines: 1,
        overflow: TextOverflow.ellipsis,
      ),
    );
    if (widget.suffixIcon != null) {
      tagContent.add(const SizedBox(width: 6));
      tagContent.add(widget.suffixIcon!);
    }
    if (widget.isClosable) {
      tagContent.add(const SizedBox(width: 6));
      tagContent.add(
        GestureDetector(
          onTapDown: (details) => _onTagClose(tag, details),
          child: Icon(
            Icons.close,
            size: 16,
            color: adaptedCloseColor,
          ),
        ),
      );
    }

    return GestureDetector(
      onTap: isDisabled ? null : () => _onTagTap(tag),
      child: Container(
        height: widget.tagHeight,
        padding: EdgeInsets.symmetric(horizontal: widget.horizontalPadding),
        decoration: decoration,
        alignment: Alignment.center,
        child: Row(
          mainAxisSize: MainAxisSize.min,
          children: tagContent,
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    // 构建标签列表
    final tagWidgets = _tagList.map((tag) => _buildSingleTag(tag)).toList();

    // 流式布局（支持最大行数限制）
    Widget tagWrap = Wrap(
      spacing: widget.spacing,
      runSpacing: widget.runSpacing,
      children: tagWidgets,
    );

    // 限制最大行数（超出滚动）
    if (widget.maxLines != null) {
      tagWrap = SizedBox(
        height: widget.tagHeight * widget.maxLines! + widget.runSpacing * (widget.maxLines! - 1),
        child: SingleChildScrollView(
          physics: const BouncingScrollPhysics(),
          child: tagWrap,
        ),
      );
    }

    return tagWrap;
  }
}

四、四大高频场景实战示例（直接复制可用）

场景 1：兴趣标签选择（多选 + 自定义样式）

适用场景：用户画像、内容推荐、个性化设置等需要多选兴趣标签的场景

dart

class InterestTagPage extends StatefulWidget {
  @override
  State<InterestTagPage> createState() => _InterestTagPageState();
}

class _InterestTagPageState extends State<InterestTagPage> {
  // 兴趣标签列表（纯文本）
  final List<String> _interestTags = [
    "科技", "财经", "娱乐", "体育", "健康", "教育", "汽车", "旅行", "美食", "摄影"
  ];
  List<String> _selectedInterests = ["科技", "体育"]; // 选中的兴趣标签

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("选择兴趣标签")),
      body: Padding(
        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              "选择您感兴趣的标签（可多选）",
              style: TextStyle(fontSize: 16, fontWeight: FontWeight.w500),
            ),
            const SizedBox(height: 16),
            CommonTagWidget(
              tags: _interestTags,
              isMultiple: true,
              initialSelected: _selectedInterests,
              onSelected: (selected) {
                setState(() => _selectedInterests = selected.cast<String>());
                debugPrint("选中兴趣标签：$selected");
                // 实际业务：提交用户兴趣标签到服务端
              },
              // 自定义样式
              tagHeight: 36,
              borderRadius: 18,
              bgColor: const Color(0xFFF8F8F8),
              selectedBgColor: Colors.blueAccent,
              borderColor: const Color(0xFFE0E0E0),
              selectedBorderColor: Colors.blueAccent,
              textStyle: const TextStyle(fontSize: 14, color: Color(0xFF333333)),
              selectedTextStyle: const TextStyle(fontSize: 14, color: Colors.white),
              spacing: 12,
              runSpacing: 12,
              adaptDarkMode: true,
            ),
            const SizedBox(height: 24),
            // 选中标签预览
            Text("已选：${_selectedInterests.join("、")}", style: const TextStyle(color: Colors.grey)),
            const SizedBox(height: 24),
            SizedBox(
              width: double.infinity,
              child: ElevatedButton(
                onPressed: () => Navigator.pop(context),
                child: const Text("保存选择"),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

场景 2：筛选已选标签（可关闭 + 浅色样式）

适用场景：电商筛选、内容过滤等需要展示并移除已选筛选条件的场景

dart

class FilterTagPage extends StatefulWidget {
  @override
  State<FilterTagPage> createState() => _FilterTagPageState();
}

class _FilterTagPageState extends State<FilterTagPage> {
  late List<String> _selectedFilters; // 已选筛选条件

  @override
  void initState() {
    super.initState();
    _selectedFilters = ["价格<500", "热销", "新品"];
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("商品筛选")),
      body: Padding(
        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text("已选筛选条件", style: TextStyle(fontSize: 14, color: Color(0xFF999999))),
            const SizedBox(height: 8),
            CommonTagWidget(
              tags: _selectedFilters,
              isMultiple: true,
              isClosable: true, // 开启关闭功能
              onSelected: (selected) {
                setState(() => _selectedFilters = selected.cast<String>());
                debugPrint("当前筛选条件：$selected");
                // 实际业务：根据选中标签重新筛选商品列表
              },
              // 浅色筛选标签样式
              tagHeight: 32,
              borderRadius: 16,
              bgColor: const Color(0xFFE6F7FF),
              selectedBgColor: const Color(0xFFE6F7FF), // 选中/未选中样式一致
              borderColor: Colors.blueAccent.withOpacity(0.3),
              selectedBorderColor: Colors.blueAccent.withOpacity(0.3),
              textStyle: const TextStyle(fontSize: 13, color: Colors.blueAccent),
              selectedTextStyle: const TextStyle(fontSize: 13, color: Colors.blueAccent),
              closeIconColor: Colors.blueAccent,
              spacing: 8,
              runSpacing: 8,
            ),
            const SizedBox(height: 24),
            // 更多筛选选项（示例）
            const Text("价格区间", style: TextStyle(fontSize: 16, fontWeight: FontWeight.w500)),
            const SizedBox(height: 8),
            // 价格筛选标签（禁用"价格>5000"）
            CommonTagWidget(
              tags: ["价格<100", "价格100-500", "价格500-1000", "价格>5000"],
              disableTags: ["价格>5000"],
              onSelected: (selected) => debugPrint("价格筛选：$selected"),
              tagHeight: 30,
              borderRadius: 4,
              bgColor: Colors.white,
              selectedBgColor: Colors.orangeAccent,
              borderColor: const Color(0xFFE0E0E0),
            ),
          ],
        ),
      ),
    );
  }
}

场景 3：订单状态筛选（单选 + 前缀图标）

适用场景：订单列表、物流状态等需要单选状态标签的场景

dart

class OrderStatusTagPage extends StatelessWidget {
  // 订单状态标签（使用TagModel，支持扩展字段）
  final List<TagModel> _statusTags = [
    TagModel(id: "all", text: "全部", extra: Icons.all_inclusive),
    TagModel(id: "pending_pay", text: "待支付", extra: Icons.payment),
    TagModel(id: "pending_ship", text: "待发货", extra: Icons.local_shipping),
    TagModel(id: "pending_receive", text: "待收货", extra: Icons.receipt),
    TagModel(id: "completed", text: "已完成", extra: Icons.check_circle),
    TagModel(id: "cancelled", text: "已取消", extra: Icons.cancel),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("订单列表")),
      body: Padding(
        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 16),
        child: Column(
          children: [
            CommonTagWidget(
              tags: _statusTags,
              isMultiple: false, // 单选模式
              initialSelected: [_statusTags.first],
              onSelected: (selected) {
                final selectedTag = selected.first as TagModel;
                debugPrint("选中订单状态：${selectedTag.id} - ${selectedTag.text}");
                // 实际业务：根据状态筛选订单列表
              },
              // 单选标签样式
              tagHeight: 34,
              borderRadius: 4,
              bgColor: Colors.white,
              selectedBgColor: Colors.orangeAccent,
              borderColor: const Color(0xFFE0E0E0),
              selectedBorderColor: Colors.orangeAccent,
              textStyle: const TextStyle(fontSize: 14, color: Color(0xFF666666)),
              selectedTextStyle: const TextStyle(fontSize: 14, color: Colors.white),
              spacing: 10,
              // 前缀图标（使用标签扩展字段的图标）
              prefixIcon: Icon(
                (_statusTags.first.extra as IconData),
                size: 14,
                color: Colors.grey,
              ),
            ),
            const SizedBox(height: 16),
            // 订单列表组件
            const Expanded(child: Center(child: Text("订单列表内容"))),
          ],
        ),
      ),
    );
  }
}

场景 4：渐变背景标签（营销标签 + 最大行数）

适用场景：活动营销、内容分类等需要视觉突出的标签场景

dart

class GradientTagPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("营销标签示例")),
      body: Padding(
        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              "热门活动标签（最大2行）",
              style: TextStyle(fontSize: 16, fontWeight: FontWeight.w500),
            ),
            const SizedBox(height: 16),
            CommonTagWidget(
              tags: [
                "限时特惠", "满减活动", "新品首发", "会员专享", "买一送一",
                "满199减50", "包邮到家", "积分兑换", "爆款直降", "百亿补贴",
                "限时秒杀", "优惠券领取", "免息分期"
              ],
              isMultiple: true,
              maxLines: 2, // 限制最大2行，超出滚动
              onSelected: (selected) => debugPrint("选中营销标签：$selected"),
              // 渐变背景样式
              tagHeight: 40,
              borderRadius: 20,
              bgGradient: const LinearGradient(
                colors: [Color(0xFFF6F9FF), Color(0xFFE6F7FF)],
                begin: Alignment.centerLeft,
                end: Alignment.centerRight,
              ),
              selectedBgGradient: const LinearGradient(
                colors: [Colors.blueAccent, Colors.blue],
                begin: Alignment.centerLeft,
                end: Alignment.centerRight,
              ),
              borderColor: Colors.transparent,
              textStyle: const TextStyle(fontSize: 14, color: Color(0xFF333333)),
              selectedTextStyle: const TextStyle(fontSize: 14, color: Colors.white),
              spacing: 10,
              runSpacing: 10,
            ),
          ],
        ),
      ),
    );
  }
}

五、核心封装技巧（复用成熟设计思路）

1. 标签标准化设计：新增TagModel统一管理标签（ID + 文本 + 扩展字段），避免文本重复导致选中状态混乱，支持更复杂的标签场景（如不同标签不同颜色）。
2. 状态内置管理：选中状态由组件内部维护，外部仅需关注回调结果，单选 / 多选逻辑通过isMultiple一键切换，减少外部状态管理成本。
3. 事件隔离处理：关闭标签事件通过onTapDown+stopPropagation阻止冒泡，避免触发标签点击，交互更精准（如点击关闭图标不会选中标签）。
4. 样式分层适配：支持纯色 / 渐变背景、选中 / 未选中 / 禁用状态样式独立配置，深色模式通过统一方法适配，避免样式碎片化。
5. 边界条件鲁棒性：
   • 标签类型校验（仅支持 String/TagModel），避免类型错误；
   • 初始选中标签自动过滤（仅保留存在于标签列表的项）；
   • 单选模式自动去重（最多保留 1 个选中项）。
6. 布局灵活扩展：基于Wrap实现流式布局，支持最大行数限制 + 滚动，适配小屏设备和多标签场景。

六、避坑指南（解决 90% 开发痛点）

1. 标签唯一性：务必保证标签 ID 唯一（纯文本标签 ID = 文本），否则会出现 “选中 A 标签，B 标签也被选中” 的异常（如两个 “新品” 标签）。
2. 初始选中校验：initialSelected中的标签必须存在于tags列表中，否则会被自动过滤，不生效。
3. 可关闭标签注意：isClosable=true时，标签会从组件内部的_tagList中移除，若需外部同步标签列表，需在onSelected回调中更新。
4. 最大行数适配：设置maxLines后，标签高度需固定（tagHeight），否则滚动高度计算异常（如高度动态变化导致行数超出限制）。
5. 深色模式兼容：自定义颜色时必须通过_adaptDarkMode方法适配，避免浅色文本配浅色背景（如深色模式下白色文本配白色背景）。
6. 禁用标签处理：禁用标签不可点击 / 关闭，样式自动灰度化，需确保disableTags中的标签 ID 存在于tags列表中。
7. 渐变背景优先级：bgGradient/selectedBgGradient优先级高于bgColor/selectedBgColor，设置渐变后纯色背景不生效。

欢迎大家加入[开源鸿蒙跨平台开发者社区](https://openharmonycrossplatform.csdn.net)，一起共建开源鸿蒙跨平台生态。