harmonyos-ui-design-guides-mcp 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# HarmonyOS UI 设计指南 MCP 服务器
+
+把鸿蒙 UI 设计指南(166 篇,设计规范/视觉风格/控件设计/交互/多设备适配)封装成 MCP 检索服务,供 Claude Code / opencode / Cursor / Cline 等客户端在开发时查设计规范。**文档随包发布,装包即用、零配置。**
+
+与姊妹项目分工:
+- **本服务(ui-design-guides)**:查**设计怎么做**(视觉/交互/控件设计规范)
+- [`harmonyos-guides-mcp`](https://github.com/2351548518/harmonyos-guides-mcp):查 **API 用法**(代码层面)
+- [`harmonyos-api-references-mcp`](https://github.com/2351548518/harmonyos-api-references-mcp):查**接口精确定义**
+- [`harmonyos-best-practices-mcp`](https://github.com/2351548518/harmonyos-best-practices-mcp):查**场景最佳实践 + 参考代码**
+
+配合:先本服务定设计规范,再用 guides/api-references 查实现该设计的 API。
+
+## 提供的工具
+
+| 工具 | 作用 |
+|------|------|
+| `search_design_guides({query, limit?})` | 全文检索设计指南(中文友好),返回相关度排序的文档列表(含标题、分类路径) |
+| `get_design_guide({name})` | 读取指定设计指南(docId)的完整 Markdown 正文 |
+| `list_design_guides_by_topic({topic?})` | 按分类路径浏览;支持多级下钻(如 `控件` → `控件 / 导航类`) |
+
+数据规模:166 篇设计指南,9 个顶级类——控件(49)、针对多设备设计(26)、通用设计基础(23)、系统特性&能力(22)、应用设计最佳实践(14)、元服务设计(12)、人机交互(11)、应用 UX 体验标准(8)、变更说明(1)。
+
+## 安装(最终用户)
+
+无需 clone 本仓库,直接配置客户端(以 Claude Code / opencode `.mcp.json` 为例):
+
+```json
+{
+  "mcpServers": {
+    "harmonyos-ui-design-guides": {
+      "command": "npx",
+      "args": ["-y", "harmonyos-ui-design-guides-mcp"]
+    }
+  }
+}
+```
+
+或全局安装:`npm install -g harmonyos-ui-design-guides-mcp`。任何支持 stdio 的 MCP 客户端同样配置。
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `BP_DOCS_DIR` | 包内 `data/docs` | 文档目录(一般无需改) |
+
+## 更新
+
+设计指南和服务器会持续更新(版本号见 `package.json`)。
+
+**更新服务器**:
+
+```bash
+# npx -y 方式:无需手动操作,每次启动自动拉最新版
+# 全局安装方式:手动更新
+npm update -g harmonyos-ui-design-guides-mcp
+# 或锁定最新版
+npm install -g harmonyos-ui-design-guides-mcp@latest
+```
+
+更新后**重启 AI 客户端**(Claude Code / opencode / Cursor 等),让新进程加载新版 MCP。
+
+**更新文档**:166 篇设计指南随包内置(`data/docs/`),更新 npm 包即同步更新,无需单独操作。纯文档,无代码包。
+
+**查看版本**:
+```bash
+npm view harmonyos-ui-design-guides-mcp version   # 最新发布版
+npm ls -g harmonyos-ui-design-guides-mcp          # 本地已装版本
+```
+或看客户端 MCP 面板里服务器的 `version` 字段。
+
+## 开发与发布(维护者)
+
+```bash
+cd harmonyos-ui-design-guides-mcp
+npm install
+npm run build          # 编译
+npm run prepack        # 拷文档到 data/ + 编译(发布前自动)
+npm run selfcheck      # 自检三个工具
+npm publish
+```
+
+包内含:`dist/` + `data/`(文档+索引) + README。源码 `src/` 不随包。
+
+## 验证
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## 许可
+
+设计指南文档源自华为 HarmonyOS 官方文档,版权归华为所有,此处仅作开发辅助检索用途。MCP 服务器代码(MIT)见 `package.json`。

package/data/INDEX.md

@@ -0,0 +1,181 @@
+# UI 设计指南文档索引 (design-guides)
+
+> 共 166 篇，目录 `Harmonyos_UI_design-guides_docs/`。文件名即文档 slug（fileName）。
+
+- **通用设计基础**
+  - `design-concepts-0000001795698445.md` — 设计理念
+  - `visual_design-0000001823497081.md` — 视觉风格
+    - `color-0000001776857164.md` — 色彩
+    - `font-0000001828772001.md` — 鸿蒙黑体
+    - `typography-0000002622688363.md` — 文本排版
+    - `application-icon-0000001953444009.md` — 应用图标
+    - `system-icons-0000001929854962.md` — HarmonyOS Symbol
+    - `immersivelight-0000002612101053.md` — 沉浸光感
+    - `corner-radius-parameter-0000002556468705.md` — 圆角参数
+    - `interval-parameter-0000002562577161.md` — 间隔参数
+  - `design-layout-0000001748539680.md` — 布局
+    - `design-layout-basics-0000001795579413.md` — 布局基础
+    - `design-responsive-layout-structure-0000001748539684.md` — 响应式应用架构
+    - `design-responsive-layout-method-0000001795698449.md` — 响应式布局方法
+  - `design-animation-0000001750078484.md` — 动效
+    - `design-animation-overview-0000001750985338.md` — 概述
+    - `animation-design-principles-0000001750237392.md` — 设计原则
+    - `animation-attributes-0000001797117229.md` — 动效属性
+    - `transition-animation-0000001750078488.md` — 转场动效
+    - `gesture-animation-0000001797038213.md` — 手势动效
+  - `design-ui-language-0000001795698453.md` — 界面用语
+  - `design-globalization-0000001748539688.md` — 全球化
+  - `privacy-0000001929972682.md` — 隐私
+- **控件**
+  - `general_overview-0000001929599380.md` — 概览
+  - `component_navigation-0000001929763488.md` — 导航类
+    - `bottomtab-0000001956787789.md` — 底部页签
+    - `chipsgroup-0000001929788350.md` — 子页签
+    - `titlebar-0000001929628982.md` — 标题栏
+    - `swiper-0000001956947629.md` — 导航点
+  - `component_view-0000001929604116.md` — 展示类
+    - `text-0000001956975261.md` — 文本
+    - `divider-0000001956815469.md` — 分隔器
+    - `subheader-0000001929816012.md` — 子标题
+    - `progress-0000001929656644.md` — 进度条
+    - `alphabetindexer-0000001956975265.md` — 索引条
+    - `scrollbar-0000001956815473.md` — 滚动条
+    - `badge-0000001929816016.md` — 新事件标记
+    - `toast-0000001929656648.md` — 即时反馈
+    - `component_snackbar-0000002340726169.md` — 即时操作
+    - `popup-0000001956975269.md` — 气泡提示
+    - `datapanel-0000001956815481.md` — 数据可视化
+    - `qrcode-0000001929816020.md` — 二维码
+    - `textclock-0000001929656652.md` — 文本时钟
+    - `image-0000001956975273.md` — 图片
+    - `blank-0000001956815485.md` — 空白
+  - `component_controls-0000001956922769.md` — 操作类
+    - `button-0000001929683228.md` — 按钮
+    - `select-0000001957001873.md` — 下拉按钮
+    - `togglebutton-0000001956842045.md` — 状态按钮
+    - `chips-0000001929842624.md` — 操作块
+    - `toolbar-0000001929683232.md` — 工具栏
+    - `component_actionbar-0000002306891560.md` — 核心操作栏
+    - `menu-0000001957001877.md` — 菜单
+    - `textselection-0000001956842049.md` — 文本选择菜单
+  - `component_input-0000001956762929.md` — 输入类
+    - `textinput-0000001957012557.md` — 文本框
+    - `search-0000001956852741.md` — 搜索框
+    - `counter-0000001929853284.md` — 数字加减
+    - `patternlock-0000001929853902.md` — 图案锁
+  - `component_selection-0000001929763496.md` — 选择类
+    - `checkbox-0000001957012561.md` — 勾选
+    - `toggleswitch-0000001956852745.md` — 开关
+    - `radio-0000001929853288.md` — 单选框
+    - `rating-0000001929853906.md` — 评分条
+    - `slider-0000001957012565.md` — 滑动条
+    - `picker-0000001956852749.md` — 选择器
+    - `color-picker-0000002574393143.md` — 色彩选择器
+    - `segmentbutton-0000001929853292.md` — 分段按钮
+  - `component_container-0000001929604124.md` — 容器类
+    - `list-0000001929853910.md` — 列表
+    - `dialog-0000001957012569.md` — 弹出框
+    - `bindsheet-0000001956852753.md` — 半模态面板
+- **人机交互**
+  - `hmi-overview-0000001795410269.md` — 概述
+  - `hmi-touchscreen-0000001928273206.md` — 手势
+  - `hmi-cursor-0000001795531205.md` — 光标交互
+  - `hmi-focus-0000001748650376.md` — 焦点导航
+  - `hmi-mouse-0000001930021626.md` — 鼠标
+  - `hmi-keyboard-0000001928070488.md` — 键盘
+  - `hmi-touchpad-0000002464444730.md` — 触控板
+  - `hmi-scenes-0000001748650380.md` — 常用交互
+    - `hmi-scenes-drag-0000001795410277.md` — 拖拽
+    - `hmi-scenes-selection-0000001957005521.md` — 框选
+  - `hmi-interaction-events-0000001795531217.md` — 交互事件归一
+- **系统特性&能力**
+  - `system-features-0000001826860773.md` — 系统特性
+    - `navigation-0000001957075737.md` — 导航条
+    - `system-features-notification-0000001793074217.md` — 通知
+    - `system-features-live-view-0000001955186861.md` — 实况窗
+    - `system-features-multi-window-interaction-0000001795392917.md` — 多窗口交互
+    - `floatview-0000002624640357.md` — 闪控球和闪控窗
+    - `system-features-service-widget-0000002087671904.md` — 服务卡片
+    - `pip-0000001927422624.md` — 画中画
+    - `dark-mode-0000001823255497.md` — 深色模式
+    - `status-bar-0000001776775568.md` — 状态栏
+    - `broadcasting-control-0000001957017133.md` — 播控中心
+    - `shortcat-0000002550987962.md` — 桌面快捷方式
+  - `system-capabilities-0000001780261034.md` — 系统能力
+    - `share-0000001957076313.md` — 分享
+    - `id-0000001880001344.md` — 华为账号开放登录
+    - `huaweipay-0000002054558905.md` — 华为支付
+    - `preview-0000001957112409.md` — 预览
+    - `system-capabilities-launch-page-0000002311335748.md` — 启动页
+    - `onehop-0000002354602581.md` — 碰一碰
+    - `i-connect-0000002354482789.md` — 靠近发现
+    - `smart-reachability-0000002556657823.md` — 智感握姿
+    - `parallel_view-0000002588655180.md` — 平行视界
+- **元服务设计**
+  - `ux-guidelines-overview-0000001938867005.md` — 概述
+  - `ux-guidelines-overview-0000001939135629.md` — 元服务基本要素
+    - `ux-guidelines-overview-0000001900384976.md` — 基础信息
+    - `ux-guidelines-overview-0000001939144821.md` — 服务卡片
+  - `ux-guidelines-overview-0000001900218352.md` — 元服务体验场景
+  - `ux-guidelines-overview-0000001900378248.md` — 设计原则
+    - `ux-guidelines-overview-0000001900422910.md` — 通用友好
+    - `ux-guidelines-overview-0000001939183197.md` — 轻量高效
+    - `ux-guidelines-overview-0000001900424082.md` — 简洁高级
+    - `ux-guidelines-overview-0000001900584166.md` — 安全可靠
+  - `best-practices-0000002004044485.md` — 最佳设计实践
+    - `accounts-0000001967444380.md` — 账号
+- **针对多设备设计**
+  - `phone-0000001776694632.md` — 手机
+  - `folding-screen-0000001929865346.md` — 折叠屏
+    - `design-principles-0000001957023989.md` — 设计原则
+    - `foldable-0000002352875141.md` — 双折叠
+    - `trifold-0000002352915021.md` — 三折叠
+    - `flip-0000002321233974.md` — 阔折叠
+  - `pad-0000001823654157.md` — 平板
+  - `2in1-0000001777531700.md` — 电脑
+    - `concept-0000002353669657.md` — 设计概述
+    - `window-0000002321868010.md` — 窗口框架
+    - `app-design-0000002353509845.md` — 应用设计
+    - `statusbar-0000002319710910.md` — 应用接入状态栏
+    - `foldable-pc-0000002322600098.md` — 折叠电脑
+  - `smart-cockpit-0000002045925712.md` — 智能座舱
+    - `smart-cockpit-overview-0000002592486432.md` — 概述
+    - `smart-cockpit-basic-experience-0000002592646356.md` — 基础体验要求
+    - `smart-cockpit-ux-basic-0000002622965869.md` — 设计基础
+    - `smart-cockpit-system-architecture-0000002623086005.md` — 系统架构
+    - `smart-cockpit-application-architecture-0000002592486434.md` — 应用架构
+    - `smart-cockpit-hicar-0000002592646358.md` — HUAWEI HiCar
+  - `wearable-0000002164711032.md` — 智能穿戴
+    - `wearable-overview-0000002197410498.md` — 概述
+    - `application-architecture-0000002202799801.md` — 应用架构
+    - `human-machine-interaction-0000002167648022.md` — 人机交互
+    - `spacing-parameters-0000002202912577.md` — 间隔参数
+  - `vision-0000002321377950.md` — 智慧屏
+- **应用设计最佳实践**
+  - `practices-overview-0000001746498066.md` — 概述
+  - `responsive-design-examples1-0000001957369849.md` — 影音娱乐类
+  - `responsive-design-examples2-0000001793536901.md` — 社交通讯类
+  - `responsive-design-examples3-0000001746498074.md` — 拍摄美化类
+  - `responsive-design-examples4-0000001746657290.md` — 新闻阅读类
+  - `responsive-design-examples5-0000001930419478.md` — 电商购物类
+  - `responsive-design-examples6-0000001793536905.md` — 金融理财类
+  - `convenient-life-0000001957252465.md` — 便捷生活类
+  - `tourist-accommodation-0000001957241545.md` — 旅游住宿类
+  - `travel-and-navigation-0000001957391017.md` — 出行导航类
+  - `mobile-payment-0000001957421613.md` — 移动支付类
+  - `games-0000001930189974.md` — 游戏类
+  - `cars-0000001930233436.md` — 汽车类
+  - `office-0000002315825496.md` — 办公类
+- **应用 UX 体验标准**
+  - `ux-guidelines-overview-0000001760867048.md` — 概述
+  - `ux-guidelines-general-0000001760708152.md` — 通用应用 UX 体验标准
+  - `ux-guidelines-large-screen-0000001807707561.md` — 大屏应用 UX 体验标准
+  - `ux-guidelines-foldable-screen-0000001807866557.md` — 折叠屏应用 UX 体验标准
+  - `ux-guidelines-2in1-0000001777895636.md` — 电脑应用 UX 体验标准
+  - `ux-guidelines-vision-0000002360813381.md` — 智慧屏应用 UX 体验标准
+  - `ux-standard-overview-0000002019655177.md` — 元服务 UX 体验标准
+  - `ux-guidelines-wearable-0000002503475023.md` — 智能穿戴应用 UX 体验标准
+- **变更说明**
+  - `whats-new-0000002189266636.md` — 变更说明
+
+> 共计 166 篇文档。

package/data/docs/2in1-0000001777531700.md

@@ -0,0 +1,15 @@
+# 电脑
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/design-guides/2in1-0000001777531700
+> 文档标识(fileName): 2in1-0000001777531700  
+> 目录(catalogName): design-guides  
+> 语言: cn  
+> 更新时间: 2025-07-01 03:19:34  
+> 导航地址: /hmos/design
+
+---
+- **[设计概述](https://developer.huawei.com/consumer/cn/doc/design-guides/concept-0000002353669657)**
+- **[窗口框架](https://developer.huawei.com/consumer/cn/doc/design-guides/window-0000002321868010)**
+- **[应用设计](https://developer.huawei.com/consumer/cn/doc/design-guides/app-design-0000002353509845)**
+- **[应用状态栏接入](https://developer.huawei.com/consumer/cn/doc/design-guides/statusbar-0000002319710910)**
+- **[折叠电脑](https://developer.huawei.com/consumer/cn/doc/design-guides/foldable-pc-0000002322600098)**

package/data/docs/accounts-0000001967444380.md

@@ -0,0 +1,105 @@
+# 账号
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/design-guides/accounts-0000001967444380
+> 文档标识(fileName): accounts-0000001967444380  
+> 目录(catalogName): design-guides  
+> 语言: cn  
+> 更新时间: 2025-11-25 10:58:12  
+> 导航地址: /hmos/design
+
+---
+#### 使用华为账号登录
+
+## 概述
+
+华为账号（Account Kit）提供简单、快速、安全的登录功能，让用户快捷地使用华为账号登录元服务，当元服务涉及账号体系和登录能力时，需规范使用华为账号能力。通过用户授权，华为账号可提供手机号、头像、收货地址、发票抬头等用户信息，无需用户手动输入复杂信息，帮助元服务更高效的完成履约流程。元服务设计时，建议按照官方规范指引进行设计实现。
+
+## 静默登录
+
+**场景约束**
+
+**使用任意元服务，必须满足以下两点条件：**
+
+1）用户设备已登录华为账号
+
+用户使用元服务必须登录华为账号。用户设备下华为账号是否登录判断，由系统自动处理，开发者无需任何处理。
+
+① 用户设备未登录华为账号时，点击任一元服务入口访问使用元服务时须先完成华为账号登录。
+
+② 用户只能通过系统设置入口退出华为账号登录。用户退出华为账号登录后，系统将清理后台运行的元服务任务及进程，无法访问使用任一元服务。
+
+2）用户同意平台统一的用户协议与隐私声明，相关接入指南请参阅[托管隐私声明](https://developer.huawei.com/consumer/cn/doc/app/agc-help-privacy-policy-atomic-0000002317135133)。
+
+**获取 Openid & UnionID 静默登录**
+
+**元服务内涉及账号体系时，需调用官方提供的登录API进行静默登录**
+
+1）登录API是基于华为账号体系提供的登录能力。在用户同意隐私声明后，开发者可通过调用登录API，方便地获取用户身份标识，快速建立元服务内的用户体系，让用户直接使用服务，开展经营活动。用户打开元服务时，不需要用户点击登录/注册按钮，开发者即可获取用户唯一标识OpenID和用户在该元服务下的唯一标识UnionID，完成静默登录。开发者可以根据用户标识来生成自定义登录态，用于后续业务逻辑中前后端交互时识别用户身份，相关接入指南请参阅[静默登录](https://developer.huawei.com/consumer/cn/doc/atomic-guides/account-atomic-silent-login)。
+
+2）开发者调用华为账号体系，需有页面呈现用户登录状态。如，开发者需要在“我的”相关页面呈现用户登录状态，建议使用[默认头像](https://developer.huawei.com/images/download/next/yuanfuwu-touxiang.zip) + 华为用户（或自定义昵称，如“元服务名称+用户”），并默认显示为已登录状态。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185805.46638179302148042477103438660094:50001231000000:2800:C4CFC76C9CC22435BDC891C7A4DC03B5B93CE42A0A2CC07794ABD38424DB7974.png "点击放大")
+
+使用华为账号登录是元服务使用的基本要求，开发者应避免在用户界面直接使用“注册”、“登录”、“退出登录”、“注销账号”等描述，避免误导用户。 开发者不应引导用户进行账号登录，不可使用自行设计实现的登录界面，相关设计可参阅[开发者可以使用自行设计的登录界面吗？](https://developer.huawei.com/consumer/cn/doc/atomic-faqs/faqs-common-account-5)
+
+元服务内如涉及使用开发者账号体系，需与华为账号建立关联，相关设计请参阅[开发者怎么在元服务中使用开发者账号体系？](https://developer.huawei.com/consumer/cn/doc/atomic-faqs/faqs-common-account-6)当开发者提供注销等账号服务，应明确操作对象，如使用“注销XX账号”等描述。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185806.56816252761416564689487524190401:50001231000000:2800:638704B9980EF4B101E5EE19CF93C18805CC821C185DBC134C6E42EB96402329.png "点击放大")
+
+#### 获取华为账号用户信息
+
+## 概述
+
+当元服务需要获取或完善用户个人资料（头像、昵称、手机号、收货地址、发票抬头）时，可通过Account Kit提供的相关能力，引导用户填写、管理相关信息并完成授权。
+
+## 获取头像
+
+当元服务需要获取用户头像时，可调用华为账号的[头像授权能力](https://developer.huawei.com/consumer/cn/doc/atomic-guides/account-guide-atomic-get-avatar-nickname)，引导用户完成头像授权。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185807.61294274554911627912251101106934:50001231000000:2800:B07A6BC52C68C34AFB7AB23130EB4F32542D2F76441F5A125C8E6CBA58CB24E4.png "点击放大")
+
+## 获取昵称
+
+当元服务需要获取用户昵称时，可调用[智能填充服务](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/scenario-fusion-intelligent-filling)获取华为账号的昵称信息，引导用户填写华为账号昵称。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185807.70081500536747949553206260428732:50001231000000:2800:12C8625A9D4AA616FD67169C3E2E1598EE3B89151545CCFD84B3DA810DC020FF.png "点击放大")
+
+## 获取手机号
+
+当元服务需要获取用户手机号时，可调用华为账号的[手机号授权能力](https://developer.huawei.com/consumer/cn/doc/atomic-guides/account-guide-atomic-get-phone)，引导用户完成手机号授权。
+
+元服务倡导在用户意图发生时，恰当、合理向用户申请手机号权限授权，可参考如下设计：
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185807.37712741881434792964174769573827:50001231000000:2800:63663FDA751D7F6A7265D50314B7526D7513BCC6FA13307D90F4555D22B491BE.png "点击放大")
+
+不允许在用户刚刚进入元服务还未开始查看、浏览页面时，就弹出手机号授予申请。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185808.29663042395149090768502834559907:50001231000000:2800:52C9899D7049C939156E4B00797B68F8AFE054DFC54366AD83DB9F7F285EEEAE.png "点击放大")
+
+**元服务开发者可通过手机号同步用户数字资产**
+
+用户授权手机号后，开发者可通过手机号查找开发者账号下对应的用户账号，并将其与元服务登录的华为账号进行关联，进而将用户在其他平台的数字资产同步至元服务，如用户历史订单、会员等级等。
+
+开发者可以根据业务需要，对“我的”页面中的用户头像、昵称进行刷新，支持用户主动修改。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185808.27437731745479235994367764714807:50001231000000:2800:8A0A56F2442DBF032B1DB930ED9611B9D59BFB5300977232510698EAE1B89AF7.png "点击放大")
+
+## 获取收货地址
+
+当元服务需要获取用户收货地址时，可调用华为账号的[获取收货地址能力](https://developer.huawei.com/consumer/cn/doc/atomic-guides/account-guide-atomic-choose-address)，引导用户完成收货地址授权。
+
+开发者可在收货地址管理界面、收货地址编辑界面等位置，设置[选择收货地址Button](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/scenario-fusion-button-ship-to)，实现用户收货地址的快速填充和使用。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185809.53041762776679082906948601714221:50001231000000:2800:1D7B0A0A73079131796F5A4918C99C11F871726E5E0137E12101A164F9F0BCAB.png "点击放大")
+
+## 获取发票抬头
+
+当元服务需要获取用户发票抬头时，可调用华为账号的[获取发票抬头能力](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/account-select-invoice-title)，引导用户完成发票抬头授权。
+
+开发者可在发票抬头管理界面、发票抬头编辑界面等位置，设置[选择发票抬头Button](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/scenario-fusion-button-invoice-title)，实现用户发票抬头的快速填充和使用。
+
+![](https://alliance-communityfile-drcn.dbankcdn.com/FileServer/getFile/cmtyPub/011/111/111/0000000000011111111.20251125185810.19356997351966188061850963072884:50001231000000:2800:0F61CC88E4D96256538D74667A197AFC9C384E00A39555651AD075AFC10569A1.png "点击放大")
+
+#### 常见账号问题FAQ
+
+如有疑问，请参阅[常见账号问题FAQ](https://developer.huawei.com/consumer/cn/doc/atomic-faqs/faqs-common-account)以获取更多帮助。

package/data/docs/alphabetindexer-0000001956975265.md

@@ -0,0 +1,96 @@
+# 索引条
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/design-guides/alphabetindexer-0000001956975265
+> 文档标识(fileName): alphabetindexer-0000001956975265  
+> 目录(catalogName): design-guides  
+> 语言: cn  
+> 更新时间: 2026-06-12 10:17:29  
+> 导航地址: /hmos/design
+
+---
+索引条主要针对按字母顺序排序的列表进行快速定位。用于快速精确定位，如：联系人列表 (查找联系人)、天气、世界时钟 (添加城市)。开发相关描述请参考 [AlphabetIndexer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-alphabet-indexer) 文档。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7d/v3/dZUCyWvDT46pr8pYy7xpyg/zh-cn_image_0000001929672676.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=056AF7CDC4F5B6AC52367B2D08688DEC71C40F6D32AD9002D41BEA8BE52A63BA "点击放大")
+
+#### 如何使用
+
+**索引条作为快速检索类型组件，需要充分适配设备尺寸。**例如在手机竖屏情况下时，能够完整展示索引条内容；若将手机旋转成横屏显示，由于屏幕高度限制，优先显示对应的字母索引；如果字母仍然显示不全，则使用缩略的方式展示关键字母条目。索引条可以通过 [usingPopup](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-alphabet-indexer#usingpopup) 接口显示浮层窗口，用于展示索引内容的首字母，可以配置仅展示英文，或展示对应该条目下的所有同类型字母前缀，主要适用于中文场景。
+
+|  |  |
+| --- | --- |
+|  |  |
+| 纯首字母索引浮层 | 多项索引浮层 |
+
+#### 组件规则
+
+## 控件构成
+
+索引条控件主要由索引项、索引浮层和检索内容区域为主。其中索引项一般为英文字母，用来进行选择，切换对应选后会对内容区进行筛选，做到快速定位。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/hh6N9yqnTvyIBPnwFW-Dfg/zh-cn_image_0000001929832060.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=21DB577A4915675B99EF9E42F80203677C0242FE6338607089B8B08FF21F3509 "点击放大")
+
+|  |  |  |
+| --- | --- | --- |
+| 序号 | 元素名称 | 描述 |
+| 1 | 当前索引项 | 表示内容区域正显示由此索引项对应的内容 |
+| 2 | 快捷操作浮层 | 用户在索引项列表上滑动时出现，支持点击操作，如无操作显示 3 秒后自动隐藏 |
+| 3 | 索引项列表 | 展示所有可操作的索引项 |
+| 4 | 内容区域 | 跟随索引项操作变化内容显示 |
+
+## 动态布局
+
+当设备处于横屏下时，例如手机设备，或是当应用窗口处于分屏场景时，由于可展示的应用高度不够，字母索引可以以间隔方式显示字母。 通过使用 [autoCollapse](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-alphabet-indexer#autocollapse11) 接口能力可以实现动态判断。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f7/v3/jlzKVB35TI-N8yyI_n8iBQ/zh-cn_image_0000001929672680.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=BCCCEE84DE5B0C8367941FE493A6B784B0B80B677618F9C604A5397B3941AE26 "点击放大")
+
+#### 视觉规则
+
+## 沉浸光感
+
+组件已默认提供[沉浸光感](https://developer.huawei.com/consumer/cn/doc/design-guides/immersivelight-0000002612101053)样式，为页面带来更好的视觉精致度和空间感。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3/v3/d7yaPefwSgmlOf92c_bA3w/zh-cn_image_0000002584074148.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=A0E430BC3D067DD4F6EB1F2339EDB4EAC82F95B632D7560AD0F633DAFD0FF9D1 "点击放大")
+
+#### 设备差异
+
+## 手机设备
+
+|  |  |
+| --- | --- |
+|  |  |
+| 索引条的位置需要在界面中可以自由布局，通常情况下建议在界面中保持居中位置。在 HarmonyOS 应用中通常会将界面中的信号栏和底部工具栏/底部页签高度去除掉，然后居中展示。 | 若顶部的内容还包含子页签等其他组合组件，字母索引起始位置可以考虑基于顶部组件高度提供一个默认间距，固定显示。 |
+
+## 穿戴设备
+
+索引条是快速定位列表内容的操作条。用于快速精确定位，如联系人列表查找联系人。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7a/v3/81WuXnKrQ9G8j5j3vKxJ_Q/zh-cn_image_0000002347548569.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=213A4DCA385568062D06CD99BC0A6C285215103BDE96764F36F531465CEED38C "点击放大")
+
+**使用规则**
+
+- 索引条最少显示 2 个索引；当索引数在索引条上量超过 4 个时，可通过点击折叠箭头> 展开或折叠索引条。
+- 未展开状态下，用户可以在索引条上通过滑动交互和点击交互来获取精确定位。当用户手指滑动或点击至某一字母位置时，界面顶部有气泡提示当前字母，用户在非索引条区域滚动或点击时，此气泡消失；若用户没有操作，则 3.5s 后气泡自动消失。
+- 展开状态的索引条，点击或用滑动索引条，均可进行焦点选择，此时界面有气泡提示当前字母，消失规则与未展开时相同； 滑动列表中的内容或点击箭头，可将索引条折叠。
+- 展开状态的索引条弧长根据数量增长，最长可形成整圆。方形表为胶囊形。
+- 多语言情况下，整圆状态下超过 30 个字符时，可隐藏一些字符并以“.”显示，焦点处于此位置时，气泡显示被隐藏的多个字符。
+- 多语言情况下，一些语言需要切换至字母索引时，本地语言末尾有一个字母，点击或滑动可切换至字母语言；切换至字母索引时，字母索引上方有一个本地语言字符，点击或获得可切换至本地语言。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6c/v3/QSs-zinyRTSTUa8PBkJ89Q/zh-cn_image_0000002164393364.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=0F7CEF6B8B2DEB6E58BF610610DDCB78DF65E4EE8FD1172ACA7E5976A7FCCF75 "点击放大")
+
+方形表：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b1/v3/OK1MrnWOQPGLoeERuWqnbA/zh-cn_image_0000002347549749.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=DB6F923915DFCAF226FF9E9417987EAAA04309D06AEB637E7B5317E0EF1059A4 "点击放大")
+
+**视觉规则**
+
+圆形表：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/47/v3/QNDEdnjpQwW40lMY9VR6DQ/zh-cn_image_0000002164557308.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=DF586029B53286778C96D8FE66063B1BDD537C9282D389D51839B2C615D4A18A "点击放大")
+
+方形表：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3/v3/1KXIbrUyTcOd9svi7Ohb6w/zh-cn_image_0000002347711273.png?HW-CC-KV=V1&HW-CC-Date=20260623T092324Z&HW-CC-Expire=86400&HW-CC-Sign=0DEA673833B2CD89A9D8AEA33F74E7F9641DBE66A7E89E7D3C405FD1AAD680DA "点击放大")
+
+#### 开发文档
+
+[AlphabetIndexer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-alphabet-indexer)