更新记录

2.4.0（2026-11-12） 下载此版本

• o-card-footer 新增 bg 背景属性：留空继承卡片背景（不改变现有视觉），纯色用 background-color、渐变 / 图片用 background 简写；判断只用一个正则，无浏览器 API，内联 style 下发，Vue2 / Vue3 与各端小程序通用。卡片根节点已有 overflow:hidden + border-radius，底部两角会自动裁成圆角
• 演示页新增「footer 背景」区块（浅灰纯色 / 主题浅色 + :border="false" / 渐变三种）与 codes.footerBg；readme 补参数、示例与平台说明

平台兼容性

uni-app(3.8.10)

o-card

卡片组件，一套七个组件组合使用：

<o-card size="md">
    <o-card-header>
        <o-card-title>标题</o-card-title>
        <o-card-desc>描述</o-card-desc>
        <o-card-action text="查看更多" @click="onMore" />
    </o-card-header>
    <o-card-content>内容区，放任意内容</o-card-content>
    <o-card-footer>底部，默认带细分隔线</o-card-footer>
</o-card>

• header 内部为 flex 布局：title 与 action 同行，title 自动撑满剩余宽度、action 按内容长短伸缩（文案上限 16 字节 = 8 个中文，超出自动截断），desc 自动换到下一行；align="center" 可切换为「左返回 + 标题居中 + 右操作」的导航栏式排版
• size 是唯一的间距来源：四档映射成一个 rpx 数值，没有派生公式、没有覆盖优先级链
• 卡片的 gap: S 只作用于三个区块之间：header / content / footer 都不继承卡片的 gap 值。o-card-header 自带固定 gap: 8rpx（与 size 无关）：既给同行的 title / action 提供列间距，也给 desc 换行后提供行间距；content / footer 不设 gap，内部间距由内容自行控制
• 底部留白自动判断：插槽里有 o-card-footer 时，卡片只有 padding-top:S + gap:S（底部由 footer 的四边 padding 提供）；没有 footer 时，卡片额外补 padding-bottom:S
• footer 可单独设背景：bg 留空继承卡片背景，传纯色 / 渐变即可做底部高亮条；卡片根节点 overflow:hidden + border-radius 会自动把背景裁成圆角
• 子组件必须置于 o-card 内使用，不再提供脱离卡片的独立兜底
• title / desc / action 字号固定，不随 size 变化；需要时用各自的 size 覆盖
• 兼容 Vue2 / Vue3；小程序端带 virtualHost + styleIsolation: apply-shared

尺寸体系

S 作用于以下位置：

结构示意（区块自身都不设 gap）：

有 footer：card = padding-top:S + gap:S
┌─ o-card ─────────────────────────────────────┐
│  ↑ S   padding-top                            │
│  o-card-header   pl/pr: S                     │
│  ↑ S   card gap                               │
│  o-card-content  pl/pr: S                     │
│  ↑ S   card gap                               │
│  o-card-footer   padding: S  ← 提供底部留白    │
│  ↓ S   footer padding-bottom                  │
└───────────────────────────────────────────────┘

无 footer：card = padding-top:S + gap:S + padding-bottom:S
┌─ o-card ─────────────────────────────────────┐
│  ↑ S   padding-top                            │
│  o-card-header   pl/pr: S                     │
│  ↑ S   card gap                               │
│  o-card-content  pl/pr: S                     │
│  ↓ S   card padding-bottom  ← 补上底部留白     │
└───────────────────────────────────────────────┘

动态值全部以内联 style 下发，不使用 CSS 变量（var() 在部分小程序端会被整条丢弃）。 footer 的 padding-top 与卡片 gap 会自然叠加，这是四边 padding 的预期结果。

header 内部布局

o-card-header 是 flex + wrap，自带固定 gap: 8rpx（列间距与行间距都是 8rpx，与 size 无关、不取自 o-card 的 S）：

┌─ o-card-header  pl/pr: S / gap: 8rpx ────────────────┐
│  ┌─ o-card-title ────────────────┐  ┌─ o-card-action┐ │
│  │ flex: 1 1 0%  自动撑满剩余宽度 │  │ flex: none     │ │
│  │ min-width: 0  长标题可省略     │  │ 宽度 = 内容宽度 │ │
│  └──────────────────────────────┘  └───────────────┘ │
│                              ↑ 8rpx column-gap        │
│                              ↑ 8rpx row-gap           │
│  o-card-desc   flex: 0 0 100% 整行换到下一行          │
└───────────────────────────────────────────────────────┘

• o-card-title（常规 header 内）flex: 1 1 0% + min-width: 0：占满 action 之外的全部宽度，长标题配合 lines 正常省略而不会把 action 挤到下一行
• o-card-action flex: none + white-space: nowrap：宽度完全跟随文案／插槽内容长短，不拉伸、不压缩、不折行；margin-left:auto 只在「header 里没有 title」时把它推到右侧
• o-card-desc flex: 0 0 100% 独占一行，行间距由 header 的 row-gap 提供（组件自身不再加 margin-top，避免叠加成 16rpx）
• align="center" 时 title 改为绝对定位居中，不参与 flex 伸缩；此时 back 在左、action 在右

