Skip to content

3. 组件

3.1. 示例 10:组件及其 props

组件是用户界面中 可复用的一部分。本示例创建了一个组件 [DoctorCard],并多次使用它。

3.1.1. 数据类型

1
2
3
4
5
6
7
8
9
// 由父组件(App)和子组件(DoctorCard)共用的数据类型
export interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: string;
  available: boolean;
}

类型 [Doctor] 由父组件和子组件共用:它存放在单独的模块中。

3.1.2. 子组件

// =========================================================================
// 10-components/src/DoctorCard.tsx - 一个子组件
// -------------------------------------------------------------------------
// 它通过 props(属性)从父组件接收数据:即
// 父组件写在 <DoctorCard ... /> 上的属性,由
// React 汇集成一个对象,作为函数的第一个参数。它们的类型会
// 在编译时检查:<DoctorCard doctor={42} /> 会被拒绝。
//
// 黄金法则:组件绝不修改它的 props。数据
// 从父组件向下流向子组件;若要请求修改,
// 子组件调用父组件传给它的函数(参见示例 11)。
// =========================================================================

import type { Doctor } from './doctor';
// styles:一个对象 { initials: '_initials_x7f3a_1' } - 每个类的真实名称
import styles from './DoctorCard.module.css';

// props 的类型:父组件可以(?)或必须提供的内容
interface Props {
  doctor: Doctor;
  rank: number;
  compact?: boolean; // 可选的
}

// props 对象被“解构”;compact = false:它的默认值
export default function DoctorCard({ doctor, rank, compact = false }: Props) {
  // 由 props 计算得出的值:父组件改变它们时会重新计算
  const initials = `${doctor.firstName[0]}${doctor.lastName[0]}`;

  return (
    <div className={`card h-100 ${doctor.available ? 'border-success' : ''}`}>
      <div className="card-body d-flex gap-3 align-items-center">
        <div className={styles.initials}>{initials}</div>
        <div>
          <h2 className="h6 mb-1">{rank}. {doctor.title} {doctor.firstName} {doctor.lastName}</h2>
          {!compact && <p className="mb-0 text-muted small">{doctor.specialty}</p>}
        </div>
      </div>
    </div>
  );
}
  • 第 14 行:仅类型导入;
  • 第 16 行:导入 CSS 模块 (见下文);
  • 第 19–23 行:组件的 prop 类型——父组件写在 [<DoctorCard ... />] 上的属性。[compact?] 是可选的;
  • 第 26 行:[React] 把 props 合并成一个对象,作为第一个参数传给函数。它随即被“解构”:[{ doctor, rank, compact = false }] 得到三个变量,如果父组件没有提供 [compact],它就等于 [false] 。props 的类型在编译时检查:[<DoctorCard doctor={42} />] 会被拒绝,省略 [rank] 同样会被拒绝;
  • 第 28 行:由 props 计算得出的值:如果父组件改变了 props,组件会被重新调用,该值也随之重新计算;
  • 第 33 行:从 CSS 模块中读取的 CSS 类;
  • 第 36 行:专业只在普通模式下显示。

黄金法则:组件 绝不修改 自己的 props。数据从父组件流向子组件;若要请求修改,子组件调用父组件传给它的函数(见示例 11)。

3.1.3. CSS 模块

/* “CSS 模块”(*.module.css 文件):Vite 会重命名每个类
   (.initials -> ._initials_x7f3a_1); it can therefore only apply to the
   elements of the component that imports it */
.initials {
  width: 2.5rem;
  height: 2.5rem;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #087ea4;
  color: white;
  font-weight: bold;
}

名称以 [.module.css] 结尾的文件是 CSS 模块:[Vite] 会重命名其中的每个类(例如 [.initials] 变成 [._initials_x7f3a_1]),并在导入时提供一个把原始名称与实际名称对应起来的对象:[styles.initials]。因此这个类只能应用于导入它的组件的元素:这相当于 [Angular] 中的样式封装。[Bootstrap] 的类是全局的,仍可在任何地方使用。

3.1.4. 父组件

// =========================================================================
// 10-components/src/App.tsx - 父组件
// -------------------------------------------------------------------------
// 它导入 DoctorCard 组件,并把它当作新的
// 标签 <DoctorCard /> 使用,需要多少次就用多少次:组件是
// 界面中可复用的一部分,拥有自己的数据、JSX 和
// 样式。以大写字母开头的标签是组件;
// 小写的(<div>、<p>)则是 HTML 元素。
// =========================================================================

import { useState } from 'react';
import DoctorCard from './DoctorCard';
import type { Doctor } from './doctor';

export default function App() {
  const [doctors, setDoctors] = useState<Doctor[]>([
    { id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true },
    { id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false },
    { id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner', available: true },
  ]);
  const [compact, setCompact] = useState(false);

  // 父组件修改它自己的数据:React 再次调用父组件,然后
  // 用新的 props 调用子组件
  function toggleAvailability() {
    setDoctors((list) => list.map((m) => ({ ...m, available: !m.available })));
  }

  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 10 - components and their props</h1>
      <div className="d-flex gap-3 mb-3">
        <label className="form-check-label">
          <input type="checkbox" className="form-check-input" checked={compact}
                 onChange={(e) => setCompact(e.target.checked)} /> compact display
        </label>
        <button className="btn btn-sm btn-outline-primary" onClick={toggleAvailability}>Toggle availabilities</button>
      </div>
      <div className="row g-3">
        {doctors.map((m, i) => (
          <div key={m.id} className="col-md-4">
            {/* doctor={m} 传递的是对象 m(一个表达式);
                doctor="m", without braces, would pass the STRING "m" */}
            <DoctorCard doctor={m} rank={i + 1} compact={compact} />
          </div>
        ))}
      </div>
      <p className="mt-3 mb-1 small text-muted">The same card, in compact version, by an attribute without a value:</p>
      <div className="w-50">
        {/* 没有值的 compact 等于 true */}
        <DoctorCard doctor={doctors[0]} rank={1} compact />
      </div>
    </div>
  );
}
  • 第 12 行:子组件像其他模块一样被导入;
  • 第 25–27 行:父组件修改它自己的数据。[React] 重新渲染它,然后用新的 props 重新渲染子组件:卡片随之更新;
  • 第 44 行:组件被当作新标签使用。[doctor={m}] 传递的是对象 [m] (一个表达式);[doctor="m"] 不带花括号,传递的则是字符串“m”;
  • 第 51 行:没有值的属性([compact])等于 [true]。

Image

勾选“紧凑显示”,然后反转各医生的可预约设置:

Image

3.2. 示例 11:子组件通知父组件

数据通过 props 向下流动。若要把信息传回上层,父组件向子组件传递 函数,再由子组件调用它们。

3.2.1. 来自子组件的“事件”

