一、目标长什么样

AI 助手回复“打车”意图时会下发一张“确认行程”卡片：

• 渐变蓝色抬头
• 中段一条横向虚线撕线
• 撕线左右各有一个半圆缺口
• 下方白这方面。地图、价格区间、选择车型、确认用车按钮
• 整张卡有阴影，缺口处的阴影要“凹”进去，让票根有物理感

关键视觉特征只有一个——左右两个真挖出去的半圆缺口。按理说，

二、第一版：用 Circle 覆盖底色“挖洞”

最直觉的做法是把撕线那一行做成 Stack中间放虚线。左右各放一个填外层底色的 Circle形成视觉上的“缺口”。

Stack {
// 中间水平虚线
Line
.height
.startPoint
.endPoint
.stroke
.strokeWidth
.strokeDashArray
.width
.margin
// 左右两个跟底色一致的“假缺口”
Row {
Circle
.fill
.offset
Blank
Circle
.fill
.offset
}
.width
}
.width
.height

痛点 #1：颜色不匹配导致假缺口露出浅灰色块。怎么说呢， 卡片被塞进 AI 聊天气泡里气泡背景是浅蓝渐变。与 #F5F6FA 不一致，缺口处直接露出浅灰色块，看起来像是“贴上去的”。

痛点 #2：阴影仍然是矩形轮廓，没有沿缺口走。 外层 .shadow 加在最外面的 Column 上。阴影边界仍是矩形圆角，缺口边缘没有阴影包络，视觉上没有凹感。

根本原因：这两个 Circle 并没有真的把形状挖掉，只是用同块盖住而已。一旦底色变化、父容器出现渐变或需要截图分享时就会立刻穿帮。

三、第二版尝试：Path 组件 + 双层 Stack 补阴影

既然要“真挖洞”。自然想到使用 SVG 方法描述一个带缺口的形状，接下来把卡片裁剪成该形状。

方法示例：

M …H ，A …V ，A …A ，V …A ，H …A ，V …A ，A …V ，A …Z

尝试直接把 Path.clipShape)，IDE 报错——clipShape) 不接受绘制组件 Path)。

痛点 #3：API 用错导致编译错误。

于是采用“双层 Stack”：底层 Path 加阴影，上层 Column 用相同形状裁剪内容。至于代码结构如下，

• 阴影 = 底层 Path 投影
• 内容 = 上层 Column 真裁剪

结果：

1. ) 在新版本 ArkUI 已不推荐。用 PathShape) 替代。其实，
缺口处仍然没有阴影。

* 痛点 #4：双层结构易失效且维护成本高 *

四、对照团队成熟做法——找到真相

真相 1：clipShape 入参用 PathShape，不是 Path

ath

html

Project Name : MyApplication Component Name : ConfirmTripCardComp Description : The goal is to implement a ticket style card that contains a gradient blue header。dashed line separator in middle and two semi-circular notches on both sides of

separator.

This documentation explains how you would approach building this component and what you have tried in order to create an actual

一、目标原型展示

• A) 渐变蓝色标题区。
• B) 中段横向虚线分割。
• C) 虚线上两侧各有一个半圆凹槽——**真正挖出的孔**。
• D) 下方白底区域展示地图、价格区间、车型选择及确认按钮。
• E) 整体投影需在凹槽处产生 **向内凹陷的光晕**，提高真实感。

┌──────────────────────────────────────────┐
│ 确认行程 │
│ ─── │
│ │
│ ⊙ 香港中国公司协会 立即出发 │
│ ⋮ 全程 公里 分钟 │
│ ⊙ 香港国际机场 预计 : 到达 │
└──┘ ← 撕线 + 两侧凹槽 │
│ │
│ ┌────────────────────────────────┐ │
│ │ │ │
│ └────────────────────────────────┘ │
│ 预估 ~ 人民币起 │
│ 已选中 种车型： │
│ │
│ ┌────── 确认用车 ──────┐ │
└──────────────────────────────────────────┘

