企业官网建设流程全解析

做鸿蒙开发的同学大概率都遇到过这个画面：一个列表项卡片，只想在底部加一条浅灰分割线，随手写下.border({ width: 1, color: '#E5E5E5' })，跑起来一看，四条边全给框上了。改成.border({ width: { bottom: 1 } })，线是出来了，可配上圆角之后两端又开始往上翘。再往后做标签选中态，用if/else切换了两个组件，点击瞬间整个列表项闪一下，之前的过渡动画也全没了。

ArkTS 的边框设置看着就一个.border()，实际用起来牵扯到三个层次的问题：属性对象的形状、组件自身的绘制边界、以及状态到样式的映射方式。这三个层次任何一层理解偏了，画出来的东西就不是你想要的那条线。下面我按自己踩过的顺序，把单边边框、条件边框这两件事拆开讲一遍，代码都能直接抄。

1. 拆开 BorderOptions：单写 width 为什么常常看不到线

.border()接收的是一个BorderOptions对象，它里面有四个子属性：width、color、radius、style。绝大多数「边框不显示」的问题，根因都能在这四个子属性的默认值上找到答案。

1.1 四个子属性各自的默认值决定了你看到什么

border的radius默认是 0，也就是直角；style默认是BorderStyle.Solid，实线。这两个一般不会坑人。真正容易出问题的是width和color这一对：宽度默认是 0，颜色默认是黑色。

宽度默认 0 意味着，如果你只写了color而没写width，什么都不会画出来。反过来，如果你只写了width而没写color，线会正常出现，但是一条黑色的实线——很多同学以为自己「没设置颜色所以没有线」，其实是设了宽度就一定有颜色，只是颜色默认是黑的，在浅色卡片上非常扎眼。

所以我在写边框的时候有个固定习惯：width 和 color 永远成对出现，需要给哪条边就同时给哪条边的宽度和颜色，不依赖任何默认值。这个习惯看着啰嗦，但能省掉大量「为什么这条线颜色不对」的排查时间。

// 推荐写法：方向和颜色成对指定，不依赖默认值 Text('订单编号：202405120001') .padding(16) .backgroundColor(Color.White) .border({ width: { bottom: 1 }, color: { bottom: '#E5E6EB' }, style: BorderStyle.Solid })

1.2 EdgeWidths 这类四向对象的传参规则

单边边框之所以能成立，是因为width、color、style这三个属性都支持两种传参形态：一种是单个值（Length/ResourceColor/BorderStyle），一种是四向对象（EdgeWidths/EdgeColors/EdgeStyles）。四向对象的结构就是top、right、bottom、left四个可选的键。

这里有个特别容易混的点：四向对象里的键是可选的，没写的方向就是「不设置」，而不是「设为 0」。没设置的方向会走默认值，而默认宽度本来就是 0，所以视觉上和不设置没区别；但如果那个方向之前被别的属性调用设置过，情况就不一样了。这也是为什么不建议在同一个组件上混用.border()和.borderWidth()——两个入口都会写同一份渲染属性，先后顺序会直接影响结果。

四向对象不能简写。不像 CSS 里border-width: 1px 0 0 0那种四值简写，ArkTS 的四向对象必须把键名写全，{ bottom: 1 }就是只给底边。想给「上边和底边」两条线，就得老老实实写{ top: 1, bottom: 1 }。

// 只给上、下两条线，左右不给 Row() { Text('分组成员') } .padding({ left: 16, right: 16, top: 12, bottom: 12 }) .border({ width: { top: 1, bottom: 1 }, color: { top: '#E5E6EB', bottom: '#E5E6EB' } })

1.3 后置属性与.border()的覆盖顺序

ArkTS 还提供了四个独立的通用属性：.borderWidth()、.borderColor()、.borderStyle()、.borderRadius()。它们和.border()是操作同一份数据的两个入口，链式调用时后写的覆盖先写的，而且只覆盖自己负责的那一项。

这意味着.border({ width: 1, color: '#E5E6EB' }).borderWidth(2)最终宽度是 2，颜色还是#E5E6EB。反过来.borderWidth(2).border({ width: 1, color: '#E5E6EB' })最终宽度是 1。

我个人的用法是：样式固定的边框只走.border()一个入口，条件边框也尽量在.border()内部用表达式完成。只有一种情况我会用后置属性——某个基础组件已经在内部写死了.border()，我只想追加一个圆角，这时候.borderRadius(8)比整体重写.border()更省事。

提示：在同一个组件上混用.border()和后置属性时，建议在代码注释里标一句「此处宽度由后置属性覆盖」，不然后面接手的人改.border()会发现改了没反应。

