Preview Updated 2026-05-10

ColumnVisibilityMenu 列显隐菜单

表格列的显隐 / 排序 / 固定（pin left/right）控制；HTML5 拖拽 + 上下移动按钮。

English translation pending This page hasn't been translated yet — falling back to Chinese. PRs welcome on GitHub.

基础用法

modelValue 是 ColumnConfig 数组，含 key / label / visible / pinned / locked。组件不直接操作表格——它只输出”用户期望的列配置”，由消费方应用到 CfTable / CfDataGrid / CfTreeTable 上。locked: true 的列禁止隐藏 / 改 pin。

背景视口

✓ 姓名 (left)
✓ 邮箱
✓ 角色
✗ 团队
✓ 加入时间
✓ 状态 (right)

src/App.vue

<script setup lang="ts">
import { ref } from 'vue';
import { CfColumnVisibilityMenu, type ColumnConfig } from '@chufix-design/vue';

const columns = ref<ColumnConfig[]>([
  { key: 'name',   label: '姓名',     visible: true, pinned: 'left',  locked: true },
  { key: 'email',  label: '邮箱',     visible: true },
  { key: 'role',   label: '角色',     visible: true },
  { key: 'team',   label: '团队',     visible: false },
  { key: 'joined', label: '加入时间', visible: true },
  { key: 'status', label: '状态',     visible: true, pinned: 'right' },
]);
</script>
<template>
  <div class="demo-stack">
    <CfColumnVisibilityMenu v-model="columns" />
    <pre class="demo-hint">{{ columns.map(c => `${c.visible ? '✓' : '✗'} ${c.label}${c.pinned ? ` (${c.pinned})` : ''}`).join('\n') }}</pre>
  </div>
</template>
<style scoped>
.demo-hint { background: var(--bg-2); padding: 8px 12px; border-radius: var(--r-3); font-family: var(--font-mono); font-size: var(--t-12); margin: 0; }
</style>

<script setup>
import { ref } from 'vue';
import { CfColumnVisibilityMenu } from '@chufix-design/vue';

const columns = ref<ColumnConfig[]>([
  { key: 'name',   label: '姓名',     visible, pinned: 'left',  locked: true },
  { key: 'email',  label: '邮箱',     visible: true },
  { key: 'role',   label: '角色',     visible: true },
  { key: 'team',   label: '团队',     visible: false },
  { key: 'joined', label: '加入时间', visible: true },
  { key: 'status', label: '状态',     visible, pinned: 'right' },
]);
</script>
<template>
  <div class="demo-stack">
    <CfColumnVisibilityMenu v-model="columns" />
    <pre class="demo-hint">{{ columns.map(c => `${c.visible ? '✓' : '✗'} ${c.label}${c.pinned ? ` (${c.pinned})` : ''}`).join('\n') }}</pre>
  </div>
</template>
<style scoped>
.demo-hint { background: var(--bg-2); padding: 8px 12px; border-radius: var(--r-3); font-family: var(--font-mono); font-size: var(--t-12); margin: 0; }
</style>

import { useState } from 'react';
import { CfColumnVisibilityMenu } from '@chufix-design/react';

export default function Demo() {
  const [columns, setColumns] = useState([
    { key: 'name',   label: '姓名',     visible: true, pinned: 'left',  locked: true },
    { key: 'email',  label: '邮箱',     visible: true },
    { key: 'role',   label: '角色',     visible: true },
    { key: 'team',   label: '团队',     visible: false },
    { key: 'joined', label: '加入时间', visible: true },
    { key: 'status', label: '状态',     visible: true, pinned: 'right' },
  ]);
  const [columns, setColumns] = useState([
    { key: 'name',   label: '姓名',     visible: true, pinned: 'left',  locked: true },
    { key: 'email',  label: '邮箱',     visible: true },
    { key: 'role',   label: '角色',     visible: true },
    { key: 'team',   label: '团队',     visible: false },
    { key: 'joined', label: '加入时间', visible: true },
    { key: 'status', label: '状态',     visible: true, pinned: 'right' },
  ]);
  return (
    <>
      <CfColumnVisibilityMenu value={columns} onChange={setColumns} />
    </>
  );
}

import { useState } from 'react';
import { CfColumnVisibilityMenu } from '@chufix-design/react';

export default function Demo() {
  const [columns, setColumns] = useState([
    { key: 'name',   label: '姓名',     visible, pinned: 'left',  locked: true },
    { key: 'email',  label: '邮箱',     visible: true },
    { key: 'role',   label: '角色',     visible: true },
    { key: 'team',   label: '团队',     visible: false },
    { key: 'joined', label: '加入时间', visible: true },
    { key: 'status', label: '状态',     visible, pinned: 'right' },
  ]);
  const [columns, setColumns] = useState([
    { key: 'name',   label: '姓名',     visible, pinned: 'left',  locked: true },
    { key: 'email',  label: '邮箱',     visible: true },
    { key: 'role',   label: '角色',     visible: true },
    { key: 'team',   label: '团队',     visible: false },
    { key: 'joined', label: '加入时间', visible: true },
    { key: 'status', label: '状态',     visible, pinned: 'right' },
  ]);
  return (
    <>
      <CfColumnVisibilityMenu value={columns} onChange={setColumns} />
    </>
  );
}

API

属性	类型	默认	说明
`modelValue` / `value`	`ColumnConfig[]`	`—`	当前列配置
`showPinning`	`boolean`	`true`	显示 L / R pin 按钮
`showReorder`	`boolean`	`true`	显示拖拽 handle + 上下箭头
`triggerLabel`	`string`	`'列设置'`	触发按钮文案
`menuLabel`	`string`	`'列显示与排序'`	菜单标题 + aria

ColumnConfig

字段	类型	说明
`key`	`string`	列 id
`label`	`string`	显示名
`visible`	`boolean`	当前显隐
`pinned`	`'left' \| 'right' \| null`	固定到边
`locked`	`boolean`	不可改（灰显）