!5563 【轻量级 PR】：【OpenHarmony开源贡献者计划2022】update zh-cn/application-dev/IDL/idl-guidelines.md.

Merge pull request !5563 from Mr_YX/N/A

zh-cn/application-dev/IDL/idl-guidelines.md

@@ -7,7 +7,7 @@
 
 ![IDL-interface-description](./figures/IDL-interface-description.png)
 
-OpenHarmony  IDL接口描述语言主要用于：
+OpenHarmony IDL接口描述语言主要用于：
 
 - 声明系统服务对外提供的服务接口，根据接口声明在编译时生成跨进程调用（IPC）或跨设备调用（RPC）的代理（Proxy）和桩（Stub）的C/C++代码或JS/TS代码。
 
@@ -29,16 +29,16 @@ OpenHarmony  IDL接口描述语言主要用于：
 
 #### 2.1.1 基础数据类型
 | IDL基本数据类型 | C++基本数据类型 | TS基本数据类型 |
-|   --------      |  --------      | --------    |
-|void             | void           | void |
-|boolean          | bool           | boolean |
-|byte             | int8_t         | number |
-|short            | int16_t        | number |
-|int              | int32_t        | number |
-|long             | int64_t        | number |
-|float            | float          | number |
-|double           | double         | number |
-|String           | std::string    | string |
+|   --------    |  --------     | --------     |
+|void           | void          | void         |
+|boolean        | bool          | boolean      |
+|byte           | int8_t        | number       |
+|short          | int16_t       | number       |
+|int            | int32_t       | number       |
+|long           | int64_t       | number       |
+|float          | float         | number       |
+|double         | double        | number       |
+|String         | std::string   | string       |
 
 IDL支持的基本数据类型及其映射到C++、TS上的数据类型的对应关系如上表所示。
 
@@ -47,29 +47,34 @@ sequenceable数据类型是指使用“sequenceable”关键字声明的数据
 
 在C++中sequenceable数据类型的声明放在文件的头部，以“sequenceable includedir..namespace.typename”的形式声明。具体而言。声明可以有如下三个形式：
 
-```
+```cpp
 sequenceable includedir..namespace.typename
 sequenceable includedir...typename
 sequenceable namespace.typename
 ```
+
 其中，includedir表示该数据类型头文件所在目录，includedir中以“.”作为分隔符。namespace表示该数据类型所在命名空间，namespace中同样以“.”作为分隔符。typename表示数据类型，数据类型中不能包含非英文字符类型的其他符号。includedir与namespace之间通过“..”分割，如果类型声明的表达式中不包含“..”,除去最后一个typename之外的字符都会被解析为命名空间。例如：
-```
+
+```cpp
 sequenceable a.b..C.D
 ```
+
 上述声明在生成的的C++头文件中将被解析为如下代码：
-```
+
+```cpp
 #include  “a/b/d.h”
 using C::D;
 ```
+
 TS声明放在文件的头部，以 “sequenceable namespace.typename;”的形式声明。具体而言，声明可以有如下形式：
 
-```
+```ts
 sequenceable idl.MySequenceable
 ```
 
 其中，namespace是该类型所属的命名空间，typename是类型名。MySequenceable类型表示可以通过Parcel进行跨进程传递。sequenceable数据类型并不在OpenHarmony IDL文件中定义，而是定义在.ts文件中。因此，OpenHarmony IDL工具将根据声明在生成的.ts代码文件中加入如下语句：
 
-```
+```ts
 import MySequenceable from "./my_sequenceable"
 ```
 
@@ -80,19 +85,19 @@ import MySequenceable from "./my_sequenceable"
 
 C++中声明的形式与sequenceable类型相似，具体而言可以有如下形式：
 
-```
+```cpp
 interface includedir..namespace.typename
 ```
 
 TS中声明的形式，具体而言可以有如下形式：
 