2. 单边边框的三种写法与真实取舍

单边边框的需求在业务里出现频率极高：分割线、选中下划线、输入框的底部提示线、卡片顶部的分类色条。它的实现方式不止一种，选错了后面会一直被样式问题追着跑。

2.1 单边边框遇上圆角的绘制冲突

这是我最想强调的一点。给组件同时设置圆角和单边边框，两者会打架。

原因是边框的绘制路径是沿着组件的圆角外框走的。当你只给底边指定宽度时，渲染层依然要沿着整个圆角矩形去描这条边，于是表现就变成了：底边线的左右两端顺着圆角往上弯，看起来像一个小托盘；或者圆角处的缺口被填成直角，圆角效果被破坏。

不同版本上的表现略有差异，有的版本是两端弯折，有的版本是圆角那一圈被描出细弧。结论是一样的：圆角 + 单边边框属于不可靠组合，能避开就避开。

我的处理原则很直接：

• 需要圆角的卡片，分割线交给Divider组件或者独立的子容器来画，不要用单边边框。
• 一定要用单边边框，就把radius去掉，保持直角。
• 既想要圆角又想要勾勒轮廓，那就四条边一起给宽度，别只给一边。

2.2 用 Divider 或子容器接管分割线

Divider组件就是干这个的，它只画一条线，不参与内容的布局计算，也不会和圆角冲突。用法上要注意两点：一是水平方向的分割线通常需要显式给.width('100%')，否则在某些容器里它只占自身内容宽度；二是想让线条两端缩进，用.margin()处理。

Column() { Text('第一项').padding(16) Divider() .strokeWidth(1) .color('#E5E6EB') .width('100%') .margin({ left: 16, right: 16 }) Text('第二项').padding(16) } .backgroundColor(Color.White) .borderRadius(12) .clip(true)

另一种更「可控」的写法是用子容器模拟线：一个高度 1vp、宽度撑满的Row，配一个背景色。这种写法的好处是线本身就是一个普通组件，能加渐变色、能加透明度、能做动画，还能在LazyForEach里按条件决定要不要渲染。缺点是多了一层节点。数据量大的列表里，我更倾向用List的divider属性而不是给每个 item 加子容器。

// 用子容器做线的写法，适合需要渐变或动画的场景 Column() { Text('内容区').width('100%').padding(16) Row() .width('100%') .height(1) .backgroundColor('#E5E6EB') }

2.3 列表场景直接用 List 的 divider

如果分割线出现在List里，别急着给ListItem加边框。List自带了divider属性，它能在相邻 item 之间画线，并且支持左右缩进，这是最省事也最稳的方案。

List({ space: 0 }) { ForEach(this.dataList, (item: string) => { ListItem() { Text(item).padding(16).width('100%') } }) } .divider({ strokeWidth: 1, color: '#E5E6EB', startMargin: 16, endMargin: 16 })

对比一下几种单边线的实现，我给一张表，按「是否有圆角」「是否在列表里」两个维度选就行：

最后一行值得展开一句：如果你想要的是「卡片整体描一圈边」，就用全边框，别用单边。全边框配圆角是完全正常的组合，绘制路径天然吻合，不会出现弯折。很多人绕远路，就是因为一开始把需求误判成了单边。

3. 条件边框：状态到样式的映射方式

条件边框的本质是把一个状态值映射成一组边框样式，选中态显示、未选中态隐藏，或者不同状态显示不同颜色和粗细。实现路径有四五种，选哪种取决于状态从哪来、变化频率有多高。

3.1 三元表达式直写 border 的写法与类型陷阱

最直接的写法就是在.border()里用三元表达式。这里有个 ArkTS 特有的坑：三元表达式的两个分支尽量返回同一种类型。

this.selected ? '#0A59F7' : Color.Transparent这种写法，两个分支一个是string一个是Color，在严格类型检查下容易报类型不匹配。稳妥的做法是两个分支都用十六进制字符串，Color.Transparent对应的写法是'#00000000'（ARGB 八位，前两位是透明度）。这样返回类型天然统一，编译也不会出问题。

@Entry @Component struct TagItem { @State selected: boolean = false build() { Column() { Text('推荐') .fontSize(14) .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .border({ width: this.selected ? 1 : 0, color: this.selected ? '#0A59F7' : '#00000000', radius: 6, style: BorderStyle.Solid }) .onClick(() => { this.selected = !this.selected }) } .padding(16) } }