// =========================================================================
// 11-lifting-state-up/src/Counter.tsx
// -------------------------------------------------------------------------
// 一个通知父组件的子组件:父组件在 props 中向它传递函数
// (按惯例,它们的名称以“on”开头),子组件在
// 有事情发生时调用它们:
//     <Counter label="Coffees" max={3} onIncrement={...} onLimit={...} />
// =========================================================================

import { useState } from 'react';

interface Props {
  label: string;
  max: number;
  onIncrement: (value: number) => void; // 带新值
  onLimit: () => void; // 不带数据
}

export default function Counter({ label, max, onIncrement, onLimit }: Props) {
  // 这个计数器自有的状态:每个 <Counter> 都有自己的状态
  const [value, setValue] = useState(0);

  function plus() {
    if (value >= max) {
      onLimit();
      return;
    }
    setValue(value + 1);
    // value 尚未被修改(要到下一次调用
    // 组件时才会改变):传出的是 value + 1
    onIncrement(value + 1);
  }

  return (
    <div className="d-flex align-items-center gap-2 mb-2">
      <span className="w-25">{label}</span>
      <button className="btn btn-sm btn-outline-primary" onClick={plus}>+1</button>
      <span className="badge text-bg-secondary">{value} / {max}</span>
    </div>
  );
}
  • 第 12–17 行:两个 prop 是函数:[onIncrement] 接收新值,而 [onLimit] 不接收任何参数。按惯例,它们的名称以“on”开头,例如 [onClick];
  • 第 21 行:这个计数器自有的状态:页面上的每个 [<Counter>] 都有各自的状态。状态附着在组件于页面树中的位置上;
  • 第 23–32 行:通知父组件。注意:[setValue(value + 1)] 不会改变变量 [value](它是本次组件调用中固定的常量):它在下一次调用时才会变成 [value + 1]。因此传给父组件的是 [value + 1]。

3.2.2. 受控组件

// =========================================================================
// 11-lifting-state-up/src/TextField.tsx - 一个受控组件
// -------------------------------------------------------------------------
// 一个“自制”的表单字段(标签 + 字段 + 帮助 + 字符
// 计数器),用法类似受控的 <input>(参见示例 05):
//     <TextField value={lastName} onChange={setLastName} label="Last name" max={20} />
// 该组件没有状态:值属于父组件,由父组件传入
// (value),并在每次按键时通知父组件(onChange)。由
// 父组件决定新的值。
// =========================================================================

import { useId } from 'react';

interface Props {
  value: string;
  onChange: (value: string) => void;
  label: string;
  max: number;
  help?: string;
}

export default function TextField({ value, onChange, label, max, help = '' }: Props) {
  // useId:一个唯一的标识符,页面上的每个 <TextField>
  // 各不相同,用来关联 <label htmlFor> 和 <input id>
  const id = useId();

  return (
    <div className="mb-3">
      <label className="form-label" htmlFor={id}>{label}</label>
      <input id={id} className={`form-control ${value.length === max ? 'is-invalid' : ''}`} value={value}
             maxLength={max} onChange={(e) => onChange(e.target.value)} />
      <div className="form-text">{help} ({value.length} / {max})</div>
    </div>
  );
}

一个“自定义”的表单字段(标签、字段、提示、字符计数器),用作受控的 [<input>] (见示例 05):父组件向它传递值([value])以及每次按键时调用的函数([onChange])。

  • 第 14–20 行:props;[help] 是可选的;
  • 第 25 行:[useId()] 提供一个 唯一的标识符,页面上的每个 [<TextField>] 各不相同,用来关联 [<label htmlFor>] 和 [<input id>];
  • 第 31 行:每次按键都会用新的文本调用父组件的函数。

该组件没有状态:值属于父组件,由父组件决定新值。这称为“状态提升”:由多个组件共享的数据存放在它们最近的共同祖先中。

3.2.3. 父组件

// =========================================================================
// 11-lifting-state-up/src/App.tsx - 父组件监听它的子组件
// -------------------------------------------------------------------------
// 数据向下流动(props);信息通过 props 中传递的
// 函数向上流动:
//   1. 子组件的“事件”:onIncrement、onLimit;
//   2. 受控组件:value + onChange,就像 <input>。状态
//      仍然属于父组件,父组件可以自己修改它(Clear)。
// =========================================================================

import { useState } from 'react';
import Counter from './Counter';
import TextField from './TextField';

export default function App() {
  const [total, setTotal] = useState(0);
  const [message, setMessage] = useState('');
  const [firstName, setFirstName] = useState('Marie');
  const [lastName, setLastName] = useState('PELISSIER');

  // 由计数器调用的函数:它接收计数器传来的值
  function onIncrement(label: string, value: number) {
    setTotal((t) => t + 1);
    setMessage(`${label} is now ${value}`);
  }

  function clear() {
    setFirstName('');
    setLastName('');
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 11 - the child notifies its parent</h1>

      <div className="card p-3 mb-4">
        <h2 className="h6">1. Functions called by the children</h2>
        <Counter label="Coffees" max={3} onIncrement={(v) => onIncrement('Coffees', v)}
                 onLimit={() => setMessage('No more than 3 coffees!')} />
        <Counter label="Glasses of water" max={8} onIncrement={(v) => onIncrement('Glasses of water', v)}
                 onLimit={() => setMessage('Enough drinking.')} />
        <p className="mb-0">Total of the clicks: {total} - <em>{message}</em></p>
      </div>

      <div className="card p-3">
        <h2 className="h6">2. Controlled components</h2>
        {/* onChange={setFirstName}:状态函数,原样传递 */}
        <TextField value={firstName} onChange={setFirstName} label="First name" max={20} help="Required" />
        <TextField value={lastName} onChange={setLastName} label="Last name" max={20} help="Displayed in upper case" />
        <p className="mb-0">Data of the parent: <strong>{firstName} {lastName.toUpperCase()}</strong></p>
        <button className="btn btn-sm btn-outline-secondary mt-2 align-self-start" onClick={clear}>Clear (from the parent)</button>
      </div>
    </div>
  );
}
  • 第 22–25 行:由计数器调用的函数;它接收计数器传给它的值;
  • 第 38–39 行:父组件传递箭头函数,由它们加上计数器的标签;
  • 第 48 行:[onChange={setFirstName}]:状态函数 原样传递;子组件用新的文本调用它;
  • 第 51 行:父组件自己修改这些值;字段随之更新。

点击第一个“+1”两次,再点击四次,点击第二个一次,并在“姓”字段中输入“Dupont”:

Image

3.3. 示例 12:组合

props 传递数据……也传递 内容:“JSX”和其他值(例如“[ReactNode]”)一样是一个值,可以传给组件,组件可以把它放在任何想放的位置。

3.3.1. 卡片