-```
+```ts
 interface namespace.interfacename
 ```
 
 其中，namespace是该接口所属的命名空间，interfacename是接口名。例如：“interface OHOS.IIdlTestObserver;”声明了在其他OpenHarmony IDL文件定义的IIdlTestObserver接口，该接口可以作为当前定义中方法的参数类型或返回值类型使用。OpenHarmony IDL工具将根据该声明在生成的TS代码文件中加入如下语句：
 
-```
+```ts
 import IIdlTestObserver from "./i_idl_test_observer"
 ```
 
@@ -100,9 +105,9 @@ import IIdlTestObserver from "./i_idl_test_observer"
 数组类型使用“T[]”表示，其中T可以是基本数据类型、sequenceable数据类型、interface类型和数组类型。该类型在C++生成代码中将被生成为std::vector<T>类型。
 OpenHarmony IDL数组数据类型与TS数据类型、C++数据类型的对应关系如下表所示：
 
-|OpenHarmony IDL数据类型  | C++数据类型       | TS数据类型     |
-|   --------             |  --------        |  --------        |
-|T[]                     | std::vector<T>   | T[] |
+|OpenHarmony IDL数据类型  | C++数据类型           | TS数据类型     |
+|   -------              |  --------            |  --------    |
+|T[]                     | std::vector<T> | T[]          |
 
 #### 2.1.5 容器类型
 IDL支持两种容器类型，即List和Map。其中List类型容器的用法为List&lt;T&gt;;Map容器的用法为Map<KT,VT>,其中T、KT、VT为基本数据类型、sequenceable类型、interface类型、数组类型或容器类型。
@@ -114,26 +119,32 @@ List类型在TS代码中不支持,Map容器被映射为Map。
 OpenHarmony IDL容器数据类型与Ts数据类型、C++数据类型的对应关系如下表所示：
 
 |OpenHarmony IDL数据类型  | C++数据类型       | TS数据类型     |
-|   --------             |  --------        |  --------        |
-|List&lt;T&gt;                 | std::list        | 不支持 |
-|Map<KT,VT>              | std::map         | Map |
+|   --------             |  --------        |  -------     |
+|List&lt;T&gt;           | std::list        | 不支持        |
+|Map<KT,VT>              | std::map         | Map          |
 
 
 ### 2.2 IDL文件编写规范
 一个idl文件只能定义一个interface类型，且该interface名称必须和文件名相同。idl文件的接口定义使用BNF范式描述，其基本定义的形式如下：
+
 ```
 [<*interface_attr_declaration*>]interface<*interface_name_with_namespace*>{<*method_declaration*>}
 ```
+
 其中，<*interface_attr_declaration*>表示接口属性声明。当前仅支持“oneway”属性，表示该接口中的接口都是单向方法，即调用方法后不用等待该方法执行即可返回。这个属性为可选项，如果未声明该属性，则默认为同步调用方法。接口名需要包含完整的接口头文件目录及命名空间，且必须包含方法声明，不允许出现空接口。
 接口内的方法声明形式为：
+
 ```
 [<*method_attr_declaration*>]<*result_type*><*method_declaration*>
 ```
+
 其中，<*method_attr_declaration*>表示接口属性说明。当前仅支持“oneway”属性，表示该方法为单向方法，即调用方法后不用等待该方法执行即可返回。这个属性为可选项，如果未声明该属性，则默认为同步调用方法。<*result_type*>为返回值类型，<*method_declaration*>是方法名和各个参数声明。
 参数声明的形式为：
+
 ```
 [<*formal_param_attr*>]<*type*><*identifier*>
 ```
+
 其中<*formal_param_attr*>的值为“in”，“out”，“inout”,分别表示该参数是输入参数，输出参数或输入输出参数。需要注意的是，如果一个方法被声明为oneway，则该方法不允许有输出类型的参数（及输入输出类型）和返回值。
 
 ## 3.开发步骤
@@ -144,20 +155,20 @@ OpenHarmony IDL容器数据类型与Ts数据类型、C++数据类型的对应关
 
  开发者可以使用C++编程语言构建.idl文件。.idl示例如下： 
 