⚡ 痛点 #1 – 背景颜色不匹配导致假孔显露灰色块 当卡片嵌入 AI 聊天气泡时其背景为浅蓝渐变；若使用固定颜色 ) 的 Circle 来遮挡。则会出现明显颜色不一致的灰块，看起来像是「贴上去」的假孔。

Stack {
// 中间水平虚线
Line
.height
.startPoint
.endPoint
.stroke
.strokeWidth
.strokeDashArray
.width
.margin
// 左右两个与背景同色的 “假孔”
Row {
Circle
.fill // <-- 固定颜色 → 与父容器不匹配  
            .offset
        Blank
        Circle
            .fill
            .offset
    }.width
}.width.height

⚡ 痛点 #2 – 阴影仍保持矩形轮廓 将 `.shadow` 加在最外层 `Column` 上后投射出的阴影始终是矩形/圆角矩形。而不是沿着凹槽轮廓展开，从而失去 “凹陷感”。此时原因在于 **Circle 并未真的把区域挖掉**。它们只是用同块覆盖而已，一旦背景或父容器改变，就会立刻穿帮。

三、第二版尝试 – 使用 Path 绘制真实凹槽 & 双层 Stack 补阴影

⚡ 痛点 #3 – API 使用错误导致编译报错 直接将 ``Path`组件当作 `.clipShape` 参数会报错，因为 `clipShape` 接受的是 **Shape 对象** 而非视图节点 `Path`。此错误常见于文档分散且命名相近的情况下。按理说，

• Path → 绘制组件。仅用于渲染 SVG 方法；加入视图树后不会参与几何裁剪计算。
• PathShape → Shape 对象。用作 clipShape / mask 等属性的入参，可参与几何运算。<\/ul>

M x y // 起点
H w-r // 顶部直线至右侧圆角前
A r r 0 0 1 w r // 顶部右圆角
V ny-nr // 垂直至左侧凹槽上缘
A nr nr 0 0 1 w ny+nr // 凹槽右侧弧线
V h-r // 垂直至右下圆角前
A r r 0 0 1 w-r h // 底部右圆角
H r // 底部直线至左下圆角前
A r r 0 0 1 r h // 底部左圆角
V ny+nr // 垂直回到左侧凹槽下缘
A nr nr 0 0 1 r ny-nr // 凹槽左侧弧线
Z // 闭合方法
<\/codeline>

⚡ 痛点 #4 – 双层 Stack 难以同步宽高 & 阴影位置 即便使用双层结构。也会遇到以下问题：

1. new Path 已被废弃，需要改用 new PathShape；若强行使用仍可运行，但底层 Path 的投射阴影只能覆盖矩形外缘，不会贴合凹槽。
2. Stack 必须保持完全相同尺寸，否则两层错位导致视觉漂移。<\/ol>

四、主要真相 —— 正确使用 

真相 ① ClipShape 入参应为 \*

<\/tbody> <\/table>

类名	作用	使用场景
Path<\/ code>	绘制组件。仅用于渲染 SVG 方法<\/ td>	放置于视图树内部绘制各种形状<\/ td>
PathShape<\/ code>	几何 Shape 对象，可作为 clip/mask 参数<\/ td>	需要进行几何裁剪或遮罩时使用<\/ td>

⚡ 痛点 #5 – 开发者容易混淆这两者名称，引发 API 调用错误，从而浪费调试时间。不过，<\/div>

import { PathShape } from '@kit.ArkUI';Column
/* 内容 */
/*①先裁剪 */
.clipShape }))
/*②再加投射 */
.shadow({
radius :12。color:'#33000000',offsetX :0,offsetY :4,});其实，<\/codeline>

真相 ② Shadow 自动沿 Clip 后轮廓外发光 \*

