MUI Checkbox用defaultChecked改搜索参数报错，求更优解决方案

我需要实现一个从URL搜索参数读取筛选值的组件，要求仅在组件挂载时设置Checkbox的defaultChecked状态。现有组件代码如下：

import "./styles.css";
import {
  Checkbox,
  FormControlLabel,
  Box,
  FormGroup,
  Button,
} from "@mui/material";
import { useSearchParams } from "react-router-dom";

const filterValues = [
  {
    value: 1,
    label: "One",
  },
  {
    value: 2,
    label: "Two",
  },
] as const;

export default function Filters() {
  const [searchParams, setSearchParams] = useSearchParams();
  const onFilterChange = (
    event: React.ChangeEvent<HTMLInputElement>,
    checked: boolean
  ) => {
    let filters = searchParams.get("filters")?.split(",") || [];

    const filter = event.target.value;

    if (checked) filters.push(filter);
    else filters = filters.filter((_filter) => filter !== _filter);

    if (filters.length === 0) searchParams.delete("filters");
    else searchParams.set("filters", filters.join(","));
  };

  return (
    <Box>
      <FormGroup>
        {filterValues.map(({ label, value }) => (
          <FormControlLabel
            key={label}
            control={
              <Checkbox
                defaultChecked={searchParams
                  .get("filters")
                  ?.split(",")
                  .includes(value.toString())}
                onChange={onFilterChange}
              />
            }
            value={value}
            label={label}
          />
        ))}
      </FormGroup>
      <Button variant="contained" onClick={() => setSearchParams(searchParams)}>
        Set Filters
      </Button>
    </Box>
  );
}

设置新的搜索参数后，控制台出现以下错误：

MUI: A component is changing the default checked state of an uncontrolled SwitchBase after being initialized.

我尝试过用useState保存初始选中状态，代码如下，但感觉这是不必要的状态重复：

const [checkedStates] = useState(
  filterValues.map(({ value }) => ({
    checked: searchParams.get('filters')?.split(',').includes(value.toString()),
  })),
);

请问有没有更好的处理方式？

解决方案 #

错误原因 #

报错的核心问题是：searchParams是响应式对象，当你修改并更新搜索参数后，组件会重新渲染，此时defaultChecked会读取最新的searchParams值。但defaultChecked仅应该在组件初始化时生效，后续修改会让React认为组件从「非受控状态」切换到「受控状态」，从而抛出错误。

优化方案：缓存初始筛选状态（无重复状态） #

我们可以用useMemo或useRef缓存组件挂载时的初始筛选参数，避免每次渲染都读取最新的searchParams，同时满足「仅挂载时设置defaultChecked」的需求。

方案1：使用useMemo缓存初始状态

import "./styles.css";
import {
  Checkbox,
  FormControlLabel,
  Box,
  FormGroup,
  Button,
} from "@mui/material";
import { useSearchParams } from "react-router-dom";
import { useMemo } from "react";

const filterValues = [
  {
    value: 1,
    label: "One",
  },
  {
    value: 2,
    label: "Two",
  },
] as const;

export default function Filters() {
  const [searchParams, setSearchParams] = useSearchParams();

  // 仅在组件挂载时计算一次初始选中状态，空依赖保证只执行一次
  const initialCheckedStates = useMemo(() => {
    const initialFilters = searchParams.get("filters")?.split(",") || [];
    return filterValues.map(({ value }) => 
      initialFilters.includes(value.toString())
    );
  }, []);

  const onFilterChange = (
    event: React.ChangeEvent<HTMLInputElement>,
    checked: boolean
  ) => {
    // 注意：必须创建新的URLSearchParams实例，避免直接修改原对象
    const newSearchParams = new URLSearchParams(searchParams);
    let filters = newSearchParams.get("filters")?.split(",") || [];
    const filter = event.target.value;

    if (checked) {
      // 避免重复添加相同筛选值
      if (!filters.includes(filter)) {
        filters.push(filter);
      }
    } else {
      filters = filters.filter((_filter) => _filter !== filter);
    }

    if (filters.length === 0) {
      newSearchParams.delete("filters");
    } else {
      newSearchParams.set("filters", filters.join(","));
    }

    setSearchParams(newSearchParams);
  };

  return (
    <Box>
      <FormGroup>
        {filterValues.map(({ label, value }, index) => (
          <FormControlLabel
            key={label}
            control={
              <Checkbox
                defaultChecked={initialCheckedStates[index]}
                onChange={onFilterChange}
              />
            }
            value={value}
            label={label}
          />
        ))}
      </FormGroup>
      <Button variant="contained" onClick={() => setSearchParams(searchParams)}>
        Set Filters
      </Button>
    </Box>
  );
}

方案2：使用useRef保存初始参数

import "./styles.css";
import {
  Checkbox,
  FormControlLabel,
  Box,
  FormGroup,
  Button,
} from "@mui/material";
import { useSearchParams } from "react-router-dom";
import { useRef, useEffect } from "react";

const filterValues = [
  {
    value: 1,
    label: "One",
  },
  {
    value: 2,
    label: "Two",
  },
] as const;

export default function Filters() {
  const [searchParams, setSearchParams] = useSearchParams();
  // 用ref保存挂载时的初始筛选参数，不会触发重渲染
  const initialFiltersRef = useRef<string[]>([]);

  useEffect(() => {
    // 仅在组件挂载时读取一次初始筛选参数
    initialFiltersRef.current = searchParams.get("filters")?.split(",") || [];
  }, []);

  const onFilterChange = (
    event: React.ChangeEvent<HTMLInputElement>,
    checked: boolean
  ) => {
    const newSearchParams = new URLSearchParams(searchParams);
    let filters = newSearchParams.get("filters")?.split(",") || [];
    const filter = event.target.value;

    if (checked) {
      if (!filters.includes(filter)) {
        filters.push(filter);
      }
    } else {
      filters = filters.filter((_filter) => _filter !== filter);
    }

    if (filters.length === 0) {
      newSearchParams.delete("filters");
    } else {
      newSearchParams.set("filters", filters.join(","));
    }

    setSearchParams(newSearchParams);
  };

  return (
    <Box>
      <FormGroup>
        {filterValues.map(({ label, value }) => (
          <FormControlLabel
            key={label}
            control={
              <Checkbox
                defaultChecked={initialFiltersRef.current.includes(value.toString())}
                onChange={onFilterChange}
              />
            }
            value={value}
            label={label}
          />
        ))}
      </FormGroup>
      <Button variant="contained" onClick={() => setSearchParams(searchParams)}>
        Set Filters
      </Button>
    </Box>
  );
}

方案说明 #

• 两种方案都避免了useState带来的状态重复问题，仅缓存组件挂载时的初始筛选值；
• 同时修复了原代码中直接修改searchParams对象的问题（必须创建新实例，否则会导致意外的状态变更）；
• useMemo更适合需要计算衍生值的场景，useRef则更适合单纯保存静态初始值的场景，可根据需求选择。

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