// =========================================================================
// 12-composition/src/Card.tsx - 一个可复用的模板
// -------------------------------------------------------------------------
// props 传递数据……也传递内容:JSX 是
// 和其他值一样的值(类型为 ReactNode),可以传给
// 组件,由组件把它放在想放的位置:
//   - children:特殊的 prop,接收父组件写在
//                <Card> 和 </Card> 之间的内容——“主体”内容;
//   - header、footer:其他占位内容,由父组件以
//                props 的形式提供;header 有默认内容。
// 卡片设定框架(边框、页眉、页脚),父组件提供其中
// 的内容。它相当于 NestJS 课程中 layout.hbs 模板
// 及其 {{{body}}} 在客户端的对应物。
// =========================================================================

import type { ReactNode } from 'react';

interface Props {
  color?: 'primary' | 'success' | 'danger';
  header?: ReactNode;
  footer?: ReactNode;
  children: ReactNode;
}

export default function Card({ color, header = 'Untitled', footer, children }: Props) {
  return (
    <div className={`card mb-3 ${color ? `border-${color}` : ''}`}>
      <div className={`card-header ${color ? `text-bg-${color}` : ''}`}>{header}</div>
      <div className="card-body">{children}</div>
      {/* 没有提供页脚:就完全没有页脚 */}
      {footer && <div className="card-footer text-muted small">{footer}</div>}
    </div>
  );
}
  • 第 18–23 行:[header]、[footer] 和 [children] 都是 [ReactNode]:JSX、文本、数字或空;
  • 第 25 行:默认内容;
  • 第 29 行:[children] 是一个特殊属性:它接收父组件写在 [<Card>] 和 [</Card>] 之间的任何内容——即“主体”内容;
  • 第 31 行:没有提供页脚——就完全没有页脚。

模板定义框架(边框、页眉、页脚);父组件提供其中的内容:这相当于 [Angular] 的内容投影([<ng-content>])和 [Vue.js] 的“插槽”,以及在服务器端,[NestJS] 课程中的模板 [layout.hbs] 及其 [{{{body}}}]。

3.3.2. 通用表格

// =========================================================================
// 12-composition/src/DataTable.tsx - 一个通用表格
// -------------------------------------------------------------------------
// DataTable<T> 是一个泛型组件:它显示任意类型 T 的
// 行。它知道如何遍历各行,但不知道如何
// 显示一行:由父组件通过传给它一个
// 函数 renderRow(row, index) 来告诉它,该函数返回单元格的 JSX。
// 这就是所谓的“render prop”:父组件提供的内容
// 使用属于子组件的数据(行及其
// 序号)。
// =========================================================================

import type { ReactNode } from 'react';

interface Props<T> {
  rows: T[];
  columns: string[];
  renderRow: (row: T, index: number) => ReactNode;
  empty?: ReactNode; // 没有行时显示
}

// <T extends { id: number }>:每一行都必须有一个 id(即 key)
export default function DataTable<T extends { id: number }>({ rows, columns, renderRow, empty = 'No data.' }: Props<T>) {
  return (
    <table className="table table-sm align-middle mb-0">
      <thead>
        <tr>
          {columns.map((c) => <th key={c}>{c}</th>)}
        </tr>
      </thead>
      <tbody>
        {rows.length === 0 ? (
          <tr>
            <td className="text-muted" colSpan={columns.length}>{empty}</td>
          </tr>
        ) : (
          rows.map((l, i) => <tr key={l.id}>{renderRow(l, i)}</tr>)
        )}
      </tbody>
    </table>
  );
}
  • 第 15–20 行:一个 泛型类型:由类型为 [T] 的行组成的数组的 props,不论 T 是什么;
  • 第 18 行:一个是 返回 JSX 的函数的 prop:表格知道如何遍历各行,但不知道如何显示一行;由父组件告诉它。这种做法称为“render prop”;
  • 第 23 行:一个泛型组件:[T] 由行的类型推断得出。每一行都必须有一个 [id],用作 key;
  • 第 37 行:对于每一行,表格调用父组件的函数,并把属于该行的数据(行本身及其索引)传给它。

3.3.3. 父组件

// =========================================================================
// 12-composition/src/App.tsx - 使用 Card 和 DataTable 模板
// =========================================================================

import { useState } from 'react';
import Card from './Card';
import DataTable from './DataTable';

interface Slot {
  id: number;
  time: string;
  patient: string | null;
}

export default function App() {
  const [slots] = useState<Slot[]>([
    { id: 1, time: '8:00 - 8:20', patient: null },
    { id: 2, time: '8:20 - 8:40', patient: 'Mme Alice DURAND' },
    { id: 3, time: '8:40 - 9:00', patient: null },
  ]);
  const free = slots.filter((c) => c.patient === null).length;

  return (
    <div className="container py-4" style={{ maxWidth: 720 }}>
      <h1 className="h3 mb-3">Example 12 - composition</h1>

      {/* header 和 footer:通过 props 传入的 JSX;标签之间:children */}
      <Card color="primary" header={<span>Schedule of Mme PELISSIER</span>} footer={`${free} free slot(s)`}>
        {/* DataTable<Slot>:T 由各行的类型推断得出 */}
        <DataTable
          rows={slots}
          columns={['#', 'Slot', 'Status']}
          // “render prop”:如何显示一行;c 接收该行,i 是它的序号
          renderRow={(c, i) => (
            <>
              <td>{i + 1}</td>
              <td>{c.time}</td>
              <td>
                {c.patient ? (
                  <span className="badge text-bg-secondary">{c.patient}</span>
                ) : (
                  <span className="badge text-bg-success">Free</span>
                )}
              </td>
            </>
          )}
        />
      </Card>

      <Card color="success" header="A card without a footer">
        <p className="mb-0">The footer is not provided: the card does not display it.</p>
      </Card>

      {/* 没有提供 header:使用默认内容 “Untitled” */}
      <Card>
        <DataTable<{ id: number; name: string }>
          rows={[]}
          columns={['Name']}
          renderRow={(p) => <td>{p.name}</td>}
          empty={<span>Nobody for now.</span>}
        />
      </Card>
    </div>
  );
}
  • 第 28 行:[header] 和 [footer] 接收 JSX 或文本;写在标签之间的 [<DataTable>] 成为卡片的 [children];
  • 第 34–43 行:render prop:如何显示一行;[c] 接收该行(类型为 [Slot],由 [rows] 推导而来),[i] 为它的序号;
  • 第 56 行:列表为空时,[TypeScript] 无法推断出 [T]:需要显式提供;
  • 第 60 行:没有行时显示的内容。

Image

3.4. 示例 13:组件的生命周期

3.4.1. 时钟

// =========================================================================
// 13-lifecycle/src/Clock.tsx - 一个会启动和停止的组件
// -------------------------------------------------------------------------
// 组件的生命周期:
//   1. 它被显示(挂载):React 调用函数并把它的
//      结果放到页面中;然后执行它的副作用(useEffect);
//   2. 它被更新,次数不限(它的状态或
//      props 发生变化);
//   3. 它从页面中被移除(卸载):React 执行它各个副作用的清理函数,
//      即每个副作用返回的那个函数。
// 时钟在出现时启动一个定时器(setInterval)……并且
// 必须在消失时停止它:否则定时器
// 会白白地继续运行(内存泄漏)。
// =========================================================================

