antd ColorPicker 触发器文本渲染：全面掌握 `showText` 的默认行为与函数式自定义

导读

本文以 Rendering Trigger Text 示例 为切入点，系统讲解 antd 中 ColorPicker 触发器文本（trigger text）的渲染机制：当 showText 为 true 时组件会展示默认颜色文本；当你需要完全掌控触发区文案或插入图标等任意 ReactNode 时，可让 showText 接收一个函数并按需返回自定义内容。阅读完本文，你将能够熟练区分默认文本与函数式自定义两种用法，理解触发文本在不同色彩格式、透明色与渐变色下的渲染规则，并掌握如何在受控展开（open）场景下让文本随面板状态联动。

示例背景：一段演示代码三种用法

关联文档（components/color-picker/demo/text-render.md）描述的是同目录下的可运行示例 text-render.tsx，它在同一个页面里并排展示了 showText 的三种典型写法：

import React, { useState } from 'react';
import { DownOutlined } from '@ant-design/icons';
import { ColorPicker, Space } from 'antd';

const Demo = () => {
  const [open, setOpen] = useState(false);
  return (
    <Space vertical>
      {/* 1. 布尔值：渲染默认颜色文本 */}
      <ColorPicker defaultValue="#1677ff" showText allowClear />
      {/* 2. 函数：基于 color 对象返回自定义文本 */}
      <ColorPicker
        defaultValue="#1677ff"
        showText={(color) => <span>Custom Text ({color.toHexString()})</span>}
      />
      {/* 3. 函数 + 受控展开：文本内容随面板开合联动 */}
      <ColorPicker
        defaultValue="#1677ff"
        open={open}
        onOpenChange={setOpen}
        showText={() => (
          <DownOutlined
            rotate={open ? 180 : 0}
            style={{
              color: 'rgba(0, 0, 0, 0.25)',
            }}
          />
        )}
      />
    </Space>
  );
};

export default Demo;

其中第三例并未用触发区展示颜色值，而是借 open/onOpenChange 控制了一个下拉箭头图标（DownOutlined）的旋转方向，属于"函数式渲染任意 ReactNode"的进阶玩法。

showText 的类型与引入版本

在 antd 的公开类型定义中，showText 被声明于 interface.ts：

showText?: boolean | ((color: AggregationColor) => React.ReactNode);

• boolean：传入 true 表示展示组件内置的默认颜色文本；false（或默认不传）时触发区只渲染色块，不渲染文本。
• 函数形式：接收当前颜色对象 AggregationColor 作为唯一参数，返回任意 ReactNode（字符串、<span>、图标等均可），彻底接管触发区右侧文本区域的内容。
• 依据 ColorPicker API 文档 中的参数表，该属性自 5.7.0 版本加入。

与 showText 常搭配使用的是控制触发区整体外观的 size（large / medium / small，默认 medium）以及 trigger（hover / click，默认 click），它们共同决定触发器的最终观感。

内置默认文本的渲染规则

当 showText 为布尔值 true 时，真正负责生成文本的是 ColorTrigger.tsx 中的 desc 计算逻辑。从源码可以总结出以下规则：

场景	渲染结果
颜色已被清除（color.cleared）	展示本地化文案，英文语言包下为 Transparent
当前为渐变色（color.isGradient()）	逐段渲染 rgb(...) 百分比%，并在面板激活某色标时对非激活段附加 -inactive 样式
单色且格式为 hex（默认）	输出大写 #RRGGBB；若带透明度则追加 ,alpha%（如 #1677ff,63%）
单色且格式为 rgb	输出 rgb(...) 形式（color.toRgbString()）
单色且格式为 hsb	输出 hsb(...) 形式（color.toHsbString()）

几点关键实现细节：

