HarmonyOS7字母索引自定义位置页实战：索引条布局位置与容器适配

yangcy9

168人浏览 · 2026-07-18 15:58:33

yangcy9 · 2026-07-18 15:58:33 发布

文章目录

前言

索引条默认放在右侧很常见，但一旦页面结构更复杂，比如顶部有筛选区、底部有工具栏，组件摆放就没那么简单了。这个案例的价值，在于它展示了 AlphabetIndexer 在布局层面的可调空间。真到项目里，很多问题都不是“会不会用组件”，而是“这个组件放在当前页面里顺不顺手”。所以这篇不会只盯 API，而是把页面结构、交互反馈和后续扩展一起看。

如果把这页当成练习材料，我会优先看它怎样围绕索引条布局位置与容器适配组织页面。因为这一层想清楚了，后面的代码基本就不会散。

这类写法尤其适合落在复杂通讯录、双栏布局页、自定义导航页这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

A hand-drawn doodle illustration on pure white pap

真正值得先看的不是细节代码

我建议先不要着急顺着源码往下滚。先回答一个更实际的问题：字母索引自定义位置页这个页面，用户一进来第一眼会看到什么，接着又会去操作哪里。结构感一旦建立起来，后面的代码就不容易看散。

A hand-drawn doodle illustration on pure white pap

页面区域	主要职责	在代码里的典型表现
头部说明区	交代当前案例在演示什么	`Text` 标题、补充说明、标签文案
核心展示区	承载组件能力的主要效果	`Column`、`Row`、业务组件本体
辅助信息区	补充状态、标签、分组或统计信息	次级文本、角标、分组标题、描述块
交互入口区	负责切换、返回、定位、选择等动作	点击事件、按钮、索引条、导航入口

这一页没有额外拆出接口，页面更多是直接围绕基础数据和组件参数展开。

如果你不是只想看懂，而是准备拿去改，这篇更关注哪些区域适合抽离、复用和替换。

状态设计这里有点东西

我在看这类页面时，通常会先找状态字段。因为索引条布局位置与容器适配这件事，最终都要落到“是谁控制、什么时候变、变了之后哪里刷新”上。

A hand-drawn doodle illustration on pure white pap

这页看起来在讲位置，实际还是离不开选中态。

isShow：负责控制示例内容是否展示。
selected：记录当前索引字母，用来让不同摆放方式下的索引条保持一致反馈。

自定义位置最容易踩的坑，是只把索引条挪到左边或右边，却忘了它和内容区的视觉关系。这里的 selected 可以理解成统一的反馈锚点：无论索引条放在哪，用户点到哪个字母，页面都应该给出稳定回应。

代码别平均看，先抓关键方法

读函数别贪多。对字母索引自定义位置页这种页面来说，真正有阅读价值的往往是那几段会改状态、触发交互或者推动页面切换的逻辑。

这个案例没有太多额外方法，核心价值主要集中在页面结构和组件组合方式。

我自己读这类方法时，通常只抓一条线：谁触发、谁被改、页面哪里立刻有反馈。把这三件事连起来，很多交互代码一下就顺了。

第一段关键代码：页面是怎么被带起来的

这一段建议慢一点看。它通常决定了页面初始状态，也决定了后续哪些区域会跟着刷新。