import { useEffect, useEffectEvent, useState } from 'react';

interface Props {
  onLog: (message: string) => void;
}

export default function Clock({ onLog }: Props) {
  const [time, setTime] = useState(() => new Date().toLocaleTimeString());

  // useEffectEvent:由副作用调用的函数,它始终读取
  // 最新的 props,而本身不是副作用的依赖项。如果没有
  // 它,onLog 就必须放进下面的依赖项 [...] 中,
  // 而父组件每次显示都会传入一个新函数,于是
  // 定时器每秒都会被停止并重新启动
  const log = useEffectEvent((message: string) => onLog(message));

  // []:没有依赖项。副作用在第一次显示之后只运行一次;
  // 它返回的函数在组件被移除时只运行一次
  useEffect(() => {
    log('Clock: effect - starting the timer');
    const timer = setInterval(() => setTime(new Date().toLocaleTimeString()), 1000);
    // 清理
    return () => {
      clearInterval(timer);
      log('Clock: cleanup - timer stopped');
    };
  }, []);

  return <div className="display-6 font-monospace">{time}</div>;
}

组件的生命周期(第 4–10 行):它先 挂载 (第一次显示),更新 任意多次,最后 卸载 (从页面中移除)。[React] 没有针对每个阶段的独立方法:一切都通过 [useEffect] 完成。

  • 第 34–42 行:[useEffect(effect, [])]:依赖数组为空时,副作用只在第一次显示之后执行一次。它 返回 的函数(第 38–41 行)负责 清理:[React] 在组件从页面中移除时执行它(以及在依赖项变化导致副作用再次执行之前)。时钟在启动时启动一个定时器([setInterval])……并且必须在它消失时停止定时器([clearInterval]):否则定时器会无谓地继续运行,并试图修改一个已不存在的组件的状态;
  • 第 30 行:副作用调用父组件的 [onLog] 函数。严格来说,它应该把该函数放进依赖项:因为副作用用到了一个 prop,所以该 prop 变化时必须重新触发。然而,父组件每次显示时都会创建一个新函数:定时器会被不断地停止并重新启动。[useEffectEvent] ([React] 19.2)创建一个始终调用 [onLog] 最新版本的函数,而它本身不是副作用的依赖项。它只能在副作用内部调用。

3.4.2. 父组件

// =========================================================================
// 13-lifecycle/src/App.tsx
// -------------------------------------------------------------------------
//   - {withClock && <Clock />}:勾选/取消勾选复选框会显示/
//     移除该组件(副作用,然后清理,参见 Clock.tsx);
//   - useRef:对 <input> 元素的引用,在它显示之前为 null;
//     一个副作用在它出现时立刻让它获得焦点;
//   - 一个把标签页标题与输入内容同步的副作用。
//
// 在开发环境中,StrictMode(参见 main.tsx)会挂载每个组件,
// 卸载它,然后立即重新挂载:因此日志显示启动、
// 停止、启动。这是有意为之:清理函数写得不好的副作用
// (一个永不停止的定时器)会立刻暴露自己。在生产环境中,
// 组件只会挂载一次。
// =========================================================================

import { useEffect, useRef, useState } from 'react';
import Clock from './Clock';

export default function App() {
  const [withClock, setWithClock] = useState(true);
  const [log, setLog] = useState<string[]>([]);
  const [search, setSearch] = useState('');
  const [showSearch, setShowSearch] = useState(false);
  const field = useRef<HTMLInputElement>(null);

  function trace(message: string) {
    setLog((j) => [...j, `${new Date().toLocaleTimeString()} ${message}`]);
  }

  // App 第一次显示之后(在开发环境中会执行两次:StrictMode)
  useEffect(() => {
    trace('App: effect of the first display');
  }, []);

  // 字段刚刚出现:让它获得焦点
  useEffect(() => {
    if (showSearch) {
      field.current?.focus();
    }
  }, [showSearch]);

  // 标签页的标题从一开始就跟随输入内容
  useEffect(() => {
    document.title = search ? `Search: ${search}` : 'Example 13';
  }, [search]);

  return (
    <div className="container py-4" style={{ maxWidth: 720 }}>
      <h1 className="h3 mb-3">Example 13 - the lifecycle of a component</h1>

      <div className="card p-3 mb-3">
        <label className="form-check-label mb-2">
          <input type="checkbox" className="form-check-input" checked={withClock}
                 onChange={(e) => setWithClock(e.target.checked)} /> show the clock
        </label>
        {withClock && <Clock onLog={trace} />}
      </div>

      <div className="card p-3 mb-3">
        {!showSearch ? (
          <button className="btn btn-outline-primary align-self-start" onClick={() => setShowSearch(true)}>Search...</button>
        ) : (
          <input ref={field} className="form-control" placeholder="the title of the tab follows the input" value={search}
                 onChange={(e) => setSearch(e.target.value)} />
        )}
      </div>

      <h2 className="h6">Log</h2>
      <ol className="small">
        {log.map((line, i) => <li key={i}>{line}</li>)}
      </ol>
    </div>
  );
}
  • 第 25 行:对搜索字段的 ref,在字段未显示之前为 [null];
  • 第 32–34 行:[App] 第一次显示时的副作用;
  • 第 37–41 行:当字段出现时,让它获得焦点:副作用在显示之后执行,此时元素已经存在,ref 指向它;
  • 第 44–46 行:一个把标签页标题与状态 同步 的副作用;
  • 第 57 行:勾选/取消勾选复选框会显示/隐藏时钟。

启动时,日志令人意外:时钟启动、停止,然后再次启动,并且 [App] 的副作用被执行了两次。这是 [<StrictMode>] (见 [main.tsx])的作用:仅在开发环境中,[React] 会挂载每个组件,卸载它,然后立即重新挂载,以验证它的副作用能否自行清理。写得不好的副作用(例如一个永不停止的定时器)因此会立刻暴露:时钟每次会前进两秒。在生产环境中,组件只会挂载一次。我们还注意到,子组件(时钟)的副作用先于父组件的副作用运行。

然后取消勾选再重新勾选,并在搜索字段中输入“pediatrician”:

Image

副作用是 [React] 中最微妙的部分。有一条规则指导它们的使用:副作用把组件与 [React] 之 外 的 事物 同步(标签页标题、定时器、文档的事件监听器、服务器)。要由一个值计算另一个值,请使用变量(示例 02),而不是副作用。要响应用户操作,请使用事件处理函数,而不是副作用。

3.5. 示例 14:上下文

如何在相距较远的组件之间共享数据和函数,而不必通过所有中间组件逐层传递 props?答案是使用 上下文(Context)。这就是 [React] 共享 [Angular] 存放在其服务中(通过依赖注入提供)的内容的方式。

3.5.1. 整个应用的上下文

