本文以decap-cms-widget-text包的 CHANGELOG.md 为主线，结合当前仓库中的源码、配置示例与构建脚本，梳理该多行文本（textarea）组件从 2018 年诞生至今的完整演进路径，并深入讲解其实现原理、配置方式与版本兼容要点。读完本文，你将掌握 Decap CMS 中text控件的使用姿势、组件内部的工作机制，以及围绕该包发生的历次关键变更（包名迁移、依赖升级、构建产物演进）对实际项目的影响。

一、组件定位：text控件是什么

decap-cms-widget-text是 Decap CMS 官方发布的独立 widget 包，包描述为 "Widget for editing multiline plain string values in Decap CMS"（见 package.json）。它对应配置文件中widget: 'text'的字段类型，提供的是一个多行纯文本输入框（textarea），与单行string控件、支持富语义的markdown控件形成互补——它不解析 Markdown，也不做富文本渲染，适合存放"普通的多行文本，而非 Markdown"（开发示例配置中明确标注了hint: 'Plain text, not markdown'，见 dev-test/config.yml）。

1.1 配置文件中的声明方式

在 Decap CMS 的集合配置中，text控件与普通字段一样声明即可，最简单的形式是：

- { label: 'Text', name: 'text', widget: 'text' }

也可以补充hint提示文案，例如仓库开发环境（kitchen sink）中的完整写法：

- { label: 'Text', name: 'text', widget: 'text', hint: 'Plain text, not markdown' }

同一配置还出现在各后端测试目录中，例如 dev-test/backends/azure/config.yml、dev-test/backends/github/config.yml 等，说明text控件是各后端联调时的通用基础字段。

1.2 在 monorepo 中的注册链路

Decap CMS 采用 monorepo 结构（当前仓库的pnpm-workspace.yaml与lerna.json佐证了这一点），所有官方 widget 统一在应用入口中注册。查看 packages/decap-cms-app/src/extensions.js，可以看到：

import DecapCmsWidgetText from 'decap-cms-widget-text'; // ... CMS.registerWidget([ // ... DecapCmsWidgetText.Widget(), // ... ]);

widget 包通过index.js导出一个Widget(opts)工厂函数（见 packages/decap-cms-widget-text/src/index.js），返回{ name: 'text', controlComponent, previewComponent, ...opts }结构，并同时导出DecapCmsWidgetText命名空间与默认导出，兼容 ESM 与 UMD 两种消费方式。

二、源码解析：多行文本框的实现细节

该包源码体量很小，只有三个文件（src 目录），但其中包含若干值得注意的实现细节。

2.1 编辑器控件 TextControl

TextControl.js 是一个基于react-textarea-autosize的多行输入组件，核心要点如下：

• props 契约：接收onChange（必填）、forID、value、classNameWrapper、setActiveStyle、setInactiveStyle，其中value默认值为空字符串''。
• 渲染参数：minRows={5}保证至少显示 5 行；css={{ fontFamily: 'inherit' }}继承外部字体（这正是 CHANGELOG 中 2.0.6 版本 "set correct font family" 修复的落地体现）；onChange={e => onChange(e.target.value)}直接将 textarea 的原始字符串值上抛。
• 焦点样式：onFocus={setActiveStyle}与onBlur={setInactiveStyle}配合 Decap CMS 的 UI 体系切换输入框激活态。
• 强制更新的注释：shouldComponentUpdate()恒返回true，源码注释解释了原因——当该控件嵌套在list组件中且列表项被重排时，react-textarea-autosize可能停留在最小高度状态，恒更新能保证高度被正确重新计算；同时注释也坦诚指出"该做法成本较低但未来应做优化"。

2.2 预览组件 TextPreview

TextPreview.js 极为简洁，直接使用decap-cms-ui-default包提供的WidgetPreviewContainer包裹value进行渲染——这解释了 package.json 中decap-cms-ui-default作为 peerDependency 存在的原因（见 package.json）。

2.3 包结构与构建

从 package.json 可以读出完整的工程信息：

• 双入口：module: "dist/esm/index.js"（ESM 构建产物）+main: "dist/decap-cms-widget-text.js"（webpack 打包产物），对应 CHANGELOG 中 2.2.0 "add ES module builds" 与 2.1.0-beta.0 "provide usable UMD builds" 两个里程碑。
• 构建脚本：build走cross-env NODE_ENV=production webpack，build:esm走 Babel 输出到dist/esm；develop提供build:esm --watch的开发热构建。
• 依赖关系：运行时仅依赖react-textarea-autosize（catalog 版本管理，见根目录pnpm-lock.yaml）；peerDependencies 为@emotion/react、decap-cms-ui-default、prop-types、react。
• license 与元数据：MIT 协议，keywords 包含decap-cms、widget、string、text、textarea、mulitiline（原文拼写如此），sideEffects: false便于 tree-shaking。