这里用的是「切换宽度」而不是「切换颜色」。两种做法的布局表现是一样的（边框绘制在组件自身区域内，不参与父容器的测量），所以不会出现选中瞬间内容抖动的现象，这是用边框表达选中态相比换背景色、换组件的一个隐性优势。我个人更习惯切宽度，语义更直白，也不用担心透明度叠加造成的边缘噪点。

注意：宽度为 0 和透明色在布局上等价，但语义不同。如果一个组件要在两种状态间反复切换，建议全程用宽度切换，避免一会儿 0 一会儿透明色，把后面的维护者绕晕。

3.2 @Styles、@Extend、stateStyles 该选哪个

当条件边框出现在多个组件上时，把样式抽出来是必然的。ArkTS 给了三个工具，它们的边界完全不同。

@Styles只能写通用属性，也就是border这类所有组件都有的属性，不能写.fontSize()这种组件私有的。它还有一个硬限制：不能传参。所以用@Styles做条件边框，只能拆成两个函数，或者在函数内部读组件状态。

@Extend可以扩展某个具体组件类型，并且支持传参，这正好补上了@Styles的短板。条件边框用@Extend写起来最顺手。

stateStyles处理的是交互驱动的状态：normal、pressed、disabled、focused。按下态描边这种需求，用stateStyles比自己写onTouch管理状态省事得多，也更容易做对。

// @Extend 支持传参，条件边框的首选 @Extend(Text) function tagBorder(active: boolean) { .border({ width: active ? 1 : 0, color: active ? '#0A59F7' : '#00000000', radius: 6, style: BorderStyle.Solid }) } // stateStyles 处理按下态，不需要手写 onTouch @Entry @Component struct PressableCard { @Styles pressedBorder() { .border({ width: 1, color: '#0A59F7', radius: 12 }) } build() { Column() { Text('按下我看边框') .padding(16) } .backgroundColor(Color.White) .borderRadius(12) .stateStyles({ pressed: this.pressedBorder }) .onClick(() => { // 业务逻辑 }) } }

三者怎么选，我给一个判断路径：样式固定且全局复用 →@Styles；需要传参或绑定具体组件 →@Extend；跟随按下、禁用、聚焦等交互状态 →stateStyles。三者可以叠加使用，比如用@Extend定义常态边框，用stateStyles定义按下态覆盖。

3.3 attributeModifier：多状态、多主题下的动态边框

AttributeModifier是更重的一层方案，它把「属性怎么设」这件事从组件上剥离出来，交给一个实现了接口的类。它最实在的价值在于原生支持按交互状态分方法，同一个类里可以分别实现applyNormalAttribute、applyPressedAttribute、applyFocusedAttribute、applyDisabledAttribute，框架会按当前状态自动选方法，不需要你自己维护一堆布尔量。

class TagBorderModifier implements AttributeModifier<TextAttribute> { applyNormalAttribute(instance: TextAttribute): void { instance.border({ width: 1, color: '#E5E6EB', radius: 6 }) } applyPressedAttribute(instance: TextAttribute): void { instance.border({ width: 1, color: '#0A59F7', radius: 6 }) } applyDisabledAttribute(instance: TextAttribute): void { instance.border({ width: 1, color: '#F2F3F5', radius: 6 }) } }

// 使用侧 @State modifier: TagBorderModifier = new TagBorderModifier() Text('标签') .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .attributeModifier(this.modifier)

这里有个必须知道的边界：AttributeModifier更适合由框架驱动的交互状态，而不是由业务数据驱动的选中态。因为它的属性变化不会自动触发重绘，业务数据变了之后你还要手动触发一次刷新，等于绕了一圈。所以我的用法是：交互态（按下、禁用、聚焦）交给AttributeModifier，业务选中态老老实实用三元表达式或者@Extend。这个分工能省掉很多「改了状态但界面没动」的排查时间。

4. 边框落地时的尺寸、动画与主题细节

属性写对了只是第一步，真正上线之后还会碰到尺寸预期、动画观感、主题适配这三类问题。

4.1 边框会不会撑大组件

结论是不会。ArkTS 里边框绘制在组件自身的区域之内，不参与父容器的测量计算。给一个高度 48vp 的Row加 4vp 边框，它的外部占位仍然是 48vp，不会变成 56vp，被压缩的是内容的可用区域。

这一点和 Web 里默认的content-box不一样，倒和box-sizing: border-box的表现一致。带来的好处是：修改边框宽度不会引起布局重排，也不会让相邻元素位移，选中态切换时页面不会抖。带来的代价是：边框是「向内挤」的，视觉上组件看起来会比原来小一圈，如果组件尺寸是固定的，内边距需要相应留足。