// =========================================================================
// 14-contexts/src/contexts/log.tsx - 整个应用的上下文
// -------------------------------------------------------------------------
// 如何在相距较远的组件之间共享数据和函数,
// 而不必通过所有中间组件
// 逐层传递 props?使用上下文(CONTEXT):
//   1. createContext(defaultValue) 创建上下文;
//   2. 一个提供者(PROVIDER)组件 <LogContext value={...}> 把它的
//      值提供给它的所有后代,无论多深;
//   3. 后代组件用 use(LogContext)(或 useContext)读取它。
// 当提供的值变化时,所有读取它的组件都会被
// 再次调用。
//
// 惯例:每个上下文一个文件,导出提供者(一个
// 保存状态的组件)和读取它的 Hook(useLog)。
// React 就是这样共享 Angular 存放在其服务中的内容的。
// =========================================================================

import { createContext, use, useCallback, useMemo, useState, type ReactNode } from 'react';

interface Log {
  lines: string[];
  trace: (message: string) => void;
}

// null:当没有任何提供者包裹组件时读取到的值
const LogContext = createContext<Log | null>(null);

// 提供者:它保存状态,并把状态提供给它的后代
export function LogProvider({ children }: { children: ReactNode }) {
  const [lines, setLines] = useState<string[]>([]);

  // useCallback:两次显示之间保持同一个函数(而不是每次
  // 都创建新函数),这样接收它的组件
  // 就不会显得发生了变化
  const trace = useCallback((message: string) => {
    setLines((l) => [`${new Date().toLocaleTimeString()} ${message}`, ...l].slice(0, 6));
  }, []);

  // useMemo:只有当 lines 变化时才创建新对象
  const value = useMemo(() => ({ lines, trace }), [lines, trace]);

  // React 19:上下文本身就是提供者组件
  return <LogContext value={value}>{children}</LogContext>;
}

// 读取用的 Hook:名称以 “use” 开头
export function useLog(): Log {
  // use(context):最近的提供者所提供的值
  const log = use(LogContext);
  if (log === null) {
    throw new Error('useLog must be used inside a <LogProvider>');
  }
  return log;
}
  • 第 21–24 行:上下文提供的内容:数据和一个函数;
  • 第 27 行:[createContext(defaultValue)] 创建上下文。[null]:未被任何提供者包裹的组件所读取到的值;
  • 第 30–45 行:提供者:一个包含状态并把它传递给其所有后代组件(无论多深)的组件:
    • 第 36 行:[useCallback(fn, [dependencies])] 在两次显示之间传递同一个函数(只要依赖项不变),而不是创建新函数。这里没有依赖项:[setLines] 永远不变;
    • 第 41 行:只有当 [lines] 变化时,才会重新创建所提供的对象。如果没有这些预防措施,提供者每次显示都会提供一个新对象,所有读取该上下文的组件都会被不必要地调用;
    • 第 44 行:从 [React] 19 开始,上下文本身就是提供者组件(以前我们写作 [<LogContext.Provider>]);
  • 第 48–55 行:一个读取用的 Hook。[use(context)] ([React] 19;以前是 [useContext])返回最近的提供者的值。该 Hook 会检查提供者是否存在:明确的错误好过意外的 [null]。

3.5.2. 由组件提供的上下文

// =========================================================================
// 14-contexts/src/contexts/cart.tsx - 由一个组件提供的上下文
// -------------------------------------------------------------------------
// 购物车只提供给组件树的一部分:被
// <CartProvider> 包裹的那些组件(参见 App.tsx)。放在页面
// 两个位置的两个提供者会产生两个相互独立的购物车。
// 提供者自己也可以读取其他上下文:购物车
// 使用日志。
// =========================================================================

import { createContext, use, useMemo, useState, type ReactNode } from 'react';
import { useLog } from './log';

export interface Item {
  label: string;
  price: number;
}

interface Cart {
  items: Item[];
  total: number;
  add: (item: Item) => void;
  remove: (index: number) => void;
}

const CartContext = createContext<Cart | null>(null);

export function CartProvider({ children }: { children: ReactNode }) {
  const { trace } = useLog();
  const [items, setItems] = useState<Item[]>([]);

  const value = useMemo<Cart>(
    () => ({
      items,
      total: items.reduce((sum, a) => sum + a.price, 0),
      add: (item) => {
        setItems((a) => [...a, item]);
        trace(`cart: + ${item.label}`);
      },
      remove: (index) => {
        trace(`cart: - ${items[index].label}`);
        setItems((a) => a.filter((_, i) => i !== index));
      },
    }),
    [items, trace],
  );

  return <CartContext value={value}>{children}</CartContext>;
}

export function useCart(): Cart {
  const cart = use(CartContext);
  if (cart === null) {
    throw new Error('useCart must be used inside a <CartProvider>');
  }
  return cart;
}

购物车只提供给组件树的一部分:被 [<CartProvider>] 包裹的那些组件。放在页面不同位置的两个提供者会产生两个相互独立的购物车。

  • 第 29 行:提供者是一个组件;它自己也可以读取其他上下文;购物车使用日志;
  • 第 32–46 行:数据([items]、[total])和操作([add]、[remove]),它们在商品变化时重新计算。

3.5.3. 带配置的上下文

// =========================================================================
// 14-contexts/src/contexts/clock.tsx - 一个带参数的上下文
// -------------------------------------------------------------------------
// 一个时钟,它的刷新周期是提供者的一个 prop:
// <ClockProvider period={5000}>。两个嵌套的
// 提供者:组件读取离它最近的那个。
// 当它的提供者消失时,时钟会停止(副作用的清理)。
// =========================================================================

import { createContext, use, useEffect, useState, type ReactNode } from 'react';

// 默认值:一个固定的日期,由没有提供者的组件读取
const ClockContext = createContext<Date>(new Date());

export function ClockProvider({ period = 1000, children }: { period?: number; children: ReactNode }) {
  const [now, setNow] = useState(() => new Date());

  // [period]:如果父组件改变了周期,定时器会被重新启动
  useEffect(() => {
    const timer = setInterval(() => setNow(new Date()), period);
    return () => clearInterval(timer);
  }, [period]);

  return <ClockContext value={now}>{children}</ClockContext>;
}

export function useClock(): Date {
  return use(ClockContext);
}
  • 第 13 行:这里是一个真正的默认值:一个固定的日期;
  • 第 15 行:刷新周期是提供者的一个 prop;
  • 第 19–22 行:定时器;如果父组件改变了周期,副作用会被清理,然后重新启动。

3.5.4. 组件

// 14-contexts/src/Catalog.tsx - 向购物车添加商品的后代组件
import { useCart, type Item } from './contexts/cart';

const CATALOG: Item[] = [
  { label: 'Consultation', price: 30 },
  { label: 'Vaccine', price: 12.5 },
  { label: 'Certificate', price: 5 },
];

