#跟着若城学鸿蒙# UI组件篇-Filter及其属性

ArkUI的Filter组件提供了强大的多条件筛选功能，通过灵活的配置选项和回调机制，开发者可以轻松实现复杂的筛选需求。从API Version 10开始支持，并在后续版本中不断增强了功能，Filter组件已成为处理多维度数据筛选的理想选择。---以上。

Huang兄

638人浏览 · 2025-05-22 16:30:33

Huang兄 · 2025-05-22 16:30:33 发布

ArkUI中的Filter组件详解

概述

Filter是ArkUI中一个强大的多条件筛选组件，它能够帮助用户在大量信息中快速找到所需内容。该组件从API Version 10开始支持，并在后续版本中不断增强了功能。Filter组件由筛选器与悬浮条构成，悬浮条可下拉展示悬浮筛选器，提供了灵活的数据筛选能力。

基本结构

Filter组件的基本结构包括以下几个部分：

多条件筛选列表：主筛选区域，可设置多个筛选维度
附加快捷筛选项：在筛选器最后一行添加的快捷筛选器
筛选结果展示区域：显示筛选结果的容器区域

导入模块

使用Filter组件前需要先导入相应模块：

import { Filter } from '@kit.ArkUI'

核心属性

Filter构造函数

Filter({ multiFilters: Array<FilterParams>, additionFilters?: FilterParams, filterType?: FilterType, onFilterChanged: (Array<FilterResult>) => void, container: ()=> void })

参数说明：

参数名	类型	必填	说明
multiFilters	Array<FilterParams>	是	多条件筛选列表
additionFilters	FilterParams	否	附加快捷筛选项
filterType	FilterType	否	筛选器的样式类型
onFilterChanged	(filterResults: Array<FilterResult>) => void	是	用户点击后的回调事件
container	()=>void	是	筛选结果展示区域自定义内容

FilterParams结构

interface FilterParams { name: ResourceStr; // 筛选项维度名称 options: Array<ResourceStr>; // 筛选项维度可选项列表 }

FilterType枚举

enum FilterType { MULTI_LINE_FILTER = 0, // 多行可折叠类型筛选器 LIST_FILTER = 1 // 多行列表类型筛选器 }

FilterResult结构

interface FilterResult { name: ResourceStr; // 筛选项维度名称 index: number; // 选中项目的索引值 value: ResourceStr; // 选中项目的值 }

使用示例

基础示例

下面是一个使用Filter组件的基础示例：

import { Filter, FilterParams, FilterResult, FilterType } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  private filterParam: Array<FilterParams> = [{
    name: '月份',
    options: ['全部', '1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月', '9月', '10月', '11月', '12月'],
  }, {
    name: '年份',
    options: ['全部', '2023', '2022', '2021', '2020', '2019', '2018', '2017', '2016', '2015', '2014', '2013', '2012',
      '2011', '2010', '2009', '2008'],
  }, {
    name: '节气',
    options: ['全部', '立春', '雨水', '惊蛰', '春分', '清明', '谷雨', '立夏', '小满', '芒种', '夏至', '小暑', '大暑',
      '立秋', '处暑', '白露', '秋分', '寒露', '霜降', '立冬', '小雪', '大雪', '冬至', '小寒', '大寒'],
  }];
  // additionFilters筛选行name必传，不可为空，否则整行不显示
  private additionParam: FilterParams =
    { name: '您还可以搜', options: ['运营栏目1', '运营栏目2', '运营栏目3', '运营栏目4', '运营栏目5', '运营栏目6'] };
  private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

  build() {
    Column() {
      Filter({
        multiFilters: this.filterParam,
        additionFilters: this.additionParam,
        filterType: FilterType.MULTI_LINE_FILTER,
        onFilterChanged: (select: Array<FilterResult>) => {
          console.log('rec filter change');
          for (let filter of select) {
            console.log('name:' + filter.name + ',index:' + filter.index + ',value:' + filter.value);
          }
        }
      }) {
        List({ initialIndex: 0 }) {
          ForEach(this.arr, (item: string, index: number) => {
            ListItem() {
              Text(item.toString())
                .width('100%')
                .height(100)
                .fontSize(16)
                .textAlign(TextAlign.Center)
                .borderRadius(10)
                .backgroundColor(Color.White)
                .margin({ top: 10, bottom: 10 })
            }
          })
        }.backgroundColor(Color.Gray).padding({ left: 20, right: 20 })
      }
    }.height('100%').width('100%')
  }
}

高级用法

Filter组件还支持更复杂的配置，例如自定义筛选结果区域：

import { Filter, FilterParams, FilterResult, FilterType } from '@kit.ArkUI';

@Entry
@Component
struct AdvancedFilterExample {
  private filterData: Array<FilterParams> =
    [{ name: '地区', options: ['全部', '华北', '华东', '华南', '华中', '西北', '西南', '东北'] },
      { name: '价格', options: ['全部', '0-100', '100-300', '300-500', '500-1000', '1000以上'] },
      { name: '类型', options: ['全部', '电子产品', '家居用品', '服装', '食品', '图书'] }];
  private quickFilters: FilterParams = { name: '快捷筛选', options: ['热销', '新品', '促销', '包邮'] };
  @State filteredItems: string[] = [];

  build() {
    Column() {
      Filter({
        multiFilters: this.filterData,
        additionFilters: this.quickFilters,
        filterType: FilterType.LIST_FILTER,
        onFilterChanged: (results: FilterResult[]) => {
          this.handleFilterChange(results);
        }
      }) {
        this.buildResultArea()
      }
    }
  }

  private handleFilterChange(results: FilterResult[]) {
    // 根据筛选结果处理数据
    console.log('筛选条件变化:', results);
    // 这里可以添加实际的数据筛选逻辑
    this.filteredItems = ['商品1', '商品2', '商品3'];
    // 模拟筛选结果
  }

  @Builder
  private buildResultArea() {
    Column() {
      if (this.filteredItems.length > 0) {
        ForEach(this.filteredItems, (item: string) => {
          Text(item).fontSize(16).margin(10)
        })
      } else {
        Text('暂无数据').fontSize(16).margin(10)
      }
    }.width('100%').padding(10)
  }
}