action 文案长度上限

为避免长文案把 title 挤到换行，o-card-action 的 text 默认最多 16 字节，按双字节权重计算：中文 / 全角算 2、半角（字母、数字、符号）算 1。因此：

即「不超过 16 字节」等价于「不超过 8 个中文」。超出时按权重裁到 上限 - 2 再追加 …（省略号按 2 权重预留），保证显示文案仍在上限内；用 max-bytes 可调整上限，设为 0 关闭限制。计算用纯 JS charCodeAt，不依赖 TextEncoder / Array.from，Vue2 / Vue3 与各端小程序一致。

该限制作用于 text 属性。使用默认插槽自定义内容时，跨端 VNode 结构不一致、无法可靠读取文字，请业务自行把内容控制在 8 个中文内。

字号与尺寸解耦：o-card-title 默认 30rpx、o-card-desc 默认 26rpx、o-card-action 默认 26rpx，四档 size 下保持一致。

o-card 属性

根节点会附加 o-card--sm|md|lg|xl 类名，便于外部按档位定制样式。

子组件

o-card-header

头部容器，flex + wrap，padding-left/right = S，自身带固定 gap: 8rpx（不随 size 变化，也不继承卡片的 gap: S）；title 撑满、action 按内容伸缩、desc 换行，详见「header 内部布局」。

导航栏式排版示例（对应演示页「参考排版」）：

<o-card size="md" border :radius="16">
    <o-card-header align="center" back border @back="onBack">
        <o-card-title size="32">周易六十四卦</o-card-title>
        <o-card-action text="更多" @click="onMore" />
    </o-card-header>
    <o-card-content><!-- 8 列网格等内容 --></o-card-content>
</o-card>

center 模式下 o-card-title 由子组件自己绝对定位居中（左右撑满 + text-align:center），o-card-action 自动抬到标题之上保证可点击——样式写在各自组件内，不依赖跨组件后代选择器，小程序端同样生效。

o-card-title

o-card-desc

lines 采用 max-height + line-clamp 实现，内容不足时不留空白。

o-card-action

头部右侧操作区，宽度按内容长短伸缩（flex: none + nowrap），不拉伸不折行；同行 title 自动撑满剩余宽度。

也可以放自定义内容：<o-card-action><o-btn size="sm">按钮</o-btn></o-card-action>

o-card-content

内容区，flex column，padding-left/right = S，自身不设 gap（多个子元素之间的间距由内容自己写 margin / 行高）。无自有属性。

o-card-footer

底部区，flex column，padding = S（四边），自身不设 gap。

bg 示例：

<!-- 纯色高亮条，保留默认顶部分隔线 -->
<o-card-footer bg="#f7f8fa">底部操作区</o-card-footer>

<!-- 主题浅色 + 关闭分隔线 -->
<o-card-footer bg="#fff1f0" :border="false">底部操作区</o-card-footer>

<!-- 渐变背景；卡片圆角自动裁切 -->
<o-card-footer bg="linear-gradient(90deg, #eef4ff, #f5eeff)" :border="false">底部操作区</o-card-footer>

bg 通过内联 style 下发，不写死在 wxss；空值不生成任何背景声明，现有卡片视觉不变。卡片根节点带 overflow:hidden 与 border-radius，因此 footer 背景在底部两角会被正确裁成圆角，无需额外写圆角样式。

footer 通过 inject 向 o-card 注册自身（created 注册，beforeDestroy / beforeUnmount 注销）：卡片据此判断插槽内有没有 footer，决定是否追加 padding-bottom: S。注册用响应式计数 + 子组件自身的成对标记实现，不依赖 VNode / $parent，Vue2 / Vue3 与各端小程序通用；footer 用 v-if 动态增删时样式会同步更新。

平台说明

• 各子组件均带 virtualHost（微信）+ styleIsolation: apply-shared，无多余包裹节点，页面工具类可直接作用进组件
• o-card 根节点用 CSS flex gap: S（控制三个区块之间），o-card-header 另用固定 gap: 8rpx（控制同行元素与 desc 换行）：H5 与各家小程序当前主流 webview 均支持；nvue（Weex）不支持 gap，该端区块间距与 header 内部间距会退化为 0，App 端建议使用 app-vue
• o-card-content / o-card-footer 内部不使用 gap，旧内核 webview 与 nvue 下其内部布局不受影响
• action 文案长度上限用 charCodeAt 逐码元计权，不使用 TextEncoder / Array.from 等运行时 API，Vue2 / Vue3 与各端小程序一致
• footer 的 bg 用内联 style 下发：纯色用 background-color、渐变 / 图片用 background 简写，判断只用正则，无浏览器 API；小程序端同样生效
• footer 探测走 provide/inject 注册计数，父组件 data 里只存数字，不做 VNode 遍历、不序列化组件实例，小程序 setData 安全
• lines 行数截断依赖 -webkit-line-clamp（webview 内核均支持）；nvue 端不支持 box 布局截断，超出会直接溢出隐藏

从 1.x 升级（2.0.0 为破坏性变更）