From 54f39aa3d62c64f3847d9f05795922ebe5cd4e2e Mon Sep 17 00:00:00 2001 From: ge-yafang Date: Wed, 6 Jul 2022 16:53:26 +0800 Subject: [PATCH] update docs Signed-off-by: ge-yafang --- .../template/concept-overview-template.md | 111 ----- .../figures/how-distributedobject-works.png | Bin 0 -> 12271 bytes zh-cn/contribute/template/guide-template.md | 464 ++++++++++++++---- 3 files changed, 355 insertions(+), 220 deletions(-) delete mode 100644 zh-cn/contribute/template/concept-overview-template.md create mode 100644 zh-cn/contribute/template/figures/how-distributedobject-works.png diff --git a/zh-cn/contribute/template/concept-overview-template.md b/zh-cn/contribute/template/concept-overview-template.md deleted file mode 100644 index 9ec95b2f1a..0000000000 --- a/zh-cn/contribute/template/concept-overview-template.md +++ /dev/null @@ -1,111 +0,0 @@ -# 概述 - -## 基本概念 - -*【 **写作要求**】* - -*必选，描述本开发任务相关的基本概念，帮助开发者更好的理解开发任务。* *写作要求见下，完成写作后，请逐项自检*。 - -| 内容要求 | 是否满足 | -| -------- | -------- | -| 业界通用的概念不用赘述。 | | -| 注意使用业界通用术语来表达，不用开发者无法理解的内部语言。 | | - - -【写作样例】 - - -XX系统音频模块支持音频业务的开发，提供音频相关的功能，主要包括音频播放、音频采集、音量管理和短音播放等。 - - -在进行应用的开发前，开发者应了解以下基本概念： - - -- 采样 - 采样就是把模拟信号数字化的过程，所有的模拟信号都需要通过采样转换为可以用0101来表示的数字信号。 - -- 采样率 - 采样率为每秒从连续信号中提取并组成离散信号的采样次数，单位用赫兹（Hz）来表示。通常人耳能听到频率范围大约在20Hz～20kHz之间的声音。常用的音频采样频率有：8kHz、11.025kHz、22.05kHz、16kHz、37.8kHz、44.1kHz、48kHz、96kHz、192kHz等。 - -- 声道 - 声道是指声音在录制或播放时在不同空间位置采集或回放的相互独立的音频信号，所以声道数也就是声音录制时的音源数量或回放时相应的扬声器数量。 - -- 音频帧 - 音频数据是流式的，本身没有明确的一帧帧的概念，在实际的应用中，为了音频算法处理/传输的方便，一般约定俗成取2.5ms~60ms为单位的数据量为一帧音频。这个时间被称之为“采样时间”，其长度没有特别的标准，它是根据编解码器和具体应用的需求来决定的。 - - -## 运作机制 - -*【 **写作要求**】* - -*可选。如果机制比较简单，通过前面基本概念就可以说清楚，此章节可以不用提供，删除标题即可*。 - -*描述实现原理介绍机制，如关键步骤相关接口调用时机和触发时机，帮助开发者了解该功能的基本运作原理，以便更好的理解开发任务和定位问题*。 - -*写作要求见下，完成写作后，请逐项自检*。 - -| 内容要求 | 是否满足 | -| -------- | -------- | -| 仅描述开发任务相关的原理。 | | -| 尽量图文配合，一般使用时序图、流程图等形式。文字描述与图形描述匹配。 | | - -【写作样例-1】 - -- 信号量初始化，为配置的N个信号量申请内存（N值可以由用户自行配置，受内存限制），并把所有的信号量初始化成未使用，并加入到未使用链表中供系统使用。 - -- 信号量创建，从未使用的信号量链表中获取一个信号量资源，并设定初值。 - -- 信号量申请，若其计数器值大于0，则直接减1返回成功。否则任务阻塞，等待其它任务释放该信号量，等待的超时时间可设定。当任务被一个信号量阻塞时，将该任务挂到信号量等待任务队列的队尾。 - -- 信号量释放，若没有任务等待该信号量，则直接将计数器加1返回。否则唤醒该信号量等待任务队列上的第一个任务。 - -- 信号量删除，将正在使用的信号量置为未使用信号量，并挂回到未使用链表。 - -- 信号量允许多个任务在同一时刻访问同一资源，但会限制同一时刻访问此资源的最大任务数目。访问同一资源的任务数达到该资源的最大数量时，会阻塞其他试图获取该资源的任务，直到有任务释放该信号量。 - - -【写作样例-2】 - -**互斥锁运作原理** - -多任务环境下会存在多个任务访问同一公共资源的场景，而有些公共资源是非共享的，需要任务进行独占式处理。互斥锁怎样来避免这种冲突呢？ - -用互斥锁处理非共享资源的同步访问时，如果有任务访问该资源，则互斥锁为加锁状态。此时其他任务如果想访问这个公共资源则会被阻塞，直到互斥锁被持有该锁的任务释放后，其他任务才能重新访问该公共资源，此时互斥锁再次上锁，如此确保同一时刻只有一个任务正在访问这个公共资源，保证了公共资源操作的完整性。 - - - -## 约束与限制 - -【写作要求】 - -*必选*。 *描述本开发任务过程中* *的约束条件，以及此操作约束带来相应的负面影响，包括但不限于如下几方面*： - -- **功能限制**： - - 功能使用范围（明确不支持的场景）。 - - 规格限制。 - -* **操作限制**： - - * 已知问题的操作。 - * 潜在风险的操作（如引起性能降低）。 - * 引起性能降低的操作。 - -写作要求见下，完成写作后，请逐项自检。 - -| 内容要求 | 是否满足 | -| -------- | -------- | -| 明确功能限制或操作限制。 | | -| 约束对指导任务开发有影响或体验有感知，否则不用体现。 | | -| 容易出错的操作在步骤里描述，不在此体现。 | | - -【**写作样例**】 - -**互斥锁的约束与限制**： - -- 两个任务不能对同一把互斥锁加锁。如果某任务对已被持有的互斥锁加锁，则该任务会被挂起，直到持有该锁的任务对互斥锁解锁，才能执行对这把互斥锁的加锁操作。 - -- 互斥锁不能在中断服务程序中使用。 - -- XXX作为实时操作系统需要保证任务调度的实时性，尽量避免任务的长时间阻塞，因此在获得互斥锁之后，应该尽快释放互斥锁。 - -- 持有互斥锁的过程中，不得再调用LOS_TaskPriSet等接口更改持有互斥锁任务的优先级。 diff --git a/zh-cn/contribute/template/figures/how-distributedobject-works.png b/zh-cn/contribute/template/figures/how-distributedobject-works.png new file mode 100644 index 0000000000000000000000000000000000000000..9af60f511701f7ef7e8424492d42f247c6088b28 GIT binary patch literal 12271 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 b>6JZ-VR)Gm-LcjE0g&DmBkdxsTMzyVh0W{D literal 0 HcmV?d00001 diff --git a/zh-cn/contribute/template/guide-template.md b/zh-cn/contribute/template/guide-template.md index 2b268c09b7..9e6581f02f 100644 --- a/zh-cn/contribute/template/guide-template.md +++ b/zh-cn/contribute/template/guide-template.md @@ -1,159 +1,405 @@ -# 开发指导 +# 开发指南写作模板 -***【写作要求】*** +> **注意：** +> _1、本模板提供推荐的开发指南文档框架、典型知识点写作要求及写作指导。实际写作中，应视具体__方案/特性/功能/模块__情况，先完成开发者任务场景分析与开发指南大纲设计，然后参照本模板写作具体内容。_ +> +> _2、文档写作时，两级标题之间的位置不允许添加内容。_ +> +> _3、所有斜体为写作指导，正式文档中注意全部删除。_ -*必选*。 *描述各个场景下，开发者如何完成开发任务*。 *可根据多场景任务增加章节。写作要求见下，完成写作后，请逐项自检*。 +## xxx概述 -| 内容要求 | 是否满足 | -| -------- | -------- | -| 如果有多个场景，请写起多个“开发指导”章节，如音频播放开发指导、音量管理开发指导、短音播放开发指导。 | | -| 标题尽量使用“动词+名词”的句式表述任务操作。 | | +_必选。根据具体__方案/特性/功能/模块__的场景划分情况，此处的“xxx概述”与具体任务场景下的“任务场景n概述”按需提供一处或共存，具体的：_ +_1、此处的“xxx概述”"：用于承载开发者需要了解的、本特性各任务场景通用的概述内容。如无，则删除。_ -## 场景介绍 +_2、“任务场景n概述”：用于承载任务场景n直接相关的概述内容，知识点构成及写作要点与“xxx概述”相同，包括任务场景n简介、任务场景n直接相关的基本概念、任务场景n直接相关的实现原理、任务场景n直接相关的约束与限制、任务场景n直接相关的相关实例。如无，则删除。_ -***【写作要求】*** +**_【开发指南总体写作要求】_** -*必选*。 *描述在什么情景下解决什么问题，最终达到什么样的效果*。应用SCQA描述方法： +**_1、目标对象：_**_面向内、外部开发者（含产品经理、开发人员）。面向UX设计师的指导文档通常由专门的UX设计规范承载，不在开发指南范畴。本文如需提及，以超链接方式指向对应UX规范即可。_ -- S：situation（情景），由大家都熟悉的的情景，事实引入。 +_**2、内容定位：**介绍__方案/特性/功能/模块__是什么（What）、能做什么（Why），以及如何进行相关应用程序/设备的设计、开发、发布上架（How）。支撑开发者学习必要知识，最终在实际开发活动中完成既定任务目标。_ -- C：complication（冲突），但是实际情况往往和我们的要求有冲突。 +_**3、用户视角：**变身开发者，始终以开发者视角，提供开发者关注的、可感知和使用的内容。_ -- Q：question（疑问），怎么办？ +_**4、面向任务：**聚焦开发者实际任务，完整、正确、易用，具备权威指导性。_ -- A：answer（回答），我们的解决方案是 … +_5、不要受限：模板只是基础框架，不要僵化。_ -*写作要求见下，完成写作后，请逐项自检*。 -| 内容要求 | 是否满足 | -| -------- | -------- | -| 背景原因、什么时候在哪、做了什么操作、最终解决什么问题或操作效果都明确。 | | +### xxx简介 -【**写作样例**】 +_必选。_ -音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。 +_**【开发者关注点】**_ +_这个方案/特性/功能/模块是什么（定义-what）？我为什么要用它？它能解决哪些问题或带来哪些收益？（目的/客户价值-why）_ -## 接口说明 +_**【写作要点】**_ -*【**写作要求**】* +- _提供易理解的场景化描述。__可参考如下SCQA方式介绍方案/特性/功能/模块客户面的功能场景、特点。_ + - _S：situation（情景），由大家都熟悉的的情景、事实引入。_ + - _C：complication（冲突），但是实际情况往往和我们的要求有冲突。_ + - _Q：question（疑问），怎么办？_ + - _A：answer（回答），我们的解决方案是 …_ -*必选*。 *描述本开发指导相关的接口有哪些，旨在要开发者在开发前有大体了解，提升开发效率*。 *写作要求见下，完成写作后，请逐项自检*。 +- _抽象的概念要具象化，可以适当引入2C视角（如UX中的场景效果）的内容，帮助理解。_ -| 内容要求 | 是否满足 | -| -------- | -------- | -| 不在本开发任务的接口无需提供。 | | -| 如果接口太多，超过10个，可以提供主要的接口 | | +**_【写作要求】_** -【**写作样例**】 +- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ -音频播放开放能力如下：AudioRenderer类，具体的API详见接口文档。 +- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ -**表1** 音频播放API接口功能介绍 +- _文中使用的术语、缩略语或专有名词应全文保持一致。_ -| 接口名 | 描述 | -| -------- | -------- | -| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm) throws IllegalArgumentException | 构造函数，设置播放相关音频参数和播放模式，使用默认播放设备 | -| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm, AudioDeviceDescriptor outputDevice) throws IllegalArgumentException | 构造函数，设置播放相关音频参数、播放模式和播放设备 | -| boolean play() | 播放音频流 | -| boolean write(byte[] data, int offset, int size) | 将音频数据以byte流写入音频接收器以进行播放 | +### xxx基本概念 -## 开发步骤 +_可选。此处放置以下各任务场景通用的基本概念。_ -*【**写作要求**】* +_**【开发者关注点】**_ - *必选。描述* *开发的整体过程，便于开发者快速完成开发*。*具体写作要求见下，完成写作后，请逐项自检下*。 +_要使用该方案/特性/功能/模块，有哪些独有概念是我需要了解的？_ -| 内容要求 | 是否满足 | -| -------- | -------- | -| **如何写好步骤** | | -| 步骤完整：提供必需的步骤，顺利指导完成操作，无缺失。 | | -| 脉络清楚：文档逻辑清晰、合理。文档前面的概述、准备、操作围绕一条线描述，不能章节断裂或前后矛盾的现象。 | | -| 任务句式：标题或句子尽量使用“动词+名词”的句式表述动作。 | | -| 预防提前：操作过程中的限制、易错的、有潜在风险的，要提前描述，使用DOCS平台的“插入> 说明 > 须知”描述。 | | -| 步骤清晰-1：无论步骤简单或复杂，都需要写步骤目的，即为什么做。 | | -| 步骤清晰-2：明确在什么环境下，使用什么工具，做什么操作，怎么做该操作。 | | -| 步骤具体：如果操作可选，要明确可选条件。 | | -| 在开发步骤执行完成后，及时明确操作正确的标准。 | | -| **如何写好代码段** | | -| 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图，使用代码片段包裹。 | | -| 代码中关键段用蓝色（RGB：0.0.255）突出显示，关键步骤要有注释说明。 | | -| 代码显示符合代码缩进要求。 | | -| 步骤涉及接口调用，清晰给出接口及其使用说明或示例代码，代码来源于具体实例。 | | +**_【写作要点】_** -【**写作样例**】 +- _仅提供开发者任务中必须的概念。_ -1. 构造音频流参数的数据结构AudioStreamInfo，推荐使用AudioStreamInfo.Builder类来构造，模板如下，模板中设置的均为AudioStreamInfo.Builder类的默认值，根据音频流的具体规格来设置具体参数。 +- _运作机制、约束限制、开发过程等多个章节相关的概念在此介绍，仅某个章节用到的概念在对应章节中介绍。_ + +- _业界通用的概念不用在此赘述。__注意使用业界通用术语来表达，不用华为研发内部语言。_ + +- _概念之间如有逻辑关系，推荐使用图形描述。_ + +**_【写作要求】_** + +- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ + +- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ + +- _文中使用的术语、缩略语或专有名词应全文保持一致。_ + +**【写作样例】** + +在进行关系型数据库开发前，开发者应了解以下基本概念： + +- **关系型数据库** + +基于关系模型来管理数据的数据库，以行和列的形式存储数据。 + +- **谓词** + + 数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。 + +- **结果集** + + 指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便的拿到用户想要的数据。 + + +### 实现原理 + +_可选。此处放置以下各任务场景通用的实现原理。_ + +_**【开发者关注点】**_ + +_该方案/特性/功能/模块是如何工作的？关键步骤相关接口调用和触发时机？我要了解其原理，以更好的使用、调试它。_ + +**_【写作要点】_** + +- _如果原理简单，通过前面基本概念就可以说清楚，此章节可以不提供，删除即可。_ + +- _仅描述开发者任务（使用或接入）过程中可见的机制原理，不要提供开发者不可见的内部实现。_ + +- _尽量图文结合，一般使用时序图、流程图等形式。文字描述与图形描述匹配。_ + +- _注意不要泄密。_ + +**_【写作要求】_** + +- _清晰易懂，避免模糊、晦涩、有歧义的表述。_ + +- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_ + +- _文中使用的术语、缩略语或专有名词应全文保持一致。_ + +**【写作样例】** + +分布式数据对象生长在分布式内存数据库之上，在分布式内存数据库上进行了JS对象型的封装，能像操作本地变量一样操作分布式数据对象，数据的跨设备同步由系统自动完成。 + +**图1** 分布式数据对象运行机制 + +![how-distributedobject-works](figures/how-distributedobject-works.png) + + +### 约束与限制 + +_可选。此处放置以下各任务场景通用的约束与限制。_ + +_**【开发者关注点】**_ + +_我要__使用该方案/特性/功能/模块，有什么约束条件吗？__该方案/特性/功能/模块__实现的程度如何，能满足我的需求吗？_ + +**_【写作要点】_** + +- _描述对开发活动有影响、可感知的约束限制，及其带来的影响，包括但不限于如下几方面：_ + - **_功能限制_** + - _功能使用范围（明确不支持的场景）。_ + - _规格限制。_ + - **_操作限制_** + - _已知问题的操作。_ + - _潜在风险的操作（如引起性能降低）。_ + +- _容易出错的操作在步骤里描述，不在此体现。_ + +**【写作样例】** + +- 不同设备间只有相同bundleName的应用才能直接同步。 + +- 不建议创建过多分布式数据对象，每个分布式数据对象将占用100-150KB内存。 + +- 每个分布式数据对象大小不超过500KB。 + + +### 相关实例 + +_可选。此处放置以下各任务场景通用的相关实例。_ + +**_【开发者关注点】_** + +_有哪些Sample code、Codelabs、Demo工程可供学习、参考。_ + +**_【写作要点】_** + +_已发布的Sample code、Codelabs、Demo工程包，请在此处提供链接（一般为Gitee链接）。__注意：不允许将工程包等作为附件插入到文档中。_ + +**【写作样例】** + +针对Ability开发，有以下相关实例可供参考： + +- [Page内和Page间导航跳转](https://gitee.com/openharmony/codelabs/tree/master/Ability/PageAbility) + + +## 环境准备 + +_可选。_ + +_根据具体的开发场景分析分解情况，本节内容可按需放入“开发指导”下，作为“前提条件”或“开发准备”与具体场景的“开发步骤”就近放置。_ + +_明确如何准备开发环境（如软硬件配置要求、工具要求、设备要求等）__。_ + +_如果不涉及上述特殊要求，此章节删除。_ + + +### 环境要求 + +**_【写作要求】_** + +_明确开发环境所需要的软硬件配置，旨在要用户提前准备环境。如果软硬件内容比较多，可以再增加子标题。_ + +**【写作样例】** + +Hi3861开发板对环境配置的特有要求如下表所示。 + + **表1** Hi3861开发板对环境配置的特有要求 + +| 平台类型 | 开发工具 | 用途 | 获取途径 | +| -------- | -------- | -------- | -------- | +| Linux服务器 | SCons3.0.4+ | 编译构建工具 | 通过互联网获取 | +| Linux服务器 | build-essential | 编译依赖的基础软件包 | 通过互联网获取 | + + +### 搭建环境 + +**_【写作要求】_** + +_描述搭建开发环境的具体步骤，如果内容比较多，可以再区分章节，如：搭建编译基础环境、搭建编译工具环境等。_ + +**【写作样例】** + +1. 打开Linux编译服务器终端。 + +2. 运行如下命令，安装工具安装包。 + ``` - AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder() - .sampleRate( AudioStreamInfo.SAMPLE_RATE_UNSPECIFIED) - .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_NONE) - .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_INVALID) - .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_INVALID) - .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_UNKNOWN) - .build(); + xxxxx ``` - 以真实的播放pcm流为例： - ``` - AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate(44100)//44.1kHz - .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_MAY_DUCK)//混音 - .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_PCM_16BIT)//16-bit PCM - .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_OUT_STEREO)//双声道 - .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_MEDIA)//媒体类音频 - .build(); - ``` - -2. 使用步骤1创建的音频流构建音频播放的参数结构AudioRendererInfo，推荐使用AudioRendererInfo.Builder类来构造，模板如下，模板中设置的均为AudioRendererInfo.Builder类的默认值，根据音频播放的具体规格来设置具体参数。 +3. 运行如下命令，查看是否安装成功。 + ``` - AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder() - .audioStreamInfo(audioStreamInfo) - .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_NONE) - .bufferSizeInBytes(0) - .distributedDeviceId("") - .isOffload(false) - .sessionID(AudioRendererInfo.SESSION_ID_UNSPECIFIED) - .build(); + xxxxx ``` - 以真实的播放pcm流为例： - ``` - AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder() - .audioStreamInfo(audioStreamInfo) - .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_DIRECT_PCM)//pcm格式的输出流 - .bufferSizeInBytes(100) - .distributedDeviceId("E54***5E8")//使用分布式设备E54***5E8播放 - .isOffload(false)//false表示分段传输buffer并播放，true表示整个音频流一次性传输到HAL层播放 - .build(); - ``` - -3. 根据要播放音频流指定PlayMode，不同的PlayMode在写数据时存在差异，详情见步骤7，其余播放流程是无区别的。并通过构造函数获取AudioRenderer类的实例化对象。 + +### 检验环境是否搭建成功 + +**_【写作要求】_** + +_可选。环境搭建完成后，需要明确给出环境搭建是否成功的检验标准，也可以与搭建步骤合一。如上述写作样例。_ + + +## 任务场景n（使用具体任务/场景名称替代，只有1个场景时使用特性名称xxx）开发指导 + +_必选。_ + +_**【开发者关注点】**_ + +_我要使用/接入这个方案/特性/功能/模块，需要怎么做（how）？_ + +_**【写作要点】**_ + +_贴近开发者实际开发场景：_ + +- _开发者需要通过哪些任务来达成开发目标，这就是任务场景。_ + +- _任务场景可以有1个或多个，__可按需添加多个“开发指导”章节。__同时要遵循分层分级逻辑，即大场景（任务场景n）->小场景（子任务场景n-x）->任务逻辑（对应“开发流程”）->操作步骤（一个个step）。_ + +### 任务场景n概述 + +_根据具体特性的场景划分情况，“任务场景n概述”与开篇的“xxx概述”按需提供一处或共存，具体的：_ + +_1、开篇的“xxx概述”"：用于承载开发者需要了解的、本特性各任务场景通用的概述内容。如无，则删除。_ + +_2、“任务场景n概述”：用于承载任务场景n直接相关的概述内容，知识点构成及写作要点与开篇的“xxx概述”相同，包括任务场景n简介、任务场景n直接相关的基本概念、任务场景n直接相关的实现原理、任务场景n直接相关的约束与限制、任务场景n直接相关的相关实例。如无，则删除。_ + +### 开发流程 + +**_【写作要点】_** + +- _可选。当开发步骤较多（达到5步及以上核心操作）或步骤间存在复杂的逻辑关系时，请提供开发流程，让开发者对他要执行的操作有一个全景认知。_ + +- _一般使用流程图、表。_ + + +### 接口说明 + +**_【写作要求】_** + +- _可选。描述以下开发步骤中有哪些关键接口，并提供接口简介。旨在要开发者在开发前有大体了解，提升开发效率。_ + +- _如果相关接口超过10个，只提供主要接口即可_。 + +- _接口及其涉及的功能必须在文档发布时的对应版本已支持。_ + +**【写作样例】** + +部分接口仅系统应用才可以调用，且需要具备权限：SystemCapability.Notification.Notification ，接口返回值有两种返回形式：callback和promise，下表中为callback形式接口，promise和callback只是返回值方式不一样，功能相同。具体API说明详见[接口文档](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-notification.md)。 + +**表1** 通知使能开关接口功能介绍 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ---------------- | +| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback\): void | 查询通知使能开关 | +| enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback\): void | 设置使能开关 | + + +### 开发步骤 + +**_【写作要求】_** + +_必选。_ + +- _完整性、正确性要求_ + - _描述开发的完整过程，使开发者能够完整（如HAP中代码、资源、第三方库及应用配置文件都涉及哪些相关步骤）、正确的完成开发，不可遗漏关键配置操作。_ + - _文档中的片段示例代码直接拷贝进DevEco Studio中，放入上下文可以正常编译。_ + - _文档中的完整示例代码直接拷贝进DevEco Studio中能够运行，并和文档中描述的执行结果一致。_ + +- _清晰性要求_ + - _每个步骤有清晰的执行主体（who），明确操作目的（why）、操作内容（what/how）、场景（when/where）。使用祈使句描述步骤。_ + - _步骤中如果涉及接口调用，需要清晰给出使用的接口及其使用说明、示例代码。_ + - _关键步骤和示例代码中有开发建议或注意事项的位置，需要提供相关描述（示例代码中采用注释）。_ + 变身开发者，假想自己在操作，可能会提出什么问题？这些问题就是开发者的障碍。需要在文档中提供支撑信息，来帮助开发者处理及应对这些障碍。例如： + - 分支选取原则：步骤分支选取原则、参数选取原则或建议。 + + - 必要的随操作步骤就近放置的补充说明：可能存在的特殊操作、操作权限要求、效率提升技巧、几句话即可说清的背景知识等。 + + - 需要事先告知用户并提醒注意的信息：对其他功能可能造成影响的操作；对系统性能、可靠性可能造成影响的操作；可能导致数据丢失或各类安全问题的操作。这些信息需要在“操作步骤”开始前，以区别于正文的样式加以提示强调。 + + - 防错/纠错信息：针对开发全流程中可能遇到的典型问题，提供预防、定位或恢复指导，以提高开发效率。防错/纠错信息可酌情在“开发步骤”或下文的“常见问题”中承载。 + +- _规范性要求_ + - _保证示例代码的逻辑/语法正确性、书写规范性。涉及用户手机号码、身份证、帐号名等敏感信息均需要打码处理，如186\*\*\*\*\*\*\*\*；涉及IP地址、域名等，需要使用私网IP或相应格式代替，如xx.xx.xx.xx、www.example.com，禁止使用真实IP地址、域名。_ + - _代码显示符合代码缩进要求。缩进不要用tab键，改为4个空格，否则上网格式错乱。_ + +**【写作样例-节选】** + +1. 导入相关模块。 + + ```javascript + import formBindingData from '@ohos.application.formBindingData' + import formInfo from '@ohos.application.formInfo' + import formProvider from '@ohos.application.formProvider' + ``` -4. 播放任务结束后，调用AudioRenderer实例化对象的release()释放资源。 +2. 实现LifecycleForm生命周期接口。 + + ```javascript + export default { + onCreate(want) { + console.log('FormAbility onCreate'); + // 由开发人员自行实现，将创建的卡片信息持久化，以便在下次获取/更新该卡片实例时进行使用 + let obj = { + "title": "titleOnCreate", + "detail": "detailOnCreate" + }; + let formData = formBindingData.createFormBindingData(obj); + return formData; + }, + onCastToNormal(formId) { + // 使用方将临时卡片转换为常态卡片触发，提供方需要做相应的处理 + console.log('FormAbility onCastToNormal'); + }, + } + ``` + + +### 调测验证 + +**_【写作要求】_** + +- _可选。开发完成后，如有独立的调测验证操作，需提供指导，以确认操作是否成功。操作步骤要求同“开发步骤”。_ + +- _此处仅提供最后的业务调测，每个小任务的操作结果，推荐在开发步骤执行完成后及时验证。_ + + +## 常见问题 + +_可选。_ + +**_【开发者关注点】_** + +_该方案/特性/功能/模块开发全流程中可能遇到哪些典型问题？如何定位、解决？_ + +**_【写作要点】_** + +_描述开发过程遇到的各类问题以及解决方案，以提高开发效率。_ + +- _如果无常见问题，删除此章节。_ + +- _如果有常见问题，建议单独章节，后续具备扩展性。_ + +- _如果有常见问题，问题少于1屏且未来扩充可能性不大，可放在“开发指导”。_ + +### 1.XX问题（简单问题） -## 调测验证（可选） +XXX -*【**写作要求**】* -*可选*。 *描述开发完成后，进行调测验证，确保最终操作成功*。*操作步骤要求同“开发指导”，其他具体写作要求见下，完成写作后，请逐项自检下*。 +### 2.XX问题（复杂问题） -| 内容要求 | 是否满足 | -| -------- | -------- | -| 仅进行最后的业务调测，每个小任务的操作结果，在开发步骤执行完成后，及时验证操作结果。 | | -| 明确开发成功标准。 | | +**现象描述** -## 开发实例 -*【**写作要求**】* +XXX -*提供完整的sample示例，同时简要描述示例原理和实现，并链接到源码仓*。 +**可能原因** -针对xxx开发，有以下示例工程可供参考： +XXX -- xxx（此处请提供源码超链接） +**解决办法** - 本示例xxxx。 +XXX -- GitLab