export default function Catalog() {
  // 由 App 提供的购物车(如果没有人提供它,则报错)
  const cart = useCart();

  return (
    <ul className="list-group">
      {CATALOG.map((a) => (
        <li key={a.label} className="list-group-item d-flex justify-content-between align-items-center">
          {a.label} (€{a.price})
          <button className="btn btn-sm btn-outline-primary" onClick={() => cart.add(a)}>Add</button>
        </li>
      ))}
    </ul>
  );
}

[useCart()]:由父组件提供的购物车(如果没有父组件提供它,则报错)。

// =========================================================================
// 14-contexts/src/CartSummary.tsx
// -------------------------------------------------------------------------
// 另一个后代组件:与 Catalog 使用同一个购物车(由 App 提供),
// 但有它自己的时钟,每 5 秒刷新一次。组件只读取
// 位于它上方的提供者:因此 CartSummary 在它的内容周围
// 放置了第二个 <ClockProvider>,并把内容交给一个
// 小组件 Content。
// =========================================================================

import { ClockProvider, useClock } from './contexts/clock';
import { useCart } from './contexts/cart';

function Content() {
  const cart = useCart();
  const now = useClock(); // 最近的时钟:5 秒的那个

  return (
    <div className="card p-3">
      <h2 className="h6">
        Cart ({cart.items.length} item(s)) - {now.toLocaleTimeString()}
      </h2>
      <ul className="mb-2">
        {cart.items.map((a, i) => (
          <li key={i}>
            {a.label}{' '}
            <button className="btn btn-link btn-sm p-0 align-baseline" onClick={() => cart.remove(i)}>remove</button>
          </li>
        ))}
      </ul>
      <strong>Total: €{cart.total}</strong>
    </div>
  );
}

export default function CartSummary() {
  return (
    <ClockProvider period={5000}>
      <Content />
    </ClockProvider>
  );
}
  • 第 14–34 行:摘要内容读取购物车和时钟。最近的时钟是 5 秒的那个;
  • 第 36–42 行:组件只会读取位于它 上方 的提供者:因此 [CartSummary] 在子组件 [Content] 周围放置了它自己的 [<ClockProvider period={5000}>]。
// =========================================================================
// 14-contexts/src/App.tsx - 三层上下文
// -------------------------------------------------------------------------
//   - 日志:提供在最顶层(main.tsx),面向整个应用;
//   - 购物车,由 App 提供:由 Catalog 和 CartSummary 共享,
//     它们看到的是同一个购物车;
//   - 时钟,由 App 提供(默认周期,1 秒)并且由
//     CartSummary 提供(5 秒):各有各的时钟。
// =========================================================================

import Catalog from './Catalog';
import CartSummary from './CartSummary';
import { useLog } from './contexts/log';
import { ClockProvider, useClock } from './contexts/clock';
import { CartProvider } from './contexts/cart';

// App 的时钟的时间:一个小组件,放在提供者下方
function AppTime() {
  return <p className="text-muted">Clock of App: {useClock().toLocaleTimeString()}</p>;
}

export default function App() {
  const log = useLog();

  return (
    <ClockProvider>
      <CartProvider>
        <div className="container py-4" style={{ maxWidth: 720 }}>
          <h1 className="h3 mb-3">Example 14 - contexts</h1>
          <AppTime />
          <div className="row g-3">
            <div className="col-md-6"><Catalog /></div>
            <div className="col-md-6"><CartSummary /></div>
          </div>
          <h2 className="h6 mt-3">Log (root context)</h2>
          <ul className="small">
            {log.lines.map((line, i) => <li key={i}>{line}</li>)}
          </ul>
        </div>
      </CartProvider>
    </ClockProvider>
  );
}
  • 第 18–20 行:[App] 提供时钟;要读取它,需要一个位于它下方的组件:[AppTime];
  • 第 23 行:[App] 读取上方提供的日志;
  • 第 26–27 行:[App] 向其后代组件提供时钟(1 秒)和购物篮。

日志的提供者放在最顶层:

// =========================================================================
// 14-contexts/src/main.tsx - 日志的提供者包裹着 App:因此
// 它在整个应用中都可用
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';
import { LogProvider } from './contexts/log';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <LogProvider>
      <App />
    </LogProvider>
  </StrictMode>,
);

Image

[App] 的时钟每秒前进一次,而购物车的时钟每五秒前进一次。两个组件看到的是同一个购物车,日志记录每一次添加。

对于很少变化的数据(已登录用户、语言、主题)或只适用于页面一部分的数据,一个上下文就足够了。当状态在整个应用中共享且频繁变化时,更适合使用“store”(示例 20)。

3.6. 示例 15:编写自己的 Hook

组件复用 视图;自定义 Hook 复用的是 行为及其状态。它是一个名称以 [use] 开头、并且自身调用其他 Hook 的函数。本示例编写了两个这样的 Hook,对应 [Angular] 课程示例 15 中交给指令的两种行为。

3.6.1. 悬停时高亮元素

// =========================================================================
// 15-custom-hooks/src/hooks/useHover.ts
// -------------------------------------------------------------------------
// 自定义 Hook 是一个名称以 “use” 开头、并且自身调用其他 Hook(useState、useEffect、useRef……)的
// 函数。它
// 允许在多个组件中复用一种行为(连同它的状态),
// 就像组件复用显示那样。
//
// 这个 Hook 高亮悬停的元素。它返回要放到元素上的属性:
// <li {...useHover('#d1e7dd')}>。每次调用都有自己的
// 状态:两个高亮的元素互不干扰。
// =========================================================================

import { useState } from 'react';

export function useHover(color = '#fff3cd') {
  const [hovered, setHovered] = useState(false);
  return {
    style: { backgroundColor: hovered ? color : undefined, transition: 'background-color 0.2s' },
    onMouseEnter: () => setHovered(true),
    onMouseLeave: () => setHovered(false),
  };
}

该 Hook 有自己的状态([hovered]),并返回要应用到元素上的属性:一个样式和两个事件处理函数。每个调用它的组件都有自己的状态:两个高亮元素互不干扰。

3.6.2. 长按

// =========================================================================
// 15-custom-hooks/src/hooks/useLongPress.ts
// -------------------------------------------------------------------------
//     const longPress = useLongPress(() => remove(m), 1000);
//     <button {...longPress.handlers} className={longPress.pressing ? 'press' : ''}>
// 只有按住按钮满一秒才会执行该动作:
// 这是防止误点的保护措施。pressing 表示
// 是否正在按压(用于显示它)。
// 如果组件在按压期间消失,定时器会被停止。
// =========================================================================

import { useEffect, useRef, useState } from 'react';