-```
+```cpp
   interface OHOS.IIdlTestService {
       int TestIntTransaction([in] int data);
       void TestStringTransaction([in] String data);
   }
 ```
 
-使用者通过执行命令 “./idl -gen-cpp -d dir -c dir/iTest.idl” （-d为输出目录）在执行环境的dir目录中生成接口文件、Stub文件、Proxy文件。生成的接口类文件名称和.idl文件名称保持一致，区别在于其使用.h和.cpp扩展名。例如，IIdlTestService. idl 生成的文件名是 i_idl_test_service.h、idl_test_service_proxy.h、idl_test_service_stub.h、idl_test_service_proxy.cpp、idl_test_service_stub.cpp。
+使用者通过执行命令 “./idl -gen-cpp -d dir -c dir/iTest.idl” （-d为输出目录）在执行环境的dir目录中生成接口文件、Stub文件、Proxy文件。生成的接口类文件名称和.idl文件名称保持一致，区别在于其使用.h和.cpp扩展名。例如，IIdlTestService.idl 生成的文件名是 i_idl_test_service.h、idl_test_service_proxy.h、idl_test_service_stub.h、idl_test_service_proxy.cpp、idl_test_service_stub.cpp。
 
 #### 3.1.2 服务端公开接口
 
- OpenHarmony IDL工具生成的Stub类是接口类的抽象实现，并且会声明.idl文件中的所有方法。 
+OpenHarmony IDL工具生成的Stub类是接口类的抽象实现，并且会声明.idl文件中的所有方法。 
 
-```
+```cpp
 #ifndef OHOS_IDLTESTSERVICESTUB_H
 #define OHOS_IDLTESTSERVICESTUB_H
 #include <iremote_stub.h>
@@ -182,7 +193,7 @@ private:
 
 开发者需要继承.idl文件中定义的接口类并实现其中的方法，同时在服务侧初始化时需要将定义的服务注册至SAMGR中，在本示例中，TestService类继承了IdlTestServiceStub接口类并实现了其中的TestIntTransaction和TestStringTransaction方法。具体的示例代码如下：
 
-```
+```cpp
 #ifndef OHOS_IPC_TEST_SERVICE_H
 #define OHOS_IPC_TEST_SERVICE_H
 
@@ -207,7 +218,7 @@ private:
 
 注册服务的示例代码如下：
 
-```
+```cpp
 #include "test_service.h"
 
 #include <string_ex.h>
@@ -259,12 +270,11 @@ ErrCode TestService::TestStringTransaction(const std::string &data)
 } // namespace OHOS
 ```
 
-
 #### 3.1.3 客户端调用IPC方法
 
 C++客户端通常通过SAMGR获取系统中定义的服务代理，随后即可正常调用proxy提供的接口。示例代码如下： 
 
-```
+```cpp
 #include "test_client.h"
 
 #include "if_system_ability_manager.h"
