@yungu-fed/class-student-roster

班级/年级学生选择弹窗组件（React）。

安装

npm i @yungu-fed/class-student-roster

基础使用

import React, { useState } from 'react';
import ClassStudentRoster from '@yungu-fed/class-student-roster';

export default function Demo() {
  const [visible, setVisible] = useState(false);

  const data = {
    // 方式 1：年级 -> 班级 -> 学生
    grades: [
      {
        id: 'g10',
        name: '十年级',
        classes: [
          { id: 'c101', name: '十年级1班', studentIds: ['s1', 's2'] },
          { id: 'c102', name: '十年级2班', studentIds: ['s3'] },
        ],
      },
    ],
    students: [
      { id: 's1', name: '张三', gradeId: 'g10', classId: 'c101' },
      { id: 's2', name: '李四', gradeId: 'g10', classId: 'c101' },
      { id: 's3', name: '王五', gradeId: 'g10', classId: 'c102' },
    ],
    defaultGradeName: '全部班级',
  };

  return (
    <div>
      <button onClick={() => setVisible(true)}>打开选择学生</button>
      <ClassStudentRoster
        visible={visible}
        data={data}
        onClose={() => setVisible(false)}
        onSave={(list) => {
          console.log('selected:', list);
          setVisible(false);
        }}
      />
    </div>
  );
}

Props

visible: boolean

控制弹窗显示/隐藏。

title?: string

弹窗标题，默认：选择学生。

language?: 'zh' | 'en'

文案语言，默认：'zh'。

data: object

组件数据源（同步）。支持两种结构（任选其一）：

• 结构 A（推荐）：grades + students
  • data.grades: Array<{ id: string; name: string; classes: Array<{ id: string; name: string; studentIds: string[] }> }>
  • data.students: Array<{ id: string; name: string; classId: string; gradeId?: string }>
• 结构 B（纯班级）：classes + students
  • data.classes: Array<{ id: string; name: string; studentIds: string[] }>
  • data.students: Array<{ id: string; name: string; classId: string; gradeId?: string }>
  • 该结构会被自动包装成一个“虚拟年级”，名称取 defaultGradeName 或默认值。

可选字段：

• data.defaultGradeName?: string：当传 classes（纯班级结构）时，用于显示左侧顶层名称（如“全部班级/所有班级”）。

selectedIds?: string[]

默认回显已选学生 id 列表（弹窗打开时会初始化内部选中状态）。

disableIds?: string[]

禁选学生 id 列表：

• 禁选学生的 checkbox 不可操作
• 左侧年级/班级“联动勾选”与右侧“全选”会自动跳过禁选学生
• 已选列表（chip）里禁选学生不可删除
• “清空”只会清除可选项，禁选项若已选会保留

onClose?: () => void

点击右上角关闭或取消按钮触发。

onSave?: (list: Array<{ id: string; name: string }>) => void

点击保存触发，返回已选学生列表（仅 id/name）。

交互说明

• 左侧点击文本：仅切换定位（年级/班级），右侧展示对应学生列表
• 左侧 checkbox：控制勾选（年级全选/班级全选），并带年级/班级联动与半选态
• 右侧搜索：全局搜索年级/班级/学生名，并自动定位到第一个命中（优先年级，其次班级，最后学生）
• 班级右侧人数：显示该班级“已选/总数”（总数不含禁选项）

样式说明（重要）

本组件在打包时会将样式注入到入口 JS 中：业务项目只需要 import 组件即可生效，无需再单独 import css。

同时包内也会发布 dist/style.css，如果你希望显式引入也可以使用（可选）。

注意事项

• React 版本：本包将 react/react-dom 作为 peerDependencies，请确保业务项目已安装。
• 数据一致性：grades/classes 内的 studentIds 应与 students 中的 id 对应，否则会导致右侧列表缺失。
• 受控/非受控：当前 selectedIds 用于“打开时初始化回显”。如果你希望完全受控（外部每次变更都覆盖内部），需要额外改造同步策略。