@State isShow: boolean = true
  @State selected: number = 0

  build() {
    Column() {
      if (this.isShow) {
        Column({ space: 16 }) {
          Text('自定义位置')
            .fontSize(20)
            .fontWeight(FontWeight.Bold)
            .fontColor(DEMO_THEME_COLOR)

          Text('AlphabetIndexer 支持放置在左侧、右侧等不同位置')
            .fontSize(13)
            .fontColor(DEMO_SUBTEXT_COLOR)
            .width('100%')

          // 右侧索引（默认）
          Column({ space: 8 }) {
            Text('右侧对齐（默认）')
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .fontColor('#333333')
              .width('100%')

这一段我通常不会一下翻过去，而是先确认下面这几个判断点：

@State 字段到底在控制显示、选择、跳转结果还是模式切换。
默认值是不是合理，页面一打开会不会就落在一个可理解的状态上。
字段命名能不能让后来的人一眼看懂用途，而不是还要翻半天 UI。

第二段关键代码：真正决定交互手感的地方

这一段完整代码适合重点看布局对比：同一组 alphabetArray 和 selected，放进不同容器后，用户感知会完全不同。右侧索引更符合通讯录习惯，左侧索引则更像工具栏或辅助导航，选哪种不是 API 问题，而是页面阅读方向的问题。

/**
 * 字母索引自定义位置页
 */
import { PRESET_COLORS, generateListItems, DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'

const alphabetArray: string[] = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')

@Entry
@Component
struct AlphabetIndexerCustomPosition {
  @State isShow: boolean = true
  @State selected: number = 0

  build() {
    Column() {
      if (this.isShow) {
        Column({ space: 16 }) {
          Text('自定义位置')
            .fontSize(20)
            .fontWeight(FontWeight.Bold)
            .fontColor(DEMO_THEME_COLOR)

          Text('AlphabetIndexer 支持放置在左侧、右侧等不同位置')
            .fontSize(13)

代码读到这里，我通常会顺手补三件事，不然后面很容易只看热闹：

这个交互入口接收的到底是什么输入。
输入进来之后，代码改了哪个状态，或者触发了哪次导航。
变化发生后，用户最先感知到的反馈会落在哪个区域。

这三个问题串起来之后，这一页基本就不只是“看过”，而是真的读懂了。

不是只看，最好按这个顺序动手

文章讲再多，都不如自己把页面点一遍。尤其是字母索引自定义位置页这种带明显交互结果的页面，只看代码很难建立手感。

先进入页面，确认首屏是不是把 字母索引自定义位置页 的主题交代清楚。
盯住核心展示区，观察默认状态下最醒目的内容是什么。
主动触发一次关键交互，比如点击、滑动、跳转、返回、切换或者选择。
回头检查状态区、提示区、标题区或者附属信息有没有跟着变化。
最后再打开源码，对照刚才那次交互，把状态变化链路串起来。

如果这五步你能边操作边说清楚页面发生了什么，后面再换成自己的数据和交互，心里会稳很多。

拿去项目里之前，我通常会做这些调整

示例页最大的风险，就是你觉得“这不难”，结果真要迁进项目里，发现数据、样式、交互边界全要补。这里提前把这些坑说开。

字母索引类页面建议先把分组数据结构稳定下来，再去调索引条样式和反馈层。
一旦页面里还要加搜索、筛选或定位结果，状态来源最好先分层，不然后面很容易互相覆盖。
只要页面里有重复块，就别硬撑着手写到底；早点抽成小组件，后面改样式和改交互都会轻松很多。
示例数据最好和布局代码分开放，不然后面一接接口，页面文件很容易立刻变臃肿。

这页不复杂，但很适合当模板

它真正值得保留的地方，不只是效果能跑出来，而是写法相对克制。你以后回来翻，会发现它很适合当中间层模板。

页面结构比较稳，后续不管是换数据还是换皮肤，成本都不会特别高。
状态数量总体可控，适合拿来练“一个页面里如何分配职责”这件事。
组件参数和页面目标之间关系比较直观，不太会出现“能跑但看不懂为什么这么配”的情况。

完整代码

下面保留整理过命名的完整 ArkTS 代码，方便你直接对照学习。这里已经去掉原始的 Demo 命名，改成了更贴近当前案例语义的名称。

/**
 * 字母索引自定义位置页
 */
import { PRESET_COLORS, generateListItems, DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'

const alphabetArray: string[] = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')

@Entry
@Component
struct AlphabetIndexerCustomPosition {
  @State isShow: boolean = true
  @State selected: number = 0

  build() {
    Column() {
      if (this.isShow) {
        Column({ space: 16 }) {
          Text('自定义位置')
            .fontSize(20)
            .fontWeight(FontWeight.Bold)
            .fontColor(DEMO_THEME_COLOR)

          Text('AlphabetIndexer 支持放置在左侧、右侧等不同位置')
            .fontSize(13)
            .fontColor(DEMO_SUBTEXT_COLOR)
            .width('100%')

          // 右侧索引（默认）
          Column({ space: 8 }) {
            Text('右侧对齐（默认）')
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .fontColor('#333333')
              .width('100%')

            Row() {
              Text(alphabetArray[this.selected])
                .fontSize(28)
                .fontWeight(FontWeight.Bold)
                .fontColor(DEMO_THEME_COLOR)
                .layoutWeight(1)
                .textAlign(TextAlign.Center)

              AlphabetIndexer({
                arrayValue: alphabetArray,
                selected: this.selected
              })
              .selectedColor(DEMO_THEME_COLOR)
              .popupColor(DEMO_THEME_COLOR)
              .usingPopup(true)
              .alignStyle(IndexerAlign.Right)
              .onSelect((index: number) => {
                this.selected = index
              })
            }
            .width('100%')
            .height(80)
            .padding({ right: 8 })
            .backgroundColor(DEMO_CARD_COLOR)
            .borderRadius(12)
          }
          .width('100%')

          // 左侧索引
          Column({ space: 8 }) {
            Text('左侧对齐')
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .fontColor('#333333')
              .width('100%')

            Row() {
              AlphabetIndexer({
                arrayValue: alphabetArray.slice(0, 10),
                selected: 0
              })
              .selectedColor(PRESET_COLORS[0].value)
              .popupColor(PRESET_COLORS[0].value)
              .usingPopup(true)
              .alignStyle(IndexerAlign.Left)
              .onSelect((index: number) => {
                this.selected = index
              })

              Text('字母索引也可以放在左侧')
                .fontSize(14)
                .fontColor(DEMO_SUBTEXT_COLOR)
                .layoutWeight(1)
                .textAlign(TextAlign.Center)
            }
            .width('100%')
            .height(100)
            .padding({ left: 8 })
            .backgroundColor(DEMO_CARD_COLOR)
            .borderRadius(12)
          }
          .width('100%')

          // 居中
          Column({ space: 8 }) {
            Text('居中展示')
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .fontColor('#333333')
              .width('100%')

            Column() {
              Text('选中：' + alphabetArray[this.selected])
                .fontSize(16)
                .fontWeight(FontWeight.Bold)
                .fontColor(PRESET_COLORS[1].value)

              AlphabetIndexer({
                arrayValue: alphabetArray.slice(0, 13),
                selected: this.selected
              })
              .selectedColor(PRESET_COLORS[1].value)
              .popupColor(PRESET_COLORS[1].value)
              .usingPopup(true)
              .alignStyle(IndexerAlign.END)
              .onSelect((index: number) => {
                this.selected = index
              })
            }
            .width('100%')
            .height(100)
            .backgroundColor(DEMO_CARD_COLOR)
            .borderRadius(12)
          }
          .width('100%')
        }
        .alignItems(HorizontalAlign.Start)
      }
      Text('字母索引自定义位置页 - AlphabetIndexer 自定义位置')
        .fontSize(12).fontColor('#999999').margin({ top: 12 })
    }
    .width('100%').height('100%').backgroundColor(DEMO_BG_COLOR).padding(16)
  }
}

收个尾

看完这一页，如果你能说清楚它的结构、状态和交互分别承担什么职责，那它的核心价值你基本就拿到了。后面无非就是换成你自己的数据和页面语义。

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责