feat: add ColumnSetting component for managing table column visibility

Author: shijistar

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 # Changelog
 
+## 1.5.0
+
+2025-11-17
+
+### Features
+
+- 🔥 Add `ColumnSetting` component for table column visibility management.
+
 ## 1.4.23
 
 2025-11-11

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-codes/react-easy",
-  "version": "1.4.23",
+  "version": "1.5.0",
   "description": "Simplify React and AntDesign development with practical components and hooks",
   "keywords": [
     "react",

src/components/ColumnSetting/index.tsx

@@ -0,0 +1,273 @@
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { Button, Checkbox, ConfigProvider, Divider, Dropdown, Space, Typography } from 'antd';
+import type { ButtonProps, DropdownProps } from 'antd';
+import type { ColumnType } from 'antd/es/table';
+import classNames from 'classnames';
+import { useLocalStorage } from 'react-use';
+import { ReloadOutlined, SettingOutlined } from '@ant-design/icons';
+import { useRefFunction, useRefValue } from '../../hooks';
+import useT from '../../hooks/useT';
+import useStyle from './style';
+
+export interface ColumnSettingProps<T extends ColumnSettingItem = ColumnSettingItem> {
+  /**
+   * - **EN:** The columns to be displayed in the column setting.
+   * - **CN:** 列设置中要显示的列。
+   */
+  columns: T[];
+  /**
+   * - **EN:** Callback function triggered when the selected columns change.
+   * - **CN:** 选中列变化时触发的回调函数。
+   */
+  onChange?: (nextColumns: T[]) => void;
+  /**
+   * - **EN:** Local storage key for persisting column settings.
+   * - **CN:** 用于持久化列设置的本地存储键。
+   */
+  storageKey?: string;
+  /**
+   * - **EN:** Function to render custom column titles.
+   * - **CN:** 自定义列标题的渲染函数。
+   */
+  renderColumnTitle?: (col: ColumnSettingItem, index: number) => React.ReactNode;
+  /**
+   * - **EN:** Props for the button that triggers the dropdown.
+   * - **CN:** 触发下拉菜单的按钮属性。
+   */
+  triggerProps?: ButtonProps;
+  /**
+   * - **EN:** Props for the dropdown component.
+   * - **CN:** 下拉菜单组件的属性。
+   */
+  dropdownProps?: DropdownProps;
+  /**
+   * - **EN:** Props for the dropdown popup container.
+   * - **CN:** 下拉菜单弹出层容器的属性。
+   */
+  popupProps?: React.HTMLAttributes<HTMLDivElement>;
+  /**
+   * - **EN:** Props for the "Check All" button.
+   * - **CN:** “全选”按钮的属性。
+   */
+  checkAllProps?: ButtonProps;
+  /**
+   * - **EN:** Props for the "Reset" button.
+   * - **CN:** “重置”按钮的属性。
+   */
+  resetProps?: ButtonProps;
+  prefixCls?: string;
+}
+
+/**
+ * - **EN:** A component for configuring table column visibility.
+ * - **CN:** 用于配置表格列可见性的组件。
+ */
+function ColumnSetting<T extends ColumnSettingItem = ColumnSettingItem>(props: ColumnSettingProps<T>) {
+  const {
+    columns,
+    storageKey,
+    triggerProps,
+    dropdownProps,
+    popupProps,
+    prefixCls: prefixClsInProps,
+    checkAllProps,
+    resetProps,
+    onChange,
+    renderColumnTitle,
+  } = props;
+  const { getPrefixCls } = useContext(ConfigProvider.ConfigContext);
+  const prefixCls = getPrefixCls('column-setting', prefixClsInProps);
+  const [wrapCSSVar, hashId, cssVarCls] = useStyle(prefixCls);
+  const initialSelectedRef = useRef<string[]>(normalizeToSelectedKeys(columns));
+  const [open, setOpen] = useState(false);
+  const [selectedKeys, setSelectedKeys] = useState<string[]>(initialSelectedRef.current);
+  const t = useT();
+  const [selectedKeysFromStorage, setSelectedKeysFromStorage] = useLocalStorage<string[]>(
+    storageKey ?? '',
+    initialSelectedRef.current
+  );
+  const storageRef = useRefValue(storageKey);
+  const selectedKeysFromStorageRef = useRefValue(selectedKeysFromStorage);
+  const hasChange = useMemo(() => {
+    return [...selectedKeys].sort().join(',') !== initialSelectedRef.current.join(',');
+  }, [selectedKeys]);
+
+  // Compute keys and selectable keys
+  const keys = useMemo(() => columns.map((c, i) => String(getColKey(c, i))), [columns]);
+  const allSelectableKeys = useMemo(
+    () =>
+      columns
+        .map((c, i) => ({ k: String(getColKey(c, i)), disabled: !!c.disabled }))
+        .filter((x) => !x.disabled)
+        .map((x) => x.k),
+    [columns]
+  );
+  const isAllChecked = allSelectableKeys.length > 0 && allSelectableKeys.every((k) => selectedKeys.includes(k));
+  const isIndeterminate = selectedKeys.length > 0 && !isAllChecked;
+
+  // Fire change event when selectedKeysFromStorage changes
+  const change = useRefFunction((nextSelected: string[], fireEvent?: boolean) => {
+    setSelectedKeys(nextSelected);
+    if (storageKey) {
+      setSelectedKeysFromStorage(nextSelected);
+    }
+    if (fireEvent) {
+      const next = columns.map((col, i) => {
+        const k = String(getColKey(col, i));
+        const visible = nextSelected.includes(k);
+        return { ...col, hidden: !visible } as T;
+      });
+      onChange?.(next as T[]);
+    }
+  });
+
+  // Toggle one column change
+  const toggleOne = (key: string, checked: boolean) => {
+    const next = new Set(selectedKeys);
+    if (checked) {
+      next.add(key);
+    } else {
+      // Keep at least one visible column
+      if (selectedKeys.length <= 1) return;
+      next.delete(key);
+    }
+    const nextArr = Array.from(next);
+    change(nextArr, true);
+  };
+
+  // Toggle all columns change
+  const handleCheckAll = (checked: boolean) => {
+    const nextArr = checked
+      ? Array.from(new Set([...selectedKeys, ...allSelectableKeys]))
+      : selectedKeys.filter((k) => !allSelectableKeys.includes(k)).slice(0, 1);
+    const ensured = checked ? nextArr : nextArr.length > 0 ? nextArr : [keys[0]];
+    change(ensured, true);
+  };
+
+  // Reset to initial selected columns
+  const handleReset = () => {
+    const next = initialSelectedRef.current.length > 0 ? initialSelectedRef.current : [keys[0]];
+    change(next, true);
+  };
+
+  // Sync when columns change
+  useEffect(() => {
+    const next = normalizeToSelectedKeys(columns);
+    initialSelectedRef.current = next;
+    change(next, false);
+  }, [columns]);
+
+  // Fire change on mount if storage exists and differs from initial values
+  useEffect(() => {
+    if (
+      storageRef.current &&
+      selectedKeysFromStorageRef.current &&
+      selectedKeysFromStorageRef.current.join(',') !== initialSelectedRef.current.join(',')
+    ) {
+      change(selectedKeysFromStorageRef.current, true);
+    }
+  }, []);
+
+  const dropdownRender = () => (
+    <div
+      {...popupProps}
+      className={classNames(`${prefixCls}-popup`, popupProps?.className)}
+      onClick={(e) => {
+        e.stopPropagation();
+        popupProps?.onClick?.(e);
+      }}
+    >
+      <Typography.Text className={`${prefixCls}-popup-title`}>{t('components.ColumnSetting.title')}</Typography.Text>
+      <Space direction="vertical" className={`${prefixCls}-column-list`} size={12}>
+        {columns.map((col, idx) => {
+          const k = String(getColKey(col, idx));
+          const label = col.title ?? col.dataIndex ?? k;
+          const checked = selectedKeys.includes(k);
+          const disabled = !!col.disabled;
+          const disableUncheck = !disabled && checked && selectedKeys.length <= 1; // 禁止取消最后一个
+          return (
+            <Checkbox
+              key={k}
+              className={`${prefixCls}-column-item`}
+              disabled={disabled || disableUncheck}
+              checked={checked}
+              onChange={(e) => toggleOne(k, e.target.checked)}
+            >
+              <span className={`${prefixCls}-column-item-title`}>{renderColumnTitle?.(col, idx) ?? label}</span>
+            </Checkbox>
+          );
+        })}
+      </Space>
+      <Divider className={`${prefixCls}-divider`} />
+      <div className={`${prefixCls}-footer`}>
+        <Button
+          type="text"
+          {...checkAllProps}
+          className={classNames(`${prefixCls}-select-all`, checkAllProps?.className)}
+          onClick={(e) => {
+            handleCheckAll(!isAllChecked);
+            checkAllProps?.onClick?.(e);
+          }}
+        >
+          <Checkbox checked={isAllChecked} indeterminate={isIndeterminate}></Checkbox>
+          {t('components.ColumnSetting.selectAll')}
+        </Button>
+        <Button
+          type="text"
+          icon={<ReloadOutlined />}
+          disabled={!hasChange}
+          {...resetProps}
+          className={classNames(`${prefixCls}-reset`, resetProps?.className)}
+          onClick={(e) => {
+            handleReset();
+            resetProps?.onClick?.(e);
+          }}
+        >
+          {t('components.ColumnSetting.reset')}
+        </Button>
+      </div>
+    </div>
+  );
+
+  return wrapCSSVar(
+    <Dropdown
+      open={open}
+      onOpenChange={setOpen}
+      trigger={['click']}
+      dropdownRender={dropdownRender}
+      popupRender={dropdownRender}
+      placement="bottomRight"
+      {...dropdownProps}
+      rootClassName={classNames(hashId, cssVarCls, prefixCls, `${prefixCls}-dropdown`, dropdownProps?.className)}
+    >
+      <Button
+        icon={<SettingOutlined />}
+        {...triggerProps}
+        className={classNames(hashId, cssVarCls, prefixCls, `${prefixCls}-trigger`, triggerProps?.className)}
+      />
+    </Dropdown>
+  );
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ColumnSettingItem<T = any> extends ColumnType<T> {
+  /**
+   * - **EN:** Disable toggling visibility for this column.
+   * - **CN:** 禁止切换此列的可见性。
+   */
+  disabled?: boolean;
+}
+
+function getColKey(col: ColumnType, idx: number): React.Key {
+  return col.key ?? (col.dataIndex as string) ?? idx;
+}
+
+function normalizeToSelectedKeys(cols: ColumnType[]): string[] {
+  return cols
+    .map((c, i) => ({ key: String(getColKey(c, i)), hidden: !!c.hidden }))
+    .filter((c) => !c.hidden)
+    .map((c) => c.key)
+    .sort();
+}
+
+export default ColumnSetting;

src/components/ColumnSetting/style/index.ts

@@ -0,0 +1,58 @@
+import { genStyleHooks } from 'antd/es/theme/internal';
+import type { AliasToken, GenerateStyle } from 'antd/es/theme/internal';
+import type { CSSObject } from '@ant-design/cssinjs';
+import type { FullToken } from '@ant-design/cssinjs-utils';
+
+type ColumnSettingToken = FullToken<{ ''?: object }, AliasToken, ''>;
+
+const genStyle: GenerateStyle<ColumnSettingToken> = (token): CSSObject => {
+  const { componentCls } = token;
+  return {
+    [`${componentCls}-dropdown`]: {
+      [`${componentCls}-popup`]: {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        padding: '12px 16px',
+        borderRadius: token.borderRadiusLG,
+        boxShadow: token.boxShadow,
+        width: 260,
+        maxHeight: 500,
+        background: token.colorBgContainer,
+
+        [`${componentCls}-popup-title`]: {
+          marginBottom: 4,
+          fontWeight: '600',
+        },
+
+        [`${componentCls}-column-list`]: {
+          width: '100%',
+          overflow: 'auto',
+          flex: 'auto',
+          minInlineSize: 0,
+          padding: '0 8px',
+
+          [`${componentCls}-column-item`]: {
+            [`${componentCls}-column-item-title`]: {
+              wordBreak: 'break-all',
+            },
+          },
+        },
+
+        [`& ${componentCls}-divider`]: {
+          margin: 0,
+        },
+
+        [`${componentCls}-footer`]: {
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          gap: 12,
+        },
+      },
+    },
+    [`${componentCls}-trigger`]: {},
+  };
+};
+
+export default genStyleHooks('ColumnSetting' as never, genStyle);

src/components/index.tsx

@@ -1,6 +1,9 @@
 export type { BreakLinesProps } from './BreakLines';
 export { default as BreakLines } from './BreakLines';
 
+export type { ColumnSettingProps } from './ColumnSetting';
+export { default as ColumnSetting } from './ColumnSetting';
+
 export type { ConfigProviderProps } from './ConfigProvider';
 export { default as ConfigProvider } from './ConfigProvider';
 export type { ReactEasyContextProps } from './ConfigProvider/context';

src/locales/langs/en-US.ts

@@ -4,6 +4,10 @@ const enUS = {
   'components.EditableText.edit': 'Edit',
   'components.EditableText.save': 'Save',
   'components.EditableText.cancel': 'Cancel',
+  'components.ColumnSetting.title': 'Column Setting',
+  'components.ColumnSetting.selectAll': 'Select All',
+  'components.ColumnSetting.reset': 'Reset',
+
   'validation.rule.number.message': 'Please enter a number',
   'validation.rule.floatNumber.message': 'Please enter a number',
   'validation.rule.email.message': 'Please enter the correct email address',

src/locales/langs/zh-CN.ts

@@ -4,6 +4,10 @@ const zhCN = {
   'components.EditableText.edit': '编辑',
   'components.EditableText.save': '保存',
   'components.EditableText.cancel': '取消',
+  'components.ColumnSetting.title': '列设置',
+  'components.ColumnSetting.selectAll': '全选',
+  'components.ColumnSetting.reset': '重置',
+
   'validation.rule.number.message': '请输入数字',
   'validation.rule.floatNumber.message': '请输入数字',
   'validation.rule.email.message': '请输入正确的邮箱地址',