Flutter实现OverlayEntry列表动态高度并限制最大高度

阿华AIGC实验室

2026-6-16

解决方案：实现动态高度+最大高度限制的Overlay搜索结果列表

核心思路是放弃给Positioned设置固定高度，改用ConstrainedBox限制最大高度，结合ListView的shrinkWrap: true实现自适应，同时保证超出时可滚动。以下是具体实现步骤和代码示例：

关键布局结构调整

用ConstrainedBox包裹列表，设置maxHeight为屏幕高度的0.5倍，替代Positioned的固定高度
保留ListView的shrinkWrap: true，让列表根据结果数量自动计算高度
给ListView设置合适的滚动物理效果，确保内容超出限制时可滚动，不足时无多余滚动条
用Material包裹列表，解决Overlay中组件缺少Material上下文的样式问题

完整代码示例

import 'package:flutter/material.dart';

class SearchOverlayDemo extends StatefulWidget {
  const SearchOverlayDemo({super.key});

  @override
  State<SearchOverlayDemo> createState() => _SearchOverlayDemoState();
}

class _SearchOverlayDemoState extends State<SearchOverlayDemo> {
  final LayerLink _layerLink = LayerLink();
  OverlayEntry? _overlayEntry;
  List<String> _searchResults = [];
  final TextEditingController _searchController = TextEditingController();

  // 模拟API获取搜索结果
  void _fetchSearchResults(String keyword) {
    setState(() {
      if (keyword.isEmpty) {
        _searchResults = [];
      } else {
        // 生成0-10条模拟数据
        _searchResults = List.generate(
          keyword.length > 10 ? 10 : keyword.length,
          (index) => "搜索结果 ${index + 1}",
        );
      }
    });
    _updateOverlay();
  }

  void _updateOverlay() {
    // 先移除旧的Overlay
    _overlayEntry?.remove();
    _overlayEntry = null;

    if (_searchResults.isEmpty) return;

    _overlayEntry = OverlayEntry(
      builder: (context) => CompositedTransformFollower(
        link: _layerLink,
        showWhenUnlinked: false,
        offset: const Offset(0, 8), // 搜索栏下方的间距
        child: ConstrainedBox(
          constraints: BoxConstraints(
            maxHeight: MediaQuery.of(context).size.height * 0.5,
          ),
          child: Material(
            borderRadius: BorderRadius.circular(8),
            elevation: 4,
            child: ListView.builder(
              shrinkWrap: true,
              physics: const ClampingScrollPhysics(), // 内容超限时滚动，否则无滚动效果
              padding: EdgeInsets.zero,
              itemCount: _searchResults.length,
              itemBuilder: (context, index) {
                return ListTile(
                  title: Text(_searchResults[index]),
                  onTap: () {
                    // 处理选中逻辑
                    _searchController.text = _searchResults[index];
                    _overlayEntry?.remove();
                    _overlayEntry = null;
                  },
                );
              },
            ),
          ),
        ),
      ),
    );

    Overlay.of(context).insert(_overlayEntry!);
  }

  @override
  void dispose() {
    _overlayEntry?.remove();
    _searchController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("搜索Overlay示例")),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            // 搜索栏（绑定LayerLink）
            CompositedTransformTarget(
              link: _layerLink,
              child: TextField(
                controller: _searchController,
                onChanged: _fetchSearchResults,
                decoration: const InputDecoration(
                  hintText: "输入关键词搜索...",
                  border: OutlineInputBorder(),
                  prefixIcon: Icon(Icons.search),
                ),
              ),
            ),
            // 下方表单（被Overlay覆盖）
            const SizedBox(height: 20),
            const TextField(decoration: InputDecoration(hintText: "表单输入项1")),
            const SizedBox(height: 12),
            const TextField(decoration: InputDecoration(hintText: "表单输入项2")),
            const SizedBox(height: 12),
            const TextField(decoration: InputDecoration(hintText: "表单输入项3")),
          ],
        ),
      ),
    );
  }
}