⚡ 痛点 #6 – 错误地认为 Clip 会把 Shadow 一并裁掉。需要“双层结构”，说起来，这种思维源自 Web/RN/SwiftUI 的经验。但在 ArkUI 中恰恰相反——Shadow 是在合成阶段根据最终几何轮廓生成 Outer Shadow，所以只需单层就可以 “沿凹陷外发光”。其实，

• .clipShape 必须先于 .shadow 调用。否则 Shadow 将基于未裁剪前的矩形轮廓计算。<\/ul>

真相 ③ 单位差异——Path 命令采用 px。而布局属性采用 vp \*

⚡ 痛点 #7 – 开发者常忽略单位转换，在不同 DPI 的设备上出现孔位偏移或尺寸失真。<\/div>

• onAreaChange 回调返回宽高单位为 vp。说起来，<\/ul>

• Path commands 字符串里的数值单位为 px。<\/ul>

所有进入方法计算的数据都必须经过 vp2px 转换。说到例如，

const cornerPx = vp2px;
// 圆角16vp → px
const notchPx = vp2px;// 缺口9vp → px
\/\/ …，后续所有 path 参数均使用上述 px 值
\<\/codeline>

真相 ④ 零体积撕线 — 使用 top dashed border \*

⚡ 痛点 #8 – 手动计算 margin 为撕线留空十分繁琐且易出错；更优雅方式是让撕线节点本身拥有高度为零，仅靠 top dashed 边框渲染即可自动适配 Clip 区域。<\/div>

Row
.width
.height // 零体积节点
.border({
width这方面。{ top :1 },// top dashed line 为唯一可见部分
color这方面，'#33000000',style:borderStyle.Dashed,});\<\/codeline>

五、完整防御性写法 —— 首帧尺寸 & 极端高度兜底 \*

首帧尺寸未知导致卡片瞬间消失 \*

⚡ 痛点 #9 – 第一次渲染时 onAreaChange 尚未返回有效宽高。如果直接使用这些未初始化值生成方法，会得到极小甚至为零的 shape，使得整张卡片在首帧不可见，只能等下一帧才出现闪烁感。<\/div>

至于解决办法，在首帧检测到宽高 <=0 时返回一个超大矩形，以等价“不裁剪”。

if{ return 'M0 L2000 L2000 L0 Z';}
\<\/codeline>

卡片高度不足导致方法自交 \*

⚡ 痛点 #10 – 当高度小于 圆角+缺口 半径之和 时上下垂直段长度可能为负数，引起 path 自交并产生渲染异常。<\/div>

至于防御策略。若检测到无法容纳完整凹槽，则退化为普通无孔圓角矩形。

const minNy = cornerPx + notchPx;const maxNy = h - cornerPx - notchPx;if{ return this.getPlainRectPath;} // 无孔版本
let ny = this.notchY;说起来，if ny = minNy;if ny = maxNy;\<\/codeline>

六、动态计算缺口位置 —— 与抬头高度联动 \*

⚡ 痛点 #11 – 若硬编码了 notchY。则当抬头文字增删或字号变化时会导致欠槽位置漂移，破坏整体对齐感。<\/div>

做法是在抬头区域一样监听 onAreaChange 获取实际高度。将其转化为 px 并作为 notchY 输入给方法生成函数，实现 “贴着抬头底边走”。

@Local headerHeightVp:number=40;话说回来，// vp 单位。高度随内容变化自动更新
@Local notchYPx:number=vp2px;TicketHeader
/*…*/
//.onAreaChange 捕获实际高度并同步字段
.onAreaChange=>{
this.headerHeightVp=Number;this.notchYPx=vp2px);})，\<\/codeline>

七、完整实现代码示例 \*

字段 & 常量声明

import { PathShape } from '@kit.ArkUI';@ComponentV2 export struct ConfirmTripCardComp {
@Param @Require card : TripCard;@Local cardWidthPx:number=0;话说回来，// 实际 px 宽度。由 onAreaChange 更新
@Local cardHeightPx:number=0;// 实际 px 高度，由 onAreaChange 更新
@Local notchYPx:number=80;// 缺口中心 y，单位 px；默认值占位
@Local headerHeightVp:number=40;// 抬头实际高度，随文字动态变化
private readonly cornerRadiusVp:number=16;不过，private readonly notchRadiusVp:number=9;}
\<\/codeline>