export function useLongPress(action: () => void, duration = 1000) {
  const [pressing, setPressing] = useState(false);
  // 一个能在多次显示之间保持、却不会引起显示的值:useRef
  const timer = useRef<number | undefined>(undefined);

  // 组件被移除时:不留下孤立的定时器
  useEffect(() => () => clearTimeout(timer.current), []);

  function start() {
    setPressing(true);
    timer.current = window.setTimeout(() => {
      setPressing(false);
      action();
    }, duration);
  }

  function stop() {
    clearTimeout(timer.current);
    setPressing(false);
  }

  return {
    pressing,
    handlers: { onPointerDown: start, onPointerUp: stop, onPointerLeave: stop },
  };
}
  • 第 17 行:定时器的标识符——一个需要在多次显示之间保持、但不用于显示的值——使用 ref;
  • 第 20 行:一个不执行任何动作、只负责清理的副作用:如果按钮被按住期间组件消失,定时器就会被停止;
  • 第 22–28 行:只有按住按钮满一秒才会执行该动作:这是防止误点的保护措施;
  • 第 35–38 行:该 Hook 返回状态([pressing],用于显示它)以及指针事件处理函数(鼠标、手指或触控笔)。

3.6.3. 设置焦点

// =========================================================================
// 15-custom-hooks/src/hooks/autofocus.ts - 一个“ref 回调”
// -------------------------------------------------------------------------
// ref={function}:元素一旦被放到页面中,React 就以该 HTML 元素为参数调用这个函数
// (并且在 React 19 中,当元素被移除时,
// 会调用该函数可能返回的函数)。它不是 Hook:
// 只是一个可在任何地方复用的简单函数:
//     <input ref={autofocus} />
// (React 也处理 autoFocus 属性,它的作用相同。)
// =========================================================================

export function autofocus(element: HTMLElement | null): void {
  element?.focus();
}

ref 回调:你可以给 [ref] 属性赋一个函数,一旦元素被放到页面上,[React] 就会以该 HTML 元素为参数调用它。这不是 Hook,只是一个普通函数。

3.6.4. 用法

// =========================================================================
// 15-custom-hooks/src/App.tsx - 复用行为
// -------------------------------------------------------------------------
// Hook 只能在组件的顶层调用(绝不能在
// 循环、条件或嵌套函数中):React
// 通过调用顺序来识别它们。对于列表中逐行的行为,
// 我们因此为每一行编写一个小组件,由它调用自己的 Hook。
// =========================================================================

import { useState } from 'react';
import { useHover } from './hooks/useHover';
import { useLongPress } from './hooks/useLongPress';
import { autofocus } from './hooks/autofocus';

// 长按期间按钮的样式
const pressStyle = { outline: '4px solid #dc3545' };

// 列表中的一行:它调用自己的 Hook
function DoctorRow({ name, even, onRemove }: { name: string; even: boolean; onRemove: () => void }) {
  // 每两行取一行:默认颜色;其他行为绿色
  const hover = useHover(even ? undefined : '#d1e7dd');
  const longPress = useLongPress(onRemove, 1000);

  return (
    <li className="list-group-item d-flex justify-content-between align-items-center" {...hover}>
      {name}
      <button className="btn btn-sm btn-outline-danger" style={longPress.pressing ? pressStyle : undefined}
              {...longPress.handlers}>
        Delete (long press)
      </button>
    </li>
  );
}

export default function App() {
  const [doctors, setDoctors] = useState(['Mme Marie PELISSIER', 'Mr Paul TATOU', 'Melle Sophie DUPONT']);
  const [message, setMessage] = useState('');

  function remove(name: string) {
    setDoctors((m) => m.filter((x) => x !== name));
    setMessage(`${name} has been deleted.`);
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 15 - writing your own hooks</h1>
      <input ref={autofocus} className="form-control mb-3" placeholder="this field received the focus on its own" />

      <p className="small text-muted">Hover over the rows; hold a button down for one second to delete.</p>
      <ul className="list-group mb-3">
        {doctors.map((m, i) => (
          <DoctorRow key={m} name={m} even={i % 2 === 0} onRemove={() => remove(m)} />
        ))}
      </ul>
      {message && <p className="alert alert-info">{message}</p>}
    </div>
  );
}

Hook 遵循一条严格的规则:只能在组件或其他 Hook 的 顶层 调用,绝不能在循环、条件或嵌套函数中调用。[React] 按调用 顺序来识别每个 [useState]:如果两次显示之间顺序发生变化,各个状态就会混淆。

  • 第 19–33 行:对于列表中逐行的行为,你不能直接在 [map] 中调用 Hook;而应为每一行编写一个小组件,由它调用自己的 Hook;
  • 第 25 行:提示框的属性,展开到该行上;
  • 第 28 行:按钮的长按处理函数,以及它被按下时的样式;
  • 第 47 行:回调 ref;
  • 第 52 行:每位医生一行。

启动时,字段获得焦点。按住第二个按钮:

Image

然后,过了一秒之后:

Image

自定义 Hook 是在 [React] 中复用代码的主要方式。各个库提供了许多这样的 Hook:[useForm] (示例 08)、[useNavigate] (示例 17)、[useTranslation] (示例 21)、[useQuery](示例 24)……

3.7. 示例 16:可复用的确认窗口

“确定吗?”:[window.confirm()] 虽然存在,但它的按钮无法设置格式,也无法翻译。我们用一个由上下文控制的 [Bootstrap] 窗口来取代它。

3.7.1. 上下文

// =========================================================================
// 16-confirmation/src/confirmation/confirmation.tsx
// -------------------------------------------------------------------------
// “确定吗?”:window.confirm() 虽然存在,但既不能
// 设置样式,它的按钮也无法翻译。我们用一个由上下文驱动的 Bootstrap
// 对话框来取代它(参见示例 14)。
//
// 诀窍:confirm(message) 返回一个 promise,当用户做出回应时,它会解析为 true(是)
// 或 false(否)。这样,调用代码就能写得
// 和使用 window.confirm 时一样简单:
//
//     const confirm = useConfirmation();
//     if (await confirm('Delete this doctor?')) { ... }
//
// 提供者自己负责显示对话框:它只需放置
// 一次,包裹整个应用(参见 main.tsx)。
// =========================================================================

import { createContext, use, useCallback, useRef, useState, type ReactNode } from 'react';
import ConfirmDialog from './ConfirmDialog';

type Confirm = (message: string) => Promise<boolean>;

const ConfirmationContext = createContext<Confirm | null>(null);

export function ConfirmationProvider({ children }: { children: ReactNode }) {
  const [message, setMessage] = useState<string | null>(null); // null:对话框关闭
  // 用来解析当前 promise 的函数:它不用于显示,
  // 因此是 ref 而不是状态
  const answer = useRef<((yes: boolean) => void) | null>(null);

  const confirm = useCallback<Confirm>((text) => {
    answer.current?.(false); // 还有未回答的问题?这意味着“否”
    setMessage(text);
    return new Promise<boolean>((resolve) => {
      answer.current = resolve;
    });
  }, []);

  function respond(yes: boolean) {
    setMessage(null);
    const r = answer.current;
    answer.current = null;
    r?.(yes);
  }

  return (
    <ConfirmationContext value={confirm}>
      {children}
      {message !== null && <ConfirmDialog message={message} onAnswer={respond} />}
    </ConfirmationContext>
  );
}

