1# 开发指南写作模板 2 3### 修订记录 4| 修改描述 | 日期 | 5| ----------------------------------------------------------------------- | ------------ | 6| 增加Kit模拟器支持情况的写作要求。 | 2025/07 | 7| 开发指南按照Kit粒度提供，本模板相应刷新。 | 2024/03 | 8 9 10 11> **注意：** 12> 13> _1、本模板提供推荐的开发指南文档框架、典型知识点写作要求及写作指导。实际写作中，应视具体**Kit/方案/特性/功能/模块**情况，先完成开发者任务场景分析与开发指南大纲设计，然后参照本模板写作具体内容。_ 14> 15> _2、文档写作时，一级标题与二级标题之间的位置不允许添加内容。_ 16> 17> _3、所有斜体为写作指导，正式文档中注意全部删除。_ 18 19 20**_【开发指南总体写作要求】_** 21 22**_1、目标对象：_**_面向内、外部开发者（含产品经理、开发人员）。面向UX设计师的指导文档通常由专门的UX设计规范承载，不在开发指南范畴。本文如需提及，以超链接方式指向对应UX规范即可。_ 23 24**_2、内容定位：_**_介绍**Kit/方案/特性/功能/模块**是什么（What）、能做什么（Why），以及如何进行相关应用程序/设备的设计、开发、发布上架（How）。支撑开发者学习必要知识，最终在实际开发活动中完成既定任务目标。_ 25 26**_3、用户视角：_**_变身开发者，始终以开发者视角，提供开发者关注的、可感知和使用的内容。_ 27 28**_4、面向任务：_**_聚焦开发者实际任务，完整、正确、易用，具备权威指导性。_ 29 30**_5、不要受限：_**_模板只是基础框架，不要僵化。_ 31 32**_6、关于仅面向系统应用开放的内容：_**_对于仅面向系统应用开放的内容，在概念、原理、开发场景等各处，均建议做topic级隔离，即独立md承载，且标题显性标识“仅对系统应用开放”。_ 33 34 35## xxx（使用具体Kit/方案/特性/功能/模块名称替代）简介 36 37_必选。开篇先阐明what、why、when基础信息，让开发者对Kit/方案/特性/功能/模块有初步认知。_ 38 39_**【开发者关注点】**_ 40 41_这个Kit/方案/特性/功能/模块是什么（定义-what）？我为什么要用它？它能解决哪些问题或带来哪些收益？（目的/客户价值-why）_ 42 43_**【写作要点】**_ 44 45- _提供易理解的场景化描述。_ _可参考如下SCQA方式介绍Kit/方案/特性/功能/模块客户面的功能场景、特点。_ 46 - _S：situation（情景），由大家都熟悉的的情景、事实引入。_ 47 - _C：complication（冲突），但是实际情况往往和我们的要求有冲突。_ 48 - _Q：question（疑问），怎么办？_ 49 - _A：answer（回答），我们的解决方案是 …_ 50 51- _抽象的概念要具象化，可以适当引入2C视角（如UX中的场景效果）的内容，帮助理解。_ 52 53**_【写作要求】_** 54 55- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ 56 57- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ 58 59- _文中使用的术语、缩略语或专有名词应全文保持一致。_ 60 61**【写作样例】** 62 63Form Kit（卡片开发服务）提供一种界面展示形式，可以将应用的重要信息或操作前置到服务卡片（以下简称“卡片”），以达到服务直达、减少跳转层级的体验效果。卡片常用于嵌入到其他应用（当前被嵌入方即卡片使用方只支持系统应用，例如桌面）中作为其界面显示的一部分，并支持拉起页面、发送消息等基础的交互能力。 64 65### 能力范围 66 67_可选。介绍Kit/方案/特性/功能/模块关键开放能力，支撑选型。_ 68 69_**【开发者关注点】**_ 70 71_该Kit/方案/特性/功能/模块提供了哪些关键开放能力？我要不要使用它？_ 72 73**_【写作要点】_** 74 75- _一般不必穷举，概括描述关键开放能力即可。_ 76 77**_【写作要求】_** 78 79- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ 80 81- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ 82 83- _文中使用的术语、缩略语或专有名词应全文保持一致。_ 84 85**【写作样例】** 86 87- 音频编码：音频类应用（比如音频通话，音频录制等）可以将未压缩的音频数据送到音频编码器进行编码，应用可以设置编码要用到的编码格式，码率，采样率等参数，控制编码的输出，达到压缩音频文件的目的。 88- 视频编码：视频类应用（比如视频通话，视频录制等）可以将未压缩的视频数据送到视频编码器进行编码，应用可以设置编码要用到的编码格式，码率，帧率等参数，控制编码的输出，达到压缩视频文件的目的。 89 90### 亮点特征 91 92_可选。介绍Kit/方案/特性/功能/模块相对业界类似能力的亮点、优势，支撑选型。_ 93 94_**【开发者关注点】**_ 95 96_该Kit/方案/特性/功能/模块有哪些优势？我要不要选择它？_ 97 98**_【写作要点】_** 99 100- _提供有吸引力的亮点、优势，避免言之无物的广告语。如无明显亮点，可以不提供。_ 101 102**_【写作要求】_** 103 104- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ 105 106- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ 107 108- _文中使用的术语、缩略语或专有名词应全文保持一致。_ 109 110**【写作样例】** 111 112- 低时延播放 113 114提供统一音频低时延/非低时延播放能力接口，通过垂直打通硬件，达成最低的音频输出时延。在游戏、提示/告警音、K歌等场景下，可以通过低时延接口，实现音频快速流畅播放。 115 116- 低功耗播放 117 118针对应用播放音乐、听书类长时间音频播放场景，为确保更佳续航体验，在亮/灭屏播放时采用差异化音频缓冲区处理机制，减少CPU被唤醒的频率来降低音频播放功耗。 119 120### 基本概念 121 122_可选。此处放置以下各任务场景通用的基本概念。_ 123 124_**【开发者关注点】**_ 125 126_要使用该Kit/方案/特性/功能/模块，有哪些独有概念是我需要了解的？_ 127 128**_【写作要点】_** 129 130- _仅提供开发者任务中必须的概念。_ 131 132- _运作机制、约束限制、开发过程等多个章节相关的概念在此介绍，仅某个章节用到的概念在对应章节中介绍。_ 133 134- _业界通用的概念不用在此赘述。_ _注意使用业界通用术语来表达，不用华为研发内部语言。_ 135 136- _概念之间如有逻辑关系，推荐使用图形描述。_ 137 138**_【写作要求】_** 139 140- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ 141 142- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ 143 144- _文中使用的术语、缩略语或专有名词应全文保持一致。_ 145 146**【写作样例】** 147 148在进行关系型数据库开发前，开发者应了解以下基本概念： 149 150- **关系型数据库** 151 152基于关系模型来管理数据的数据库，以行和列的形式存储数据。 153 154- **谓词** 155 156 数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。 157 158- **结果集** 159 160 指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便的拿到用户想要的数据。 161 162 163### 实现原理 164 165_可选。此处放置以下各任务场景通用的实现原理。_ 166 167_**【开发者关注点】**_ 168 169_该Kit/方案/特性/功能/模块是如何工作的？关键步骤相关接口调用和触发时机？我要了解其原理，以更好的使用、调试它。_ 170 171**_【写作要点】_** 172 173- _如果原理简单，通过前面基本概念就可以说清楚，此章节可以不提供，删除即可。_ 174 175- _仅描述开发者任务（使用或接入）过程中可见的机制原理，不要提供开发者不可见的内部实现。_ 176 177- _尽量图文结合，一般使用时序图、流程图等形式。文字描述与图形描述匹配。_ 178 179- _注意不要泄密。_ 180 181**_【写作要求】_** 182 183- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ 184 185- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ 186 187- _文中使用的术语、缩略语或专有名词应全文保持一致。_ 188 189**【写作样例】** 190 191分布式数据对象生长在分布式内存数据库之上，在分布式内存数据库上进行了JS对象型的封装，能像操作本地变量一样操作分布式数据对象，数据的跨设备同步由系统自动完成。 192 193**图1** 分布式数据对象运行机制 194 195 196 197### 约束与限制 198 199_可选。此处放置以下各任务场景通用的约束与限制。_ 200 201_**【开发者关注点】**_ 202 203_我要使用该Kit/方案/特性/功能/模块，有什么约束条件吗？该Kit/方案/特性/功能/模块实现的程度如何，能满足我的需求吗？_ 204 205**_【写作要点】_** 206 207- _描述对开发活动有影响、可感知的约束限制，及其带来的影响，包括但不限于如下几方面：_ 208 - **_功能限制_** 209 - _功能使用范围（明确不支持的场景）。_ 210 - _规格限制。_ 211 - **_操作限制_** 212 - _已知问题的操作。_ 213 - _潜在风险的操作（如引起性能降低）。_ 214 215- _容易出错的操作在步骤里描述，不在此体现。_ 216 217**【写作样例】** 218 219#### 设备限制 220 221XXX（正式对外宣称的设备品类名，如2in1）设备暂不支持使用本Kit。 or 本Kit仅适用于（正式对外宣称的设备品类名，如2in1）设备。 or XXXXXX及以上版本的XXX设备才可使用本Kit。 222 223#### 模拟器支持情况 224_根据Kit的实际模拟器支持情况，选择如下固定句式写作。第1个适用于完全不支持模拟器的Kit；第2个适用于完全支持模拟器的Kit；第3个适用于部分支持模拟器的Kit。 225注意：对于OpenHarmony各Kit，本Section加替换标签。国内海外差异处理方式待定。_ 226 227- 本Kit暂不支持模拟器。 228 229- 本Kit支持模拟器开发。 230 231- 本Kit支持模拟器开发，但与真机存在部分能力差异，详情请参见“模拟器与真机的差异（链接到IDE的对应页面中尽量精准的section）”。 232 233#### 规格限制 234 235- 不同设备间只有相同bundleName的应用才能直接同步。 236 237- 不建议创建过多分布式数据对象，每个分布式数据对象将占用100-150KB内存。 238 239- 每个分布式数据对象大小不超过500KB。 240 241### 与相关Kit/方案/特性/功能/模块的关系（按实际主题写作） 242 243_可选。有些Kit/方案/特性/功能/模块涉及联合使用或相互依赖，有些存在相似/相关场景等，在此处明确相互关系。_ 244 245**【写作样例】** 246 247关键资产存储服务仅提供短敏感数据（不超过1KB）的安全存储能力，如业务希望对超长的数据提供保护时，请考虑使用通用密钥库系统或加解密算法库框架保护您的数据。 248 249### 相关实例 250 251_可选。此处放置以下各任务场景通用的相关实例。_ 252 253**_【开发者关注点】_** 254 255_有哪些Sample code、Codelabs、Demo工程可供学习、参考。_ 256 257**_【写作要点】_** 258 259_已发布的Sample code、Codelabs、Demo工程包，请在此处提供链接（一般为Gitee链接）。_ _注意：不允许将工程包等作为附件插入到文档中。_ 260 261**【写作样例】** 262 263针对Ability开发，有以下相关实例可供参考： 264 265- [UIAbility内和UIAbility间页面的跳转（ArkTS）](https://gitee.com/openharmony/codelabs/tree/master/Ability/StageAbility) 266 267 268## 环境准备 269 270_可选。_ 271 272_根据具体的开发场景分析分解情况，本节内容可按需放入“开发指导”下，作为“前提条件”或“开发准备”与具体场景的“开发步骤”就近放置。_ 273 274_明确如何准备开发环境（如软硬件配置要求、工具要求、设备要求等）。_ 275 276_如果不涉及上述特殊要求，此章节删除。_ 277 278 279### 环境要求 280 281**_【写作要求】_** 282 283_明确开发环境所需要的软硬件配置，旨在要用户提前准备环境。如果软硬件内容比较多，可以再增加子标题。_ 284 285**【写作样例】** 286 287Hi3861开发板对环境配置的特有要求如下表所示。 288 289 **表1** Hi3861开发板对环境配置的特有要求 290 291| 平台类型 | 开发工具 | 用途 | 获取途径 | 292| -------- | -------- | -------- | -------- | 293| Linux服务器 | SCons3.0.4+ | 编译构建工具 | 通过互联网获取 | 294| Linux服务器 | build-essential | 编译依赖的基础软件包 | 通过互联网获取 | 295 296 297### 搭建环境 298 299**_【写作要求】_** 300 301_描述搭建开发环境的具体步骤，如果内容比较多，可以再区分章节，如：搭建编译基础环境、搭建编译工具环境等。_ 302 303**【写作样例】** 304 3051. 打开Linux编译服务器终端。 306 3072. 运行如下命令，安装工具安装包。 308 309 ``` 310 xxxxx 311 ``` 312 3133. 运行如下命令，查看是否安装成功。 314 315 ``` 316 xxxxx 317 ``` 318 319 320### 检验环境是否搭建成功 321 322**_【写作要求】_** 323 324_环境搭建完成后，需要明确给出环境搭建是否成功的检验标准，也可以与搭建步骤合一。如上述写作样例。_ 325 326 327## xxx开发概述 328 329_可选。_ 330 331- _当Kit/方案/特性/功能/模块的任务场景、场景间关系不是显性呈现的信息，且这些信息不适合直接放入开篇“xxx 简介”时，需要提供本节，用于承载：任务场景概况（任务场景划分维度等）、场景间关系介绍（何时选择各场景）等。_ 332 333- _如果开发场景相对简单，可以不提供本节，在“xxx 简介”中酌情简述即可。_ 334 335 336## 任务场景n（使用具体任务/场景名称替代，只有1个场景时使用特性名称xxx）开发指导 337 338_必选。_ 339 340_**【开发者关注点】**_ 341 342_我要使用/接入这个Kit/方案/特性/功能/模块，需要怎么做（how）？_ 343 344_**【写作要点】**_ 345 346_贴近开发者实际开发场景：_ 347 348- _开发者需要通过哪些任务来达成开发目标，这就是任务场景。_ 349 350- _任务场景可以有1个或多个，可按需添加多个“开发指导”章节。同时要遵循分层分级逻辑，即大场景（任务场景n）->小场景（子任务场景n-x）->任务逻辑（对应“开发流程”）->操作步骤（一个个step）。_ 351 352### 任务场景n概述 353 354_可选。_ 355 356_用于承载任务场景n直接相关的概述内容，例如任务场景介绍、开发思路、选型建议以及本级任务场景相关的概念、原理、约束限制等。概念、原理等同类知识点写作要求请参考开篇的“xxx 简介”。如无，则删除。_ 357 358### 开发流程 359 360**_【写作要点】_** 361 362- _可选。当开发步骤较多（达到5步及以上核心操作）或步骤间存在复杂的逻辑关系时，请提供开发流程，让开发者对他要执行的操作有一个全景认知。_ 363 364- _一般使用流程图、表。_ 365 366 367### 接口说明 368 369**_【写作要求】_** 370 371- _可选。描述以下开发步骤中有哪些关键接口，并提供接口简介。旨在要开发者在开发前有大体了解，提升开发效率。_ 372 373- _如果相关接口超过10个，只提供主要接口即可_。 374 375- _接口及其涉及的功能必须在文档发布时的对应版本已支持。_ 376 377**【写作样例】** 378 379通知关键接口如下表所示。具体API说明详见API参考(这里提供到相应API参考节点的链接)。 380 381**表1** 通知使能开关接口功能介绍 382 383| 接口名 | 描述 | 384| ------------------------------------------------------------ | ---------------- | 385| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback\<boolean>): void | 查询通知使能开关 | 386| enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback\<void>): void | 设置使能开关 | 387 388 389### 开发步骤 390 391**_【写作要求】_** 392 393_必选。_ 394 395- _完整性、正确性要求_ 396 - _描述开发的完整过程，使开发者能够完整（如HAP中代码、资源、第三方库及应用配置文件都涉及哪些相关步骤）、正确的完成开发，不可遗漏关键配置操作。_ 397 - _文档中的片段示例代码直接拷贝进DevEco Studio中，放入上下文可以正常编译。_ 398 - _文档中的完整示例代码直接拷贝进DevEco Studio中能够运行，并和文档中描述的执行结果一致。_ 399 400- _清晰性要求_ 401 - _每个步骤有清晰的执行主体（who），明确操作目的（why）、操作内容（what/how）、场景（when/where）。使用祈使句描述步骤。_ 402 - _步骤中如果涉及接口调用，需要清晰给出使用的接口及其使用说明、示例代码。_ 403 - _关键步骤和示例代码中有开发建议或注意事项的位置，需要提供相关描述（示例代码中采用注释）。_ 404 变身开发者，假想自己在操作，可能会提出什么问题？这些问题就是开发者的障碍。需要在文档中提供支撑信息，来帮助开发者处理及应对这些障碍。例如： 405 - 分支选取原则：步骤分支选取原则、参数选取原则或建议。 406 407 - 必要的随操作步骤就近放置的补充说明：可能存在的特殊操作、操作权限要求、效率提升技巧、几句话即可说清的背景知识等。 408 409 - 需要事先告知用户并提醒注意的信息：对其他功能可能造成影响的操作；对系统性能、可靠性可能造成影响的操作；可能导致数据丢失或各类安全问题的操作。这些信息需要在“操作步骤”开始前，以区别于正文的样式加以提示强调。 410 411 - 防错/纠错信息：针对开发全流程中可能遇到的典型问题，提供预防、定位或恢复指导，以提高开发效率。防错/纠错信息可酌情在“开发步骤”或下文的“常见问题”中承载。 412 413- _规范性要求_ 414 - _保证示例代码的逻辑/语法正确性、书写规范性。涉及用户手机号码、身份证、帐号名等敏感信息均需要打码处理，如186\*\*\*\*\*\*\*\*；涉及IP地址、域名等，需要使用私网IP或相应格式代替，如xx.xx.xx.xx、www.example.com，禁止使用真实IP地址、域名。_ 415 - _代码显示符合代码缩进要求。缩进不要用tab键，改为4个空格，否则上网格式错乱。_ 416 417**【写作样例-节选】** 418 4191. 导入PhotoPicker模块文件。 420 421 ```javascript 422 import { 423 PhotoPickerComponent, 424 PickerController, 425 … 426 } from '@kit.MediaLibraryKit'; 427 import { photoAccessHelper } from '@ohos.file.PhotoPickerComponent'; 428 ``` 429 4302. 创建Picker组件配置选项实例（PickerOptions）和控制实例（PickerController）。 431 通过PickerOptions，开发者可配置Picker宫格的样式（如勾选框背景色、文本颜色等）、滑动预览方向、最大选择数量等参数。 432 通过PickerController，应用可向Picker组件发送数据。 433 434 ```javascript 435 // 组件初始化时设置参数信息 436 pickerOptions: PickerOptions = new PickerOptions(); 437 438 // 组件初始化完成后，可控制组件部分行为 439 @State pickerController: PickerController = new PickerController(); 440 ``` 441 442 443### 调测验证 444 445**_【写作要求】_** 446 447- _可选。开发完成后，如有独立的调测验证操作，需提供指导，以确认操作是否成功。操作步骤要求同“开发步骤”。_ 448 449- _此处仅提供最后的业务调测，每个小任务的操作结果，推荐在开发步骤执行完成后及时验证。_ 450 451 452## 常见问题 453 454_可选。_ 455 456**_【开发者关注点】_** 457 458_该Kit/方案/特性/功能/模块开发全流程中可能遇到哪些典型问题？如何定位、解决？_ 459 460**_【写作要点】_** 461 462_描述开发过程遇到的各类问题以及解决方案，以提高开发效率。_ 463 464- _如果无常见问题，删除此章节。_ 465 466- _各任务场景通用的常见问题，建议以单独章节呈现；单个任务场景相关的常见问题，放在对应任务场景的章节下即可。_ 467 468 469 470### 1.XX问题 471 472具体写作模板请参见[《FAQ模板》](https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/template/faq-template.md)。 473 474
