深入解析 Carbon Web Components 的cds-pagination快照渲染结构与组件实现原理【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncds-pagination是 IBM Carbon 设计系统 Web Componentscarbon/web-components中的分页组件它由分页大小选择器cds-page-sizes-select、页码选择器cds-pages-select、状态文本与前后翻页按钮共同组成。本文以仓库中的渲染快照文档 cds-pagination.md 为骨架结合组件源码 pagination.ts、pagination.stories.ts 与测试用例 pagination_spec.ts逐层拆解其 Shadow DOM 输出结构、属性/事件契约与内部状态计算逻辑帮助读者掌握该组件的渲染机制与实际用法。组件总览cds-pagination的内部布局cds-pagination基于 LitElement 实现类定义于 pagination.tscustomElement(${prefix}-pagination) class CDSPagination extends FocusMixin(HostListenerMixin(LitElement)) {从快照渲染结果看其 Shadow DOM 被划分为两个主要区域左侧区域cds--pagination__left包含分页大小下拉框slot namepage-sizes-select、分隔线cds-ce--pagination__divider以及条目统计文本cds--pagination__items-count。右侧区域cds--pagination__right包含默认插槽slot用于放置页码下拉框cds-pages-select、分隔线以及由两个图标按钮构成的控制区cds--pagination__control-buttons。这个布局在render()方法pagination.ts中被实际输出而快照文件正是render()产物的忠实记录。组件样式定义在 pagination.scss 中通过extend .#{$prefix}--pagination继承 Carbon 样式库carbon/styles的分页基础样式并额外声明了cds-ce--pagination__divider分隔线1px、$layer-accent-01背景色等 Web Components 特有的样式。快照一最小属性下的cds-pagination渲染结构当仅以最简方式不显式传属性渲染cds-pagination时快照记录了如下 Shadow DOM 输出div classcds--pagination__left slot namepage-sizes-select /slot div classcds-ce--pagination__divider /div span classcds--pagination__items-count cds--pagination__text Item 1–10 /span /div div classcds-ce--pagination__divider /div div classcds--pagination__right slot /slot div classcds--pagination__control-buttons button classcds--pagination__button cds--pagination__button--backward cds--pagination__button--no-index disabled titlePrevious page /button button classcds--pagination__button cds--pagination__button--forward titleNext page /button /div /div这段输出对应默认属性值page 1、pageSize 10、start 0、totalItems undefined、pagesUnknown false各属性默认值见 pagination.ts。几个值得注意的细节状态文本 Item 1–10来自_renderStatusText()pagination.ts。由于未提供totalItems组件走的是总数不确定分支调用formatStatusWithIndeterminateTotal输出开区间格式${start}–${end} itemsstart为 0 时显示为 1 起始min totalItems 0 ? 0 : start 1。后退按钮被禁用disabled且带cds--pagination__button--no-index类原因是prevButtonDisabled disabled || start 0pagination.ts首页时start 0恒成立。其titlePrevious page来自backwardText默认值pagination.ts。前进按钮未禁用nextButtonDisabled disabled || (!pagesUnknown isLastPage)pagination.ts当总页数未知时始终可用。对应的测试用例是should render cds-pagination with minimum attributespagination_spec.ts它通过toMatchSnapshot({ mode: shadow })以 Shadow DOM 模式匹配快照。快照二多种属性组合下的渲染结构当传入pageSize: 20, start: 10, totalItems: 200时对应测试should render cds-pagination with various attributes见 pagination_spec.ts快照输出为div classcds--pagination__left slot namepage-sizes-select /slot div classcds-ce--pagination__divider /div span classcds--pagination__items-count cds--pagination__text 11–30 of 200 items /span /div div classcds-ce--pagination__divider /div div classcds--pagination__right slot /slot div classcds--pagination__control-buttons button classcds--pagination__button cds--pagination__button--backward titlePrevious page /button button classcds--pagination__button cds--pagination__button--forward titleNext page /button /div /div与最小属性快照的关键差异状态文本变为 11–30 of 200 items此时totalItems是确定值200走formatStatusWithDeterminateTotal分支pagination.ts格式为${start 1}–${Math.min(start pageSize, totalItems)} of ${totalItems} items即11–30 of 200 items。后退按钮不再禁用start 10 0prevButtonDisabled为false因此移除了cds--pagination__button--no-index类和disabled属性。这一对比直观展示了start、pageSize、totalItems三个核心属性如何共同决定状态文本与按钮可用性。快照三cds-page-sizes-select的结构虽然文档中以cds-page-sizes-select命名但在当前版本中每页条数选择框实际由组件内部渲染的cds-select承担带idpage-size-select、pagination、inline等属性见 pagination.ts。快照记录了其内部结构label classcds--pagination__text forselect slot namelabel-text Items per page: /slot /label div classcds--select__item-count select classcds--select-input idselect option value10 10 /option option value20 20 /option option value30 30 /option /select /div div hidden slot /slot /div要点解析标签插槽slot namelabel-text的兜底内容为Items per page:。当使用方在cds-pagination内部通过cds-select-item声明分页大小选项时这些选项通过_handleSlotChangepagination.ts被搬移到内部cds-select的默认插槽中。而items-per-page-text属性会以cds--pagination__text文本的形式注入label-text插槽内容之前pagination.ts。选项即快照中的 10/20/30分页大小选项由使用方通过cds-select-item value1010/cds-select-item提供快照展示的正是 Storybook 默认示例中前三个选项完整示例为 10/20/30/40/50见 pagination.stories.ts。隐藏的默认插槽div hiddenslot/slot/div用于接收被搬移的选项是cds-select内部接收外部内容的标准做法。对应的快照测试是should render cds-page-sizes-select with minimum attributespagination_spec.ts测试注释特别说明需要两次await Promise.resolve()来等待cds-pagination与cds-page-sizes-select两级组件的更新周期完成。快照四cds-pages-select的结构当提供确定的总条数测试中totalItems: 100时页码下拉框会渲染为带无障碍标签的cds-select内部带idpages-select见 pagination.ts。快照输出div classcds--select__page-number label classcds--label cds--visually-hidden forselect Page number, of 10 pages /label select classcds--select-input option selected value0 1 /option option value1 2 /option ... option value9 10 /option /select /div span classcds--pagination__text of 10 pages /span要点解析页数计算totalPages Math.ceil(totalItems / pageSize)100 / 10 10页因此生成 10 个option选项值从 1 到 10对应的value属性是09索引从 0 开始代表行号起点。无障碍设计标签使用cds--visually-hidden类实现视觉隐藏、屏幕阅读器可读文本内容由formatLabelText生成默认值为Page of ${count} page${count 1 ? : s}pagination.ts。补充文本右侧的of 10 pages由formatSupplementalText生成默认逻辑为pagesUnknown或!totalItems时输出page否则输出of ${count} pagespagination.ts。页面裁剪当totalItems: 100时pages-unknown分支不渲染pagesUnknown || !totalItems为假因此渲染页码下拉框而非未知页数纯文本pagination.ts。对应测试为should render cds-pages-select with minimum attributespagination_spec.ts。核心属性与事件契约快照之外组件的完整 API 可以通过 pagination.stories.ts 的argTypes与 pagination.ts 中的property声明交叉验证。以下为核心属性一览括号内为默认值属性类型说明pagenumber1当前页反映到 DOM 属性page-sizenumber10每页条目数反映到 DOM 属性startnumber0当前页起始行号从 0 开始索引total-itemsnumber未定义总条目数传空字符串/不传则视为总数未知pages-unknownbooleanfalse是否为总页数未知模式反映到 DOM 属性disabledbooleanfalse禁用整组分页 UI反映到 DOM 属性page-input-disabledbooleanfalse仅禁用页码下拉框page-size-input-disabledbooleanfalse仅禁用分页大小下拉框sizexs \| sm \| md \| lgmd组件尺寸反映到 DOM 属性backward-textstringPrevious page后退按钮提示文本forward-textstringNext page前进按钮提示文本backward-text-tooltip-positiontop \| right \| bottom \| lefttop后退按钮 tooltip 方位forward-text-tooltip-position同上top前进按钮 tooltip 方位items-per-page-textstring每页条数标签的定制文本is-last-pageboolean显式声明当前为最后一页formatStatusWithDeterminateTotal/formatStatusWithIndeterminateTotal/formatLabelText/formatSupplementalTextfunction状态文本格式化函数用于国际化尺寸与 tooltip 方位的合法取值定义于 defs.ts 中的PAGINATION_SIZE与PAGINATION_TOOLTIP_POSITION两个枚举。组件向外派发两个自定义事件均带bubbles: true, composed: true事件名定义于 pagination.tscds-pagination-changed-current当前页起始行变化时触发detail含{ page, pageSize }。cds-page-sizes-select-changed每页条数变化时触发detail含{ page, pageSize }。测试用例验证了每次操作只触发一次事件的约定pagination-test.js并覆盖了事件detail.pageSize的正确性pagination-test.js。状态文本的三种形态与边界处理_renderStatusText()pagination.ts集中体现了组件对总数确定/不确定/为零三种场景的处理总数确定totalItems为有限数字输出start 1–min(start pageSize, totalItems) of totalItems items如快照中的11–30 of 200 items。总数不确定totalItems为undefined/null即pagesUnknown或totalItems null若totalItems 0输出0–0 of 0 items否则输出闭合区间${start 1}–${start pageSize} items如快照中的Item 1–10。最后一页且总数不确定end为空时输出Item ${start}–开区间形式。这些边界行为都有对应的测试用例Rendering status text测试块验证了单数/复数1–1 of 1 item、无总条数时的Item 11–30、以及最后一页的Item 31–pagination_spec.ts。此外start的计算由_calculateStart()pagination.ts完成(Math.max(1, page) - 1) * pageSize并在总数确定时钳制到最后一页的最大合法起始行避免越界pageSize为 0 时按 1 处理以防止除零。测试验证了页数超出范围时自动钳制pagination-test.js与totalItems为 0 时禁用前进按钮pagination-test.js等行为。一个完整的最小使用示例结合 Storybook 默认示例pagination.stories.ts一个可运行的最小示例为cds-pagination total-items103 page-size10 page1 items-per-page-textItems per page: backward-textPrevious forward-textNext sizemd cds-page-sizes-select-changed(event) console.log(event.detail) cds-pagination-changed-current(event) console.log(event.detail) cds-select-item value1010/cds-select-item cds-select-item value2020/cds-select-item cds-select-item value3030/cds-select-item cds-select-item value4040/cds-select-item cds-select-item value5050/cds-select-item /cds-pagination若数据源未知总条数如无限滚动只需设置pages-unknown且不传total-items组件便会渲染未知页数模式对应 Storybook 的PaginationUnknownPages故事pagination.stories.ts。将cds-select-item的显示文案改为 Ten/Twenty/Thirty 等即可实现自定义分页大小标签对应PaginationWithCustomPageSizesLabel故事pagination.stories.ts。组件通过 index.ts 统一导出并依赖cds-select与cds-select-item。小结快照文件 cds-pagination.md 虽然只是测试渲染结果的留影但它精确记录了cds-pagination在最小属性、组合属性、分页大小选择器、页码选择器四种场景下的 Shadow DOM 结构是理解该组件布局契约的第一手资料。结合 pagination.ts 的属性声明、状态计算与事件派发逻辑以及 pagination_spec.ts、pagination-test.js 的测试覆盖可以完整掌握从快照里的 HTML到真实可用的分页组件之间的全部实现细节。无论是要集成该组件还是要为其编写自定义格式化函数或无障碍文案都可以从本文梳理的结构与契约入手。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入解析 Carbon Web Components 的 `cds-pagination`：快照渲染结构与组件实现原理
深入解析 Carbon Web Components 的cds-pagination快照渲染结构与组件实现原理【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncds-pagination是 IBM Carbon 设计系统 Web Componentscarbon/web-components中的分页组件它由分页大小选择器cds-page-sizes-select、页码选择器cds-pages-select、状态文本与前后翻页按钮共同组成。本文以仓库中的渲染快照文档 cds-pagination.md 为骨架结合组件源码 pagination.ts、pagination.stories.ts 与测试用例 pagination_spec.ts逐层拆解其 Shadow DOM 输出结构、属性/事件契约与内部状态计算逻辑帮助读者掌握该组件的渲染机制与实际用法。组件总览cds-pagination的内部布局cds-pagination基于 LitElement 实现类定义于 pagination.tscustomElement(${prefix}-pagination) class CDSPagination extends FocusMixin(HostListenerMixin(LitElement)) {从快照渲染结果看其 Shadow DOM 被划分为两个主要区域左侧区域cds--pagination__left包含分页大小下拉框slot namepage-sizes-select、分隔线cds-ce--pagination__divider以及条目统计文本cds--pagination__items-count。右侧区域cds--pagination__right包含默认插槽slot用于放置页码下拉框cds-pages-select、分隔线以及由两个图标按钮构成的控制区cds--pagination__control-buttons。这个布局在render()方法pagination.ts中被实际输出而快照文件正是render()产物的忠实记录。组件样式定义在 pagination.scss 中通过extend .#{$prefix}--pagination继承 Carbon 样式库carbon/styles的分页基础样式并额外声明了cds-ce--pagination__divider分隔线1px、$layer-accent-01背景色等 Web Components 特有的样式。快照一最小属性下的cds-pagination渲染结构当仅以最简方式不显式传属性渲染cds-pagination时快照记录了如下 Shadow DOM 输出div classcds--pagination__left slot namepage-sizes-select /slot div classcds-ce--pagination__divider /div span classcds--pagination__items-count cds--pagination__text Item 1–10 /span /div div classcds-ce--pagination__divider /div div classcds--pagination__right slot /slot div classcds--pagination__control-buttons button classcds--pagination__button cds--pagination__button--backward cds--pagination__button--no-index disabled titlePrevious page /button button classcds--pagination__button cds--pagination__button--forward titleNext page /button /div /div这段输出对应默认属性值page 1、pageSize 10、start 0、totalItems undefined、pagesUnknown false各属性默认值见 pagination.ts。几个值得注意的细节状态文本 Item 1–10来自_renderStatusText()pagination.ts。由于未提供totalItems组件走的是总数不确定分支调用formatStatusWithIndeterminateTotal输出开区间格式${start}–${end} itemsstart为 0 时显示为 1 起始min totalItems 0 ? 0 : start 1。后退按钮被禁用disabled且带cds--pagination__button--no-index类原因是prevButtonDisabled disabled || start 0pagination.ts首页时start 0恒成立。其titlePrevious page来自backwardText默认值pagination.ts。前进按钮未禁用nextButtonDisabled disabled || (!pagesUnknown isLastPage)pagination.ts当总页数未知时始终可用。对应的测试用例是should render cds-pagination with minimum attributespagination_spec.ts它通过toMatchSnapshot({ mode: shadow })以 Shadow DOM 模式匹配快照。快照二多种属性组合下的渲染结构当传入pageSize: 20, start: 10, totalItems: 200时对应测试should render cds-pagination with various attributes见 pagination_spec.ts快照输出为div classcds--pagination__left slot namepage-sizes-select /slot div classcds-ce--pagination__divider /div span classcds--pagination__items-count cds--pagination__text 11–30 of 200 items /span /div div classcds-ce--pagination__divider /div div classcds--pagination__right slot /slot div classcds--pagination__control-buttons button classcds--pagination__button cds--pagination__button--backward titlePrevious page /button button classcds--pagination__button cds--pagination__button--forward titleNext page /button /div /div与最小属性快照的关键差异状态文本变为 11–30 of 200 items此时totalItems是确定值200走formatStatusWithDeterminateTotal分支pagination.ts格式为${start 1}–${Math.min(start pageSize, totalItems)} of ${totalItems} items即11–30 of 200 items。后退按钮不再禁用start 10 0prevButtonDisabled为false因此移除了cds--pagination__button--no-index类和disabled属性。这一对比直观展示了start、pageSize、totalItems三个核心属性如何共同决定状态文本与按钮可用性。快照三cds-page-sizes-select的结构虽然文档中以cds-page-sizes-select命名但在当前版本中每页条数选择框实际由组件内部渲染的cds-select承担带idpage-size-select、pagination、inline等属性见 pagination.ts。快照记录了其内部结构label classcds--pagination__text forselect slot namelabel-text Items per page: /slot /label div classcds--select__item-count select classcds--select-input idselect option value10 10 /option option value20 20 /option option value30 30 /option /select /div div hidden slot /slot /div要点解析标签插槽slot namelabel-text的兜底内容为Items per page:。当使用方在cds-pagination内部通过cds-select-item声明分页大小选项时这些选项通过_handleSlotChangepagination.ts被搬移到内部cds-select的默认插槽中。而items-per-page-text属性会以cds--pagination__text文本的形式注入label-text插槽内容之前pagination.ts。选项即快照中的 10/20/30分页大小选项由使用方通过cds-select-item value1010/cds-select-item提供快照展示的正是 Storybook 默认示例中前三个选项完整示例为 10/20/30/40/50见 pagination.stories.ts。隐藏的默认插槽div hiddenslot/slot/div用于接收被搬移的选项是cds-select内部接收外部内容的标准做法。对应的快照测试是should render cds-page-sizes-select with minimum attributespagination_spec.ts测试注释特别说明需要两次await Promise.resolve()来等待cds-pagination与cds-page-sizes-select两级组件的更新周期完成。快照四cds-pages-select的结构当提供确定的总条数测试中totalItems: 100时页码下拉框会渲染为带无障碍标签的cds-select内部带idpages-select见 pagination.ts。快照输出div classcds--select__page-number label classcds--label cds--visually-hidden forselect Page number, of 10 pages /label select classcds--select-input option selected value0 1 /option option value1 2 /option ... option value9 10 /option /select /div span classcds--pagination__text of 10 pages /span要点解析页数计算totalPages Math.ceil(totalItems / pageSize)100 / 10 10页因此生成 10 个option选项值从 1 到 10对应的value属性是09索引从 0 开始代表行号起点。无障碍设计标签使用cds--visually-hidden类实现视觉隐藏、屏幕阅读器可读文本内容由formatLabelText生成默认值为Page of ${count} page${count 1 ? : s}pagination.ts。补充文本右侧的of 10 pages由formatSupplementalText生成默认逻辑为pagesUnknown或!totalItems时输出page否则输出of ${count} pagespagination.ts。页面裁剪当totalItems: 100时pages-unknown分支不渲染pagesUnknown || !totalItems为假因此渲染页码下拉框而非未知页数纯文本pagination.ts。对应测试为should render cds-pages-select with minimum attributespagination_spec.ts。核心属性与事件契约快照之外组件的完整 API 可以通过 pagination.stories.ts 的argTypes与 pagination.ts 中的property声明交叉验证。以下为核心属性一览括号内为默认值属性类型说明pagenumber1当前页反映到 DOM 属性page-sizenumber10每页条目数反映到 DOM 属性startnumber0当前页起始行号从 0 开始索引total-itemsnumber未定义总条目数传空字符串/不传则视为总数未知pages-unknownbooleanfalse是否为总页数未知模式反映到 DOM 属性disabledbooleanfalse禁用整组分页 UI反映到 DOM 属性page-input-disabledbooleanfalse仅禁用页码下拉框page-size-input-disabledbooleanfalse仅禁用分页大小下拉框sizexs \| sm \| md \| lgmd组件尺寸反映到 DOM 属性backward-textstringPrevious page后退按钮提示文本forward-textstringNext page前进按钮提示文本backward-text-tooltip-positiontop \| right \| bottom \| lefttop后退按钮 tooltip 方位forward-text-tooltip-position同上top前进按钮 tooltip 方位items-per-page-textstring每页条数标签的定制文本is-last-pageboolean显式声明当前为最后一页formatStatusWithDeterminateTotal/formatStatusWithIndeterminateTotal/formatLabelText/formatSupplementalTextfunction状态文本格式化函数用于国际化尺寸与 tooltip 方位的合法取值定义于 defs.ts 中的PAGINATION_SIZE与PAGINATION_TOOLTIP_POSITION两个枚举。组件向外派发两个自定义事件均带bubbles: true, composed: true事件名定义于 pagination.tscds-pagination-changed-current当前页起始行变化时触发detail含{ page, pageSize }。cds-page-sizes-select-changed每页条数变化时触发detail含{ page, pageSize }。测试用例验证了每次操作只触发一次事件的约定pagination-test.js并覆盖了事件detail.pageSize的正确性pagination-test.js。状态文本的三种形态与边界处理_renderStatusText()pagination.ts集中体现了组件对总数确定/不确定/为零三种场景的处理总数确定totalItems为有限数字输出start 1–min(start pageSize, totalItems) of totalItems items如快照中的11–30 of 200 items。总数不确定totalItems为undefined/null即pagesUnknown或totalItems null若totalItems 0输出0–0 of 0 items否则输出闭合区间${start 1}–${start pageSize} items如快照中的Item 1–10。最后一页且总数不确定end为空时输出Item ${start}–开区间形式。这些边界行为都有对应的测试用例Rendering status text测试块验证了单数/复数1–1 of 1 item、无总条数时的Item 11–30、以及最后一页的Item 31–pagination_spec.ts。此外start的计算由_calculateStart()pagination.ts完成(Math.max(1, page) - 1) * pageSize并在总数确定时钳制到最后一页的最大合法起始行避免越界pageSize为 0 时按 1 处理以防止除零。测试验证了页数超出范围时自动钳制pagination-test.js与totalItems为 0 时禁用前进按钮pagination-test.js等行为。一个完整的最小使用示例结合 Storybook 默认示例pagination.stories.ts一个可运行的最小示例为cds-pagination total-items103 page-size10 page1 items-per-page-textItems per page: backward-textPrevious forward-textNext sizemd cds-page-sizes-select-changed(event) console.log(event.detail) cds-pagination-changed-current(event) console.log(event.detail) cds-select-item value1010/cds-select-item cds-select-item value2020/cds-select-item cds-select-item value3030/cds-select-item cds-select-item value4040/cds-select-item cds-select-item value5050/cds-select-item /cds-pagination若数据源未知总条数如无限滚动只需设置pages-unknown且不传total-items组件便会渲染未知页数模式对应 Storybook 的PaginationUnknownPages故事pagination.stories.ts。将cds-select-item的显示文案改为 Ten/Twenty/Thirty 等即可实现自定义分页大小标签对应PaginationWithCustomPageSizesLabel故事pagination.stories.ts。组件通过 index.ts 统一导出并依赖cds-select与cds-select-item。小结快照文件 cds-pagination.md 虽然只是测试渲染结果的留影但它精确记录了cds-pagination在最小属性、组合属性、分页大小选择器、页码选择器四种场景下的 Shadow DOM 结构是理解该组件布局契约的第一手资料。结合 pagination.ts 的属性声明、状态计算与事件派发逻辑以及 pagination_spec.ts、pagination-test.js 的测试覆盖可以完整掌握从快照里的 HTML到真实可用的分页组件之间的全部实现细节。无论是要集成该组件还是要为其编写自定义格式化函数或无障碍文案都可以从本文梳理的结构与契约入手。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考