方法生成函数

getCardPath:string{
const w=this.cardWidthPx;const h=this.cardHeightPx;if{return 'M0 L20000 L20000 L0 Z';} // 首帧兜底
const r=vp2px;// 圆角 px
const nr=vp2px;// 缺孔半径 px
// 防止高度不足无法容纳完整凹槽
const minNy=r+nr;其实，const maxNy=h-r-nr;if{
// 返回普通四周带圆角的矩形 path
return `M ${r} H ${w-r} A ${r} ${r} ${w} ${r} V ${h-r} A ${r} ${r} ${w-r} ${h} H ${r} A ${r} ${r} ${r} ${h-r} V ${r} Z`;}
// 钳制 notch Y 在合法区间内
let ny=this.notchYPx;ifny=minNy，怎么说呢，ifny=maxNy;// 完整带两侧内凹半圆穴道的 path 字符串
return `M ${r}`+ // 起始左上弧入口
` H ${w-r}`+ // 顶部直线至右上弧前
` A ${r} ${r} ${} ${} `+ // 顶部右圆弧
` V ${}`+ // 向下至右穴入口
` A ${nr} ${nr} ${} ${} `+ // Right 内凹半円
` V ${}`+ // 向下至右下圓弧開始
` A ${r} ${r} ${} ${} `+ // Right bottom 圆弧
` H ${r}`+
` A ${r} ${r} ${} ${} `+
` V ${}`+
` A ${nr} ${nr} ${} ${} `
` V ${}`
` A ${r} ${r} ${} ${} Z`;}
\<\/codeline>

外层结构与关键属性链路

build{
Stack{
Column{
/* ★ 抬头区 ★ */
this.TicketHeader;/* ★ 撕線 ★ — 零體積節點 */
Row
.width
.height
.border({
width这方面。{top :1},color:'#33000000',style:borderStyle.Dashed,});/* ★ 主体白區 ★ — 地圖／價格／按鈕 */
Column{ /* 此處省略具體子組件 */ }
}
/* ---- 主要三步 ---- */
//.① 裁切實際幾何輪廓
.clipShape}))
//.② 緊接著添加陰影 → 自動沿剖面外發光
.shadow({
radius :12。color :'#33000000',offsetX :0,offsetY :4,})
//.③ 捕獲實際渲染尺寸，以觸發路徑重算
.onAreaChange=>{
this.cardWidthPx = vp2px);this.cardHeightPx = vp2px);})
//.④ 背景顏色與圓角設定
.backgroundColor
}.width;}
\<\/codeline>

抬頭區塊 — 漸變背景 & 缺孔位置回填

@Builder TicketHeader{
Stack{
/* 背景層：藍底漸變 */
Column
.width
.height
.linearGradient({
angle :90。colors:,]
});/* 内容層：標題 + 三行資訊 */
Column
/* 標題示例 */
Text.fontSize.fontWeight.fontColor.marginTop;/* 更多信息，…省略 */
//.--- 動態測量抬頭實際高度 ---//
).onAreaChange=>{
this.headerHeightVp = Number;this.notchYPx = vp2px);//<‑‑ 缺孔對齊抬頭底邊
          });
    }.width;
}
\<\/codeline>

八、一句话记忆法

ClipShape 用 PathShape ;话说回来，Shadow 同層跟 Clip走;Path 参数需 vp→PX ;首幀太矮要兜底，撕線零體積＋dashed border;欠孔貼著抬頭底邊走.

---

"假洞"思路只能制造表面偽裝，一旦環境改變即會穿幫；無法承載陰影，也無法自適應不同背景或截圖分享需求。​ ​ ​ ​

Sorry!The message is incomplete because it exceeds maximum allowed length.