cds-textarea 渲染结构全解析从快照到源码的 Carbon Web Components 多行文本框深度指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncds-textarea是 IBM Carbon Design System 在 Web Components 包carbon/web-components中提供的多行文本输入组件。本指南以 cds-textarea 渲染快照文档 为骨架逐层拆解其完整的 Shadow DOM 渲染结构并结合 textarea.ts 源码、单元测试 与 Storybook 示例讲清它的全部属性、插槽、计数器、校验状态与骨架屏变体帮助你在真实项目中正确使用与排查该组件。快照文档是什么组件渲染的“契约基准”在packages/web-components/tests/snapshots/目录下存放着一批以组件命名的 Markdown 快照cds-btn.md、cds-input.md、cds-textarea.md、data-table.md等。它们记录的是组件在指定测试场景下渲染出的完整 DOM 输出本质上是组件渲染行为的“契约基准”——任何一次模板结构调整都会导致快照内容变化从而被版本控制系统捕获。cds-textarea.md对应的是Should render with various attributes场景即组件同时携带disabled、placeholder、readonly、rows等多种属性时的最终渲染结果是观察该组件输出结构最直接的入口。从快照看完整渲染结构四层 DOM 解剖快照中cds-textarea的 Shadow DOM 输出由四个结构块组成下面逐层说明每个节点在 textarea.ts 的render()方法中对应的实现位置与作用。第一层标签与计数器区域cds--text-area__label-wrapperdiv classcds--text-area__label-wrapper label classcds--label cds--label--disabled forinput slot namelabel-text/slot /label /div标签通过slot namelabel-text渲染默认内容label属性文本作为 slot 的回退值。快照中标签带cds--label--disabled因为场景中设置了disabled属性对应源码中labelClasses的classMap逻辑textarea.ts。forinput与内部textarea idinput建立关联保证点击标签可聚焦输入区。当启用计数器时同一个label-wrapper内还会渲染计数标签cds--text-area__label-counter默认不出现见后文“计数器”一节。第二层文本域包装cds--text-area__wrapperdiv classcds--text-area__wrapper cds--text-area__wrapper--readonly textarea classcds--text-area disabled idinput placeholderplaceholder-foo readonly rows4 /textarea /div内部textarea的类名为cds--text-area并携带idinput、placeholderplaceholder-foo、rows4、disabled、readonly与快照场景设置一一对应。包装节点带cds--text-area__wrapper--readonly修饰类textarea.ts设置cols时还会追加cds--text-area__wrapper--cols。源码中textarea会接收autocomplete、autofocus、cols、name、pattern、maxlength、value等透传属性并绑定keydown、paste、input、change四个事件textarea.ts。校验状态下同一层还会出现data-invalid属性、WarningFilled16invalid或WarningAltFilled16warn图标以及ai-label、slug插槽。第三层辅助文本cds--form__helper-textdiv classcds--form__helper-text cds--form__helper-text--disabled slot namehelper-text helper-text-foo /slot /div辅助文本通过slot namehelper-text渲染helperText属性作为默认回退内容此处显示helper-text-foo。disabled时带cds--form__helper-text--disabled对应源码 textarea.ts 的helperTextClasses。第四层校验消息容器cds--form-requirementdiv classcds--form-requirement hidden slot namewarn-text/slot /div该容器在无校验状态时带hidden属性仅在invalid或warn为真时显示。插槽名动态切换invalid时为invalid-text否则为warn-text默认回退内容分别为invalidText/warnText属性textarea.ts。fluid 变体isFluid的布局差异fluid 模式下校验消息与分割线hr classcds--text-area__divider /被渲染在textarea__wrapper内部非 fluid 模式下辅助文本与校验消息渲染在包装之外textarea.ts。属性 API继承自 CDSTextInput 的完整清单CDSTextarea直接继承CDSTextInputtextarea.ts因此先继承 text-input 的全部表单属性再叠加自身专属属性。以下属性均可通过 HTML 属性或 JS property 使用属性类型/默认值说明定义位置colsNumber / 未定义文本域默认列数设置后 wrapper 追加--cols类textarea.tsrowsNumber /4文本域默认行数textarea.tscounter-modecharacter \| word默认character计数器计算方式非法值变更会被hasChanged拦截textarea.tsis-fluidBoolean /false是否使用 fluid 样式textarea.tsenable-counterBoolean /false是否显示计数器text-input.tsmax-countNumber / 未定义计数上限character 模式下同步为maxlengthtext-input.tslabel/hide-labelString / Boolean标签文本 / 是否视觉隐藏标签cds--visually-hiddentext-input.tshelper-textString辅助说明文本text-input.tsinvalid/invalid-textBoolean / String无效状态及提示文案text-input.tswarn/warn-textBoolean / String警告状态及提示文案text-input.tsdisabled/readonly/requiredBoolean禁用 / 只读 / 必填text-input.tspatternStringHTML 校验正则如[A-Za-z]textarea.tsplaceholder/autocomplete/autofocus/nameString / Boolean原生输入属性透传text-input.tsvalueString当前值getter/setter 直接读写内部textareatext-input.tsvalue的双向同步机制值得注意setter在设置内部_value的同时会直接写入_input.value保证程序化赋值能即时反映到 UI_handleInput又将用户输入同步回组件valuetextarea.ts。计数器机制character 与 word 两种模式enable-counter与max-count同时满足时标签行右侧渲染当前值/上限的计数标签character默认模式按value.length计数同时把max-count写入原生maxlength由浏览器强制限制输入长度。word 模式按正则\p{L}/gu匹配的 Unicode 字母序列计数并且不设置maxlength因为 word 模式无法用原生属性表达改为在事件层手动拦截_onKeyDown在词数已达上限时阻止空格与回车键输入textarea.ts_onPaste在粘贴导致超限时阻止默认粘贴截取前maxCount个词后重新触发input事件textarea.ts。模式切换时updated()会动态添加/移除maxlengthtextarea.ts测试用例 textarea-test.js 完整覆盖了 character→word→character 的往返切换行为。校验与提示状态invalid / warn / helper 的优先级渲染逻辑严格遵循以下优先级与cds-select等组件对齐invalid优先显示WarningFilled16图标与invalid-text否则warn显示WarningAltFilled16警告图标与warn-text辅助文本仅在无 invalid/warn 时可见。在非 fluid 布局中校验消息或辅助文本二选一渲染validationMessage || helper的等价逻辑这与快照中cds--form-requirement默认hidden的行为一致。对应测试见 textarea-test.js。插槽label-text / helper-text / invalid-text / warn-text / ai-label / slug组件提供 6 个命名插槽均可覆盖对应属性文本textarea.ts 的 JSDoc 声明插槽名作用label-text覆盖标签文本helper-text覆盖辅助文本invalid-text覆盖无效提示需invalidwarn-text覆盖警告提示需warnai-label注入 AI Label 装饰触发_handleSlotChange检测slug旧版 slug 装饰位v12 移除插槽渲染的测试用例集中在 textarea-test.js使用assignedNodes({ flatten: true })断言插槽内容生效。骨架屏与 AI Label 扩展骨架屏变体cds-textarea-skeleton是独立的轻量元素渲染一条cds--label cds--skeleton可被hide-label关闭和一个cds--skeleton cds--text-area占位块textarea-skeleton.ts。测试验证了默认与hide-label两种渲染textarea-test.js。AI Label 支持在ai-label插槽中放入cds-ai-label后wrapper 会追加cds--text-area__wrapper--decorator类AI 标签以sizemini内嵌显示示例见 textarea.stories.ts 的WithAILabelstory。事件与表单集成input用户输入时触发并同步valuechange原生change事件不冒泡穿透 Shadow DOM组件通过_handleChange重新派发一个composed: true的change事件保证宿主上监听生效text-input.tsFormData集成_handleFormdata在非disabled时把name/value追加进表单数据text-input.ts组件设置delegatesFocus: true点击标签或容器空白处焦点直达内部textarea。此外updated()中通过ResizeObserver监听 wrapper 尺寸变化将辅助文本与校验消息的max-width对齐 wrapper 宽度并启用overflow-wrap: break-word避免设置cols后提示文字溢出textarea.ts。测试验证与无障碍textarea-test.js 共覆盖 20 场景包括标签/辅助文本渲染、value反射、readonly/disabled、invalid/warn文案、hide-label、cols/rows反射、pattern/required、data-*透传、计数器模式切换、全部插槽渲染以及await expect(el).to.be.accessible()的无障碍断言textarea-test.js。快照文档 cds-textarea.md 中的 DOM 输出正是这些渲染路径的稳定基准。快速上手示例通过 npm 安装carbon/web-components后引入组件使用方式与 Storybook 中的 Default story 一致cds-form-item cds-textarea labelTextArea label helper-textTextArea helper text rows4 enable-counter counter-modecharacter max-count500 placeholderEnter your feedback/cds-textarea /cds-form-itemimport carbon/web-components/es/components/textarea/index.js;自定义插槽、校验与 AI 装饰的完整用法可进一步查阅 textarea.mdx 组件文档与 textarea.stories.ts 中的Default、Skeleton、WithAILabel、WithLayer四个 story。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考