• 格式与文本联动：showText 的默认文本跟随 ColorPicker 面板中当前选中的颜色格式（hex / rgb / hsb）变化。该格式状态由 ColorPicker.tsx 中的 format / defaultFormat 受控管理，格式切换后 ColorTrigger 会依据 format 重新计算文本。
• 颜色方法来源：函数参数 AggregationColor 封装了 color.ts 中定义的对象能力，提供 toHexString()、toRgbString()、toHsbString()、toCssString() 等系列转换方法，渐变场景还提供 isGradient() 与 getColors()，这些就是你在自定义函数里可以放心调用的 API。
• DOM 结构：文本始终渲染在 ant-color-picker-trigger-text 容器内（前缀由 prefixCls 推导，最终类名为 .ant-color-picker-trigger-text），色块与文本共同构成触发区。该结构可作为编写样式覆盖或测试断言的依据。

组件源码的完整链路为：ColorPicker（外层 Popover + 状态管理）将 showText、color、format 透传给内部 ColorTrigger，由后者在 useMemo 中根据颜色状态与格式计算默认文本；当 showText 是函数时，则直接执行 showText(color) 获取返回值（源码中通过 isFunction(showText) 判断分支）。

函数式自定义的实战要点

将 showText 作为函数使用时，需要注意：

1. 函数每次渲染都会执行：由于 desc 的生成依赖 color、format、showText、activeIndex 等状态，只要颜色或面板状态变化，渲染函数就会被重新调用以产出最新文本。这意味着你可以放心在函数体内读取实时颜色，比如示例中的 color.toHexString() 每次都会随选色结果更新。
2. 颜色参数可执行全套转换：函数收到的 AggregationColor 与默认分支内部使用的是同一对象，可用方法完全一致（toHexString / toRgbString / toHsbString / toCssString、isGradient / getColors 等），因此自定义文本依然能忠实反映当前颜色，不会丢失状态。
3. 返回值必须是 ReactNode：字符串、JSX 元素、图标均可；若返回 null 或空内容，触发区将表现为只有色块。示例第三例把 showText 与 open/onOpenChange 受控展开结合，仅通过旋转箭头方向来提示面板开合状态，说明该函数并非只能展示颜色信息。
4. 可与 allowClear 组合：示例第一例同时开启了 allowClear。当用户清除颜色后，默认文本会切换为 Transparent（参见默认规则表），此时自定义函数同样会收到"已清除"状态的颜色对象，你可以据此决定展示占位文案。

测试用例如何验证这些行为

ColorPicker 测试文件 中覆盖了与本文直接相关的若干断言，可作行为基准：

• Should showText as render function work：断言 showText={(color) => color.toHexString()} 时 .ant-color-picker-trigger-text 存在且 innerHTML 为 #1677ff，验证函数返回值直接进入文本节点。
• showText with transparent：defaultValue={null} 且 showText 为布尔值，断言文本内容为 Transparent，验证清除状态的默认文案。
• Should showText work：defaultValue="#1677ff"、open 开启且 showText 为 true 时，切换面板格式为 HSB 后断言文本变为 hsb(215, 91%, 100%)，随后继续验证切换到 RGB 的文本联动——从测试层面坐实了"默认文本跟随面板格式切换"这一行为。

应用建议与边界提醒

• 当颜色值的可读性比界面简洁更重要时（例如表单中需要用户确认最终 HEX 值），直接使用布尔值 showText 并让面板格式锁定为 hex 即可获得默认的 #RRGGBB 大写输出。
• 当需要品牌化文案、多语言拼接、或更灵活的图标指示时，优先采用函数形式；注意函数接收的颜色对象可能处于渐变或清除状态，建议先通过 isGradient() 等方法做分支处理，避免对颜色值直接做字符串拼接而产生意料之外的格式。
• 函数形式返回的内容只会渲染在触发区的文本容器中，不会影响色块区域与 Popover 面板本身；如需整体改造面板内容，则应使用 panelRender 而非 showText，二者职责不同，不应混淆。
• 本文示例与文档均基于当前仓库源码：示例代码见 text-render.tsx，接口声明见 interface.ts，触发文本实现见 ColorTrigger.tsx。如需在本地复现，可将上述示例代码直接放入项目页面运行（需依赖 antd 5.7.0 及以上版本）。