export function useConfirmation(): Confirm {
  const confirm = use(ConfirmationContext);
  if (confirm === null) {
    throw new Error('useConfirmation must be used inside a <ConfirmationProvider>');
  }
  return confirm;
}

提示:[confirm(message)] 返回一个 promise,当用户做出回应时,它会解析为 [true] (是)或 [false] (否)。这样,调用代码就和使用 [window.confirm] 时一样简单:[if (await confirm('Delete this doctor?')) {...}]。

  • 第 22 行:上下文提供的内容:一个函数;
  • 第 27 行:显示的消息;[null]:窗口关闭;
  • 第 30 行:用来解析当前 promise 的函数。它不用于显示:它是 ref,而不是状态;
  • 第 32–38 行:打开窗口并返回一个 promise,其解析函数被保存为 [resolve]。未回答的问题按“否”处理;
  • 第 40–45 行:响应:关闭窗口并解析 promise;
  • 第 50 行:当有问题需要确认时,提供者自己负责显示窗口。

3.7.2. 窗口

// =========================================================================
// 16-confirmation/src/confirmation/ConfirmDialog.tsx
// -------------------------------------------------------------------------
// 模态对话框:
//   - 与真正的模态窗口使用相同的 Bootstrap 类(.modal、.modal-backdrop),
//     直接“写死”显示(show d-block):无需 Bootstrap 的
//     JavaScript;
//   - createPortal:对话框被放在 <body> 的末尾,而不是
//     组件所写的位置。这样它就避开了其祖先的样式
//     (overflow、z-index……),同时仍是一个普通的 React
//     组件(props、事件);
//   - 键盘:Escape = 否;打开时焦点放在“否”按钮上(这是
//     最安全的选择)。
// =========================================================================

import { useEffect } from 'react';
import { createPortal } from 'react-dom';

interface Props {
  message: string;
  onAnswer: (yes: boolean) => void;
}

export default function ConfirmDialog({ message, onAnswer }: Props) {
  // Escape,在页面任何位置:打开时在 DOCUMENT 上设置一个监听器,
  // 关闭时移除它(副作用的清理)
  useEffect(() => {
    const onKeydown = (e: KeyboardEvent) => {
      if (e.key === 'Escape') onAnswer(false);
    };
    document.addEventListener('keydown', onKeydown);
    return () => document.removeEventListener('keydown', onKeydown);
  }, [onAnswer]);

  return createPortal(
    <>
      <div className="modal-backdrop fade show"></div>
      {/* 点击背景(而不是对话框内部)表示“否” */}
      <div className="modal fade show d-block" tabIndex={-1} role="alertdialog" aria-modal="true"
           onClick={(e) => e.target === e.currentTarget && onAnswer(false)}>
        <div className="modal-dialog modal-dialog-centered">
          <div className="modal-content">
            <div className="modal-header">
              <h5 className="modal-title">Confirmation</h5>
              <button type="button" className="btn-close" aria-label="Close" onClick={() => onAnswer(false)}></button>
            </div>
            <div className="modal-body">
              <p className="mb-0">{message}</p>
            </div>
            <div className="modal-footer">
              {/* autoFocus:这个按钮出现时,React 让它获得焦点 */}
              <button type="button" className="btn btn-secondary" autoFocus onClick={() => onAnswer(false)}>No, go back</button>
              <button type="button" className="btn btn-danger" onClick={() => onAnswer(true)}>Yes, confirm</button>
            </div>
          </div>
        </div>
      </div>
    </>,
    document.body,
  );
}
  • 第 27–33 行:Esc 键,在页面任何位置都有效:窗口打开时,在 DOCUMENT 上附加一个监听器,窗口关闭时移除它(清理)。这正是副作用的典型用途:连接到 [React] 之外的事物;
  • 第 35 行:[createPortal(jsx, element)] 把 JSX 显示在组件所写位置之外的地方:这里是 [<body>] 的末尾。这样窗口就绕开了其祖先元素的样式([overflow]、[z-index]……),同时仍是一个普通的 [React] 组件(有 props 和事件);
  • 第 37–39 行:真正的模态窗口所用的 [Bootstrap] 类,直接写死([show d-block]):无需 [Bootstrap] 的 [JavaScript];
  • 第 40 行:点击背景(而不是窗口内部)视为“否”;
  • 第 52 行:[React] 在窗口出现时让“否”按钮获得焦点——这是最安全的选择。

3.7.3. 用法

// =========================================================================
// 16-confirmation/src/App.tsx - 使用确认对话框
// -------------------------------------------------------------------------
// 与 NestJS 课程的示例 21 是同一个页面(链接、按钮、确认),
// 但没有任何到服务器的往返。
// =========================================================================

import { useState } from 'react';
import { useConfirmation } from './confirmation/confirmation';

interface Contact {
  id: number;
  name: string;
}

export default function App() {
  const confirm = useConfirmation();
  const [contacts, setContacts] = useState<Contact[]>([
    { id: 1, name: 'Jean MARTIN' },
    { id: 2, name: 'Alice DURAND' },
    { id: 3, name: 'Luc GERMAN' },
  ]);
  const [message, setMessage] = useState('');

  // 一个 async 函数:它“等待”用户的回答
  async function remove(c: Contact) {
    if (!(await confirm(`Delete the contact ${c.name}?`))) {
      setMessage('Deletion cancelled.');
      return;
    }
    setContacts((list) => list.filter((x) => x.id !== c.id));
    setMessage(`${c.name} has been deleted.`);
  }

  async function removeAll() {
    if (await confirm(`Delete the ${contacts.length} contacts?`)) {
      setContacts([]);
      setMessage('All the contacts have been deleted.');
    }
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 16 - a confirmation dialog</h1>
      <ul className="list-group mb-3">
        {contacts.map((c) => (
          <li key={c.id} className="list-group-item d-flex justify-content-between align-items-center">
            {c.name}
            <button className="btn btn-sm btn-outline-danger" onClick={() => remove(c)}>Delete</button>
          </li>
        ))}
        {contacts.length === 0 && <li className="list-group-item text-muted">No contacts.</li>}
      </ul>
      <button className="btn btn-danger" disabled={contacts.length === 0} onClick={removeAll}>Delete all</button>
      {message && <p className="alert alert-info mt-3">{message}</p>}
    </div>
  );
}
  • 第 17 行:确认函数;
  • 第 26–33 行:一个 [async] 函数:它“等待”([await])用户的响应,而不会阻塞页面。
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';
import { ConfirmationProvider } from './confirmation/confirmation';

// 确认对话框,整个应用只有一个
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfirmationProvider>
      <App />
    </ConfirmationProvider>
  </StrictMode>,
);

整个应用只使用一个窗口:它的提供者包裹着 [App]。

Image

确认,然后请求再次删除并按 Esc:

Image