@@ -316,16 +326,13 @@ void TestClient::StartStringTransaction()
 } // namespace OHOS
 ```
 
-
-
-
 ### 3.2 TS开发步骤
 
 #### 3.2.1 创建.idl文件
 
  开发者可以使用TS编程语言构建.idl文件。.idl示例如下： 
 
-```
+```ts
   interface OHOS.IIdlTestService {
       int TestIntTransaction([in] int data);
       void TestStringTransaction([in] String data);
@@ -336,9 +343,9 @@ void TestClient::StartStringTransaction()
 
 #### 3.2.2 服务端公开接口
 
- OpenHarmony IDL工具生成的Stub类是接口类的抽象实现，并且会声明.idl文件中的所有方法。 
+OpenHarmony IDL工具生成的Stub类是接口类的抽象实现，并且会声明.idl文件中的所有方法。 
 
-```
+```ts
 import {testIntTransactionCallback} from "./i_idl_test_service";
 import {testStringTransactionCallback} from "./i_idl_test_service";
 import IIdlTestService from "./i_idl_test_service";
@@ -387,7 +394,7 @@ export default class IdlTestServiceStub extends rpc.RemoteObject implements IIdl
 
 开发者需要继承.idl文件中定义的接口类并实现其中的方法。在本示例中，我们继承了IdlTestServiceStub接口类并实现了其中的testIntTransaction和testStringTransaction方法。具体的示例代码如下：
 
-```
+```ts
 import {testIntTransactionCallback} from "./i_idl_test_service"
 import {testStringTransactionCallback} from "./i_idl_test_service"
 import IdlTestServiceStub from "./idl_test_service_stub"
@@ -408,7 +415,7 @@ class IdlTestImp extends IdlTestServiceStub {
 
 在服务实现接口后，需要向客户端公开该接口，以便客户端进程绑定。如果开发者的服务要公开该接口，请扩展Ability并实现onConnect()从而返回IRemoteObject，以便客户端能与服务进程交互。服务端向客户端公开IRemoteAbility接口的代码示例如下:
 
-```
+```ts
 export default {
     onStart() {
         console.info('ServiceAbility onStart');
@@ -442,7 +449,7 @@ export default {
 
 客户端调用connectAbility()以连接服务时，客户端的onAbilityConnectDone中的onConnect回调会接收服务的onConnect()方法返回的IRemoteObject实例。由于客户端和服务在不同应用内，所以客户端应用的目录内必须包含.idl文件(SDK工具会自动生成Proxy代理类)的副本。客户端的onAbilityConnectDone中的onConnect回调会接收服务的onConnect()方法返回的IRemoteObject实例，使用IRemoteObject创建IdlTestServiceProxy类的实例对象testProxy，然后调用相关IPC方法。示例代码如下：
 
-```
+```ts
 import IdlTestServiceProxy from './idl_test_service_proxy'
 import featureAbility from '@ohos.ability.featureAbility';
 
@@ -495,7 +502,7 @@ function connectAbility: void {
 
 MySequenceable类的代码示例如下：
 
-```
+```ts
 import rpc from '@ohos.rpc';
 export default class MySequenceable {
     constructor(num: number, str: string) {
@@ -523,8 +530,6 @@ export default class MySequenceable {
 }
 ```
 
-
-
 ## 4. C++与TS互通开发步骤
 
 ### 4.1 TS Proxy与C++ Stub开发步骤
@@ -535,7 +540,7 @@ export default class MySequenceable {
 
 2. 开发者创建服务对象，并继承C++ Stub文件中定义的接口类并实现其中的方法，例如：
 
-   ```
+   ```cpp
    class IdlTestServiceImpl : public IdlTestServiceStub {
    public:
        IdlTestServiceImpl() = default;
@@ -558,7 +563,7 @@ export default class MySequenceable {
 
 C++需要通过napi的方式，把C++服务对象提供给TS端，例如：C++端提供一个GetNativeObject方法，方法里创建IdlTestServiceImpl实例，通过NAPI_ohos_rpc_CreateJsRemoteObject方法，创建出一个JS远程对象供TS应用使用，如下：
 
-```
+```cpp
 NativeValue* GetNativeObject(NativeEngine& engine, NativeCallbackInfo& info)
 {
     sptr<IdlTestServiceImpl> impl = new IdlTestServiceImpl();
@@ -572,8 +577,7 @@ NativeValue* GetNativeObject(NativeEngine& engine, NativeCallbackInfo& info)
 
 如上所述TS开发步骤，开发者使用TS编程语言构建.idl文件，通过命令生成接口、Stub文件、Proxy文件。Proxy文件例如：
 
-```
-
+```ts
 import {testIntTransactionCallback} from "./i_idl_test_service";
 import {testStringTransactionCallback} from "./i_idl_test_service";
 import IIdlTestService from "./i_idl_test_service";
@@ -634,7 +638,7 @@ export default class IdlTestServiceProxy implements IIdlTestService {
 2. 构建TS Proxy对象，并把C++服务的远程对象传递给它
 3. 此时开发者通过TS Proxy对象调用.idl声明的方法，实现TS Proxy与C++ Stub的互通，示例如下：
 
-```
+```ts
 import IdlTestServiceProxy from './idl_test_service_proxy'
 import nativeMgr from 'nativeManager';
 
@@ -659,4 +663,3 @@ function jsProxyTriggerCppStub()
   	tsProxy.testStringTransaction("test", testIntTransactionCallback);
 }
 ```
-