还有一个容易忽略的点：边框画在背景色之上。所以给组件设了backgroundColor之后再设边框，边框一定看得见；反过来如果你发现边框「消失了」，先检查宽度和颜色，别怀疑层级——层级上它永远在最上面。

// 尺寸固定时，给内容留够内边距，避免边框挤压文字 Row() { Text('固定高度的行') .fontSize(16) .textAlign(TextAlign.Center) .width('100%') } .height(48) .padding({ left: 16, right: 16 }) .border({ width: 1, color: '#E5E6EB' })

4.2 选中态描边要不要加动画

不加动画的边框切换会比较生硬，尤其是颜色从灰跳到蓝的瞬间。所以要加，但加在哪一层有讲究。

.animation()加在border之后，会作用于它前面的可动画属性。实测下来，颜色的过渡是稳的，宽度过渡在一些版本上会出现半像素闪烁，因为宽度是在描边路径上做插值，边缘抗锯齿会跟着变。我的习惯是只让颜色动，宽度直接切换：

Text('推荐') .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .border({ width: this.selected ? 1 : 0, color: this.selected ? '#0A59F7' : '#00000000', radius: 6 }) .animation({ duration: 180, curve: Curve.EaseOut })

如果你需要的是「描边从外向内长出来」这种更明显的动效，边框本身做不到，得用一层叠加视图：外层Stack里放一个撑满的Row，给它边框和透明度变化，用opacity做过渡，内容层单独放。这样动的是透明度，渲染开销最小，观感也干净。

4.3 深色模式与多主题下的边框颜色

硬编码色值是深色模式适配最大的敌人。'#E5E6EB'这种浅灰在浅色底上很舒服，切到深色底就成了刺眼的一条亮线。正确做法是把颜色定义成资源，通过$r引用，系统切换深色模式时自动跟随。

.border({ width: { bottom: 1 }, color: { bottom: $r('app.color.divider') } })

资源文件里分别在resources/base/element/color.json和resources/dark/element/color.json定义同名色值即可，组件代码完全不用改。ResourceColor本身是支持Resource类型的，所以$r引用的色值可以直接塞进EdgeColors。

另外提一个实用技巧：需要边框与背景叠加、让线条看起来「更淡」时，用带透明度的 ARGB 色值比调浅颜色更自然。'#1F000000'是 12% 透明度的黑，压在白色卡片上和浅灰效果接近，压在浅灰卡片上会自动变深一点，比固定色值更贴合复杂背景。

5. 边框不显示或画歪了，按这个顺序排查

边框这类问题排查起来最怕东一榔头西一棒槌。我整理了一套固定顺序，从属性层往绘制层走，基本三轮之内能定位。

5.1 从属性到绘制的逐步定位法

第一步，验证宽度和颜色是否都到了。把边框临时改成width: 3, color: Color.Red，全边框形式，看能不能画出来。画得出来说明基础能力没问题，问题在方向和条件上；画不出来说明跟边框本身无关，往下走。

第二步，检查是不是条件表达式没生效。如果改成了全边框红色还是不出来，那就是渲染这一层根本没拿到这个属性。检查状态变量有没有被@State装饰、三元表达式的返回类型是否统一、@Styles里有没有写组件私有属性。

第三步，检查父容器有没有裁切。如果用了.clip(true)或者父级是滚动容器，加上圆角之后，边缘的描边有可能被裁掉一部分，表现为「线只有中间一段」。这时候把裁剪临时关掉验证。

第四步，检查圆角和单边的组合。如果线出来了但形状不对（两端上翘、圆角缺口被填平），那就是第 2 章说的圆角与单边边框冲突，换Divider或子容器。

第五步，检查是不是被别的属性覆盖了。同一个组件上如果混用了.border()和.borderWidth()等后置属性，或者外层有@Extend又叠加了stateStyles，最终的宽度和颜色可能来自你没想到的那一处。

5.2 常见异常表现与成因对照

这张表我基本是贴在项目 Wiki 里的，新人第一次遇到边框问题先对照一遍，比在群里问快得多。

最后再补一个小经验。真正让我少踩坑的，不是记住了多少个属性名，而是在写边框之前先问自己一句「这条线是装饰还是结构」。装饰性质的线——分割线、下划线、选中轮廓——优先考虑Divider、子容器、List.divider，它们和圆角、裁剪、滚动容器都不打架；结构性质的线——输入框边框、卡片描边——才用.border()，而且尽量四条边一起给。把这两类需求分开，前面提到的绝大多数异常都从源头消失了。