三、版本演进：从 CHANGELOG 看关键节点

decap-cms-widget-text的 CHANGELOG.md 遵循 Conventional Commits 规范记录，虽然多数版本是"仅版本号提升（Version bump only）"，但其中穿插的 Feature / Bug Fix 条目构成了组件演进的关键脉络。以下按时间倒序梳理对使用者有实际意义的节点：

3.1 最重要的变更：2023 年的包重命名

版本 2.5.0-beta.0（2023-08-18，PR #6863 "rename packages"）是整个 CHANGELOG 中最具里程碑意义的一笔：该包在本次变更中从原 netlify-cms 体系正式更名为 decap-cms 体系（包名由netlify-cms-widget-text变为decap-cms-widget-text）。随后 3.0.0（2023-08-18）与 3.0.1（2023-08-25）完成版本号衔接与 peerDependencies 修正（#6886），形成当前仓库中 3.x 主版本线的起点。

对升级者的直接影响：如果旧项目使用的是netlify-cms-widget-text，迁移时需要同步修改 package.json 中的依赖名，并确认CMS.registerWidget的引用方式与新包导出一致（新包导出DecapCmsWidgetText，见 src/index.js）。

3.2 依赖升级的两条主线

从 CHANGELOG 可以归纳出该组件依赖演进的两条主线：

1. textarea 自动高度库：2.3.4（2020-09-15，#4312）将react-textarea-autosize升级到 v8，这是当前 package.json 中唯一运行时依赖的版本来源。
2. React 与样式体系：2.4.0（2021-05-04，#5316）加入 React 17 peerDependency；2.0.7-beta.0（2019-03-15，#2166）升级 Emotion 10；3.0.1（2023-08-25，#6886）再次更新 peerDependencies。这些变更直接决定了使用方项目必须满足的 React / Emotion 版本环境，也是 3.1.3（2024-08-13）一度回退 #7264 依赖更新的原因——依赖升级并非总是安全，回退记录提醒我们在升级时关注锁文件与 peer 约束。

3.3 构建体系的三次补全

2019 年上半年是构建体系集中建设的时期：

• 2.1.0-beta.0（#2141）：提供可用的UMD 构建，支持<script>直接引用的使用场景；
• 2.2.0（#2215）：新增ES module 构建，让现代打包器可以正确 tree-shaking；
• 2.2.1-beta.1（#2244）：修复 decap-cms 聚合包上的导出与 ESM maps。

这三次变更奠定了当前 package.json 中module+main双入口的结构，也是 2.x 时代围绕"发行物可用性"的典型迭代。

3.4 周边联动：与 markdown/code 组件的关系

2.3.0（2019-12-16，#2828 "Code Widget + Markdown Widget Internal Overhaul"）是 CHANGELOG 中唯一直接涉及功能重构的大版本。该 PR 同时推动了代码控件与 Markdown 控件内部重构，从仓库结构可以佐证其背景：仓库同时存在decap-cms-widget-markdown、decap-cms-widget-richtext、decap-cms-widget-code等多个文本族组件（见 packages 目录）。这意味着text控件在 Decap CMS 的字段类型谱系中处于"最朴素的多行字符串"位置，而 Markdown / 富文本 / 代码块控件则承担更重的编辑能力——这也是选型时判断"用text还是markdown"的重要依据。

四、从仓库实测数据看使用边界

• 无独立测试用例：从 packages/decap-cms-widget-text 的目录结构看，本包没有自己的__tests__目录，属于薄封装组件，其行为更多依赖上游react-textarea-autosize与decap-cms-ui-default的稳定性。
• 配置层面的通用性：widget: text在仓库的 kitchen sink 配置中广泛出现于对象嵌套字段（dev-test/config.yml）、列表嵌套字段（dev-test/config.yml）等复合结构中，证明其可以安全地用于嵌套场景；而 TextControl 源码中"恒更新保证嵌套列表重排后高度正确"的注释，正是对这种嵌套使用的直接回应。
• 渲染行为：预览时不做任何格式处理，WidgetPreviewContainer直接透出字符串（TextPreview.js），因此输入中的换行会以纯文本形式呈现，不会像 markdown 那样被转换。

五、结语

decap-cms-widget-text是一个"小而不简单"的组件：源码仅三个文件，却完整覆盖了 Decap CMS 的 widget 注册协议、peerDependency 约束、双构建产物体系，并在 CHANGELOG 中留下了从 2018 年首发、2019 年构建体系补全、2020-2021 年依赖升级、直至 2023 年包重命名与 3.x 主版本线的完整轨迹。对于要在 Decap CMS 项目中自定义或审计官方 widget 的开发者而言，这个包是理解 widget 包结构的理想最小样例；而对于维护者来说，CHANGELOG 中的回退记录与 peer 依赖调整，也是评估依赖升级风险时值得参考的实战素材。