diff --git a/zh-cn/application-dev/application-models/component-startup-rules-fa.md b/zh-cn/application-dev/application-models/component-startup-rules-fa.md index e5d4cb541b39af727c7721b9469cae606d9f56b2..05339c898e390eacd48f90d0f83b19a8186a0dc5 100644 --- a/zh-cn/application-dev/application-models/component-startup-rules-fa.md +++ b/zh-cn/application-dev/application-models/component-startup-rules-fa.md @@ -34,7 +34,7 @@ - **跨应用启动FA模型的ServiceAbility组件或DataAbility组件，对端应用需配置关联启动** - 只针对跨应用场景 - 只针对目标组件为ServiceAbility与DataAbility生效 - - 目标应用的AssociateWakeUp为**ture**，其提供的ServiceAbility与DataAbility才允许被其他应用访问 + - 目标应用的AssociateWakeUp为**true**，其提供的ServiceAbility与DataAbility才允许被其他应用访问 - 只有系统预置应用才允许配置AssociateWakeUp字段，其余应用AssociateWakeUp默认为**false** diff --git a/zh-cn/application-dev/application-models/process-model-stage.md b/zh-cn/application-dev/application-models/process-model-stage.md index cf030e0ba0931f75a7ebd64757d8a355b8df36a1..57ab8441035cfb72c8d829540342a7a51c343544 100644 --- a/zh-cn/application-dev/application-models/process-model-stage.md +++ b/zh-cn/application-dev/application-models/process-model-stage.md @@ -4,10 +4,8 @@ OpenHarmony的进程模型如下图所示。 -- 应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，如下图中绿色部分的“Main Process”。 - -- 应用中（同一Bundle名称）的同一类型ExtensionAbility（除ServiceExtensionAbility和DataShareExtensionAbility外）运行在一个独立进程中，如下图中蓝色部分的“FormExtensionAbility Process”、“InputMethodExtensionAbility Process”、其他ExtensionAbility Process。 - +- 应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility和DataShareExtensionAbility均是运行在同一个独立进程（主进程）中，如下图中绿色部分的“Main Process”。 +- 应用中（同一Bundle名称）的所有同一类型ExtensionAbility（除ServiceExtensionAbility和DataShareExtensionAbility外）均是运行在一个独立进程中，如下图中蓝色部分的“FormExtensionAbility Process”、“InputMethodExtensionAbility Process”、其他ExtensionAbility Process。 - WebView拥有独立的渲染进程，如下图中黄色部分的“Render Process”。 diff --git a/zh-cn/application-dev/application-models/thread-model-stage.md b/zh-cn/application-dev/application-models/thread-model-stage.md index 57ac44d934cee35e9b57e1a67bd8dd8047fa239a..ffa97516d3ca0adc7ded6460344f84d93741e835 100644 --- a/zh-cn/application-dev/application-models/thread-model-stage.md +++ b/zh-cn/application-dev/application-models/thread-model-stage.md @@ -4,7 +4,7 @@ 1. 执行UI绘制。 2. 管理主线程的ArkTS引擎实例，使多个UIAbility组件能够运行在其之上。 -3. 管理其他线程（例如Worker线程）的ArkTS引擎实例，例如启动和终止其他线程。 +3. 管理其他线程的ArkTS引擎实例，例如启动和终止Worker线程。 4. 分发交互事件。 5. 处理应用代码的回调，包括事件处理和生命周期管理。 6. 接收Worker线程发送的消息。 diff --git a/zh-cn/application-dev/quick-start/multi-hap-principles.md b/zh-cn/application-dev/quick-start/multi-hap-principles.md index 147f409d987cf47a827382cd62507cc4f2972fd7..9174e043ecb1013ec17c926e1b81ff2b4fb127ac 100644 --- a/zh-cn/application-dev/quick-start/multi-hap-principles.md +++ b/zh-cn/application-dev/quick-start/multi-hap-principles.md @@ -4,7 +4,7 @@ 多HAP机制主要是为方便开发者进行模块化管理。HAP和应用运行时的进程并不是一一对应的，具体运行机制如下： -- 默认情况下，应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，其他同类型ExtensionAbility分别运行在单独的进程。 +- 默认情况下，应用中（同一Bundle名称）的所有UIAbility、ServiceExtensionAbility和DataShareExtensionAbility均是运行在同一个独立进程（主进程）中，而其他相同类型的ExtensionAbility则是运行在各自独立的进程中。 - HAP支持在module.json5（Stage模型）或者config.json（FA模型）中通过process标签配置单独的进程（仅系统应用支持，三方应用不支持）。配置了process的HAP，其组件运行在单独的process进程中，多个HAP可以配置相同的process，则这些HAP运行在相同进程中，process配置的详细说明请参见[module.json5配置文件](module-configuration-file.md)。 diff --git a/zh-cn/application-dev/quick-start/shared-guide.md b/zh-cn/application-dev/quick-start/shared-guide.md index b7566cbac8ddc72acc40a9f44599a34eb83a5d73..834560babca1c76d83984f315f28b8cae29c118b 100644 --- a/zh-cn/application-dev/quick-start/shared-guide.md +++ b/zh-cn/application-dev/quick-start/shared-guide.md @@ -1,6 +1,6 @@ # 共享包概述 -OpenHarmony提供了两种共享包，[HAR（Harmony Achive）](har-package.md)静态共享包，和HSP（Harmony Shared Package）动态共享包。 +OpenHarmony提供了两种共享包，[HAR（Harmony Archive）](har-package.md)静态共享包，和HSP（Harmony Shared Package）动态共享包。 HAR与HSP都是为了实现代码和资源的共享，都可以包含代码、C++库、资源和配置文件，最大的不同之处在于：HAR中的代码和资源跟随使用方编译，如果有多个使用方，它们的编译产物中会存在多份相同拷贝；而HSP中的代码和资源可以独立编译，运行时在一个进程中代码也只会存在一份。 diff --git a/zh-cn/contribute/style-guide/Readme-CN.md b/zh-cn/contribute/style-guide/Readme-CN.md index 2a80e2a32cde98f8d5e5898765152df9a8d090dc..03b07573ebe8884ead45f77edcbd0e62637fe654 100644 --- a/zh-cn/contribute/style-guide/Readme-CN.md +++ b/zh-cn/contribute/style-guide/Readme-CN.md @@ -4,3 +4,4 @@ - [语言风格](style-guide-language-style.md) - [文档结构](style-guide-document-structure.md) - [内容元素](style-guide-content-elements.md) +- [示例代码风格](style-guide-example-code-style.md) diff --git a/zh-cn/contribute/style-guide/style-guide-content-elements.md b/zh-cn/contribute/style-guide/style-guide-content-elements.md index 6e4df91da149ba948da02bdc58abdcb0630ffc6a..2982cb4b506a4de022c05ee7336c50e2796f8ea6 100755 --- a/zh-cn/contribute/style-guide/style-guide-content-elements.md +++ b/zh-cn/contribute/style-guide/style-guide-content-elements.md @@ -81,7 +81,7 @@ ### 绘图 -【规则】绘图中出现的英文单词大小写规则：术语、缩略语、专有名词（如开发板名称、设备名称）遵循[术语与缩略语](#%E6%9C%AF%E8%AF%AD%E5%8F%8A%E7%BC%A9%E7%95%A5%E8%AF%AD)的要求，全文统一大小写；其它英文单词遵循Sentence caps样式，即首个单词首字母大写。 +【规则】绘图中出现的英文单词大小写规则：术语、缩略语、专有名词（如开发板名称、设备名称）遵循[术语与缩略语](#术语与缩略语)的要求，全文统一大小写；其它英文单词遵循Sentence caps样式，即首个单词首字母大写。 【建议】字号：中英文正常字号均采用10.5pt（14px）。中文字号下限为9pt（12px），英文字号下限为8pt（11px）。 @@ -156,16 +156,16 @@ - 链接到其他站点：\[示例]\(www.example.com) - | **正例** | **反例** | - | -------- | -------- | + | **正例** | **反例** | + | ----------------------------------------------------------- | ------------------------------------------------------ | | 请参见\[OpenHarmony开源项目](https://gitee.com/openharmony) | OpenHarmony开源项目请参见https://gitee.com/openharmony | ## 术语及缩略语 -【规则】术语/缩略语名称要同“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”保持一致，且全文统一。 +【规则】术语/缩略语名称要同“[OpenHarmony术语表](../../glossary.md)”保持一致，且全文统一。 -【规则】对于“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中未涵盖的行业通用术语/缩略语（如IP，MAC等），要同国际、国家、行业标准中的名称保持一致。 +【规则】对于“[OpenHarmony术语表](../../glossary.md)”中未涵盖的行业通用术语/缩略语（如IP，MAC等），要同国际、国家、行业标准中的名称保持一致。 【规则】禁止随意缩写英文单词，自创缩略语。 @@ -173,7 +173,7 @@ 【规则】中文文档中，缩略语全称中对应的字母大写。 -【规则】“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中，术语名以“英文全称 (缩略语)；中文全称”的形式写作；术语解释直接陈述术语内涵，不需要重复术语名。 +【规则】“[OpenHarmony术语表](../../glossary.md)”中，术语名以“英文全称 (缩略语)；中文全称”的形式写作；术语解释直接陈述术语内涵，不需要重复术语名。 | **正例** | **反例** | | ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -315,40 +315,7 @@ ## 代码与注释 - -### 行内代码 - -【规则】对于正文描述中涉及代码的内容，比如实际代码中的方法名、参数名或代码文件名等，使用`包裹显示。 - -| 正例 | 反例 | -| -------- | -------- | -| 在`index.js`文件中实现页面跳转。 | 在index.js文件中实现页面跳转。 | - - -### 代码块 - -【规则】对代码示例、命令行使用代码样式。在Markdown中，使用```呈现代码样式，同时指定语言类型。 - -![代码块示例](figures/code-block-example.png) - -【规则】代码块内容应符合对应语言的通用编程规范。 - -【规则】完整举例中的代码块复制后可直接执行，且执行结果与文档描述一致。 - -【规则】如果代码块中没有标识行号，则不添加行号标识。 - -【规则】代码块显示符合缩进要求。 - -【建议】代码块中的关键代码段提供注释说明。 - - -### 注释 - -【规则】适时为代码块添加注释，特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性，帮助开发者快速掌握开发过程。 - -【规则】注释符与代码块语法保持一致，禁止自创注释符。注释符与注释内容间统一添加一个空格。例如：对于JavaScript代码块，注释写法为“// 注释内容”。 - -【规则】当一行注释内容过长时，注意断句切分到下一行呈现。 +请参见[示例代码风格](style-guide-example-code-style.md)。 ## IP及MAC地址 diff --git a/zh-cn/contribute/style-guide/style-guide-example-code-style.md b/zh-cn/contribute/style-guide/style-guide-example-code-style.md new file mode 100644 index 0000000000000000000000000000000000000000..1a94ee4512c425b7e07fc192396362126e9354f6 --- /dev/null +++ b/zh-cn/contribute/style-guide/style-guide-example-code-style.md @@ -0,0 +1,530 @@ +# 示例代码风格 +本规范适用于文档中ArkTS、JavaScript和C/C++等编程语言的示例代码片段，旨在提高OpenHarmony文档示例代码的可读性、可维护性，以及风格一致性。 + +## 代码规范 + +### 【规则】遵守基本编程规范 + +【描述】 + +文档的示例代码需要遵循[JavaScript语言编程规范](../OpenHarmony-JavaScript-coding-style-guide.md)、[C语言编程规范](../OpenHarmony-c-coding-style-guide.md)和[C++语言编程规范](../OpenHarmony-cpp-coding-style-guide.md)基本的编码规范，包括命名规范、代码格式和代码规范等。 + +### 【规则】每个接口（包括方法和组件）均需要提供示例代码 + +【描述】 + +API参考中，每个接口（包括方法和组件）均需要提供示例代码。如果多个API存在关联关系，则需要在一个场景化的代码示例中体现。 + +### 【规则】示例代码中的变量需要包含定义、使用方法或者来源链接参考或者说明 + +【描述】 + +示例代码中的变量需要包含定义、使用方法或者来源链接参考或者说明，以确保开发者能够理解如何使用。例如，如果涉及到应用开发路径，需要提供获取应用开发路径的链接参考或方法。 + +【正例】 + +示例中的context的获取方式请参见[获取UIAbility的上下文信息](../../application-dev/application-models/uiability-usage.md#获取uiability的上下文信息)。 + +```ts +let context = ...; // UIAbilityContext +let want = { + deviceId: '', // deviceId为空表示本设备 + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'func', // moduleName非必选 + parameters: { // 自定义信息 + info: '来自EntryAbility Index页面', + }, +} +// context为调用方UIAbility的UIAbilityContext +context.startAbilityForResult(want).then((data) => { + ... +}).catch((err) => { + console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`); +}) +``` + +【反例】 + +```ts +// 反例1：使用到的context和want变量未进行定义 +// context为调用方UIAbility的UIAbilityContext +context.startAbilityForResult(want).then((data) => { + ... +}).catch((err) => { + console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`); +}) + +// 反例2：UIAbilityContext的使用来源不止this.context这一种，这里列举出来就会有展示不全的问题 +let context = this.context; // UIAbilityContext +let want = { + deviceId: '', // deviceId为空表示本设备 + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'func', // moduleName非必选 + parameters: { // 自定义信息 + info: '来自EntryAbility Index页面', + }, +} +// context为调用方UIAbility的UIAbilityContext +context.startAbilityForResult(want).then((data) => { + ... +}).catch((err) => { + console.error(`Failed to start ability for result. Code is ${err.code}, message is ${err.message}`); +}) +``` + +### 【建议】一致的依赖包命名风格 + +【描述】 + +导入的依赖包的命名与其依赖包的命名空间保持一致，以便于维护和理解代码。 + +采用一致的依赖包命名风格还可以方便IDE进行提示导入，提高编码效率。 + +【正例】 + +```ts +import promptAction from '@ohos.promptAction'; +``` + +【反例】 + +```ts +// 包名和其命名空间不一致，不利于维护和理解代码 +import prompt from '@ohos.promptAction'; +``` + +### 【规则】组件宽高等属性不加单位 + +【描述】 + +为了保持代码的一致性和简洁性，在设置组件的宽度、高度等属性时，应该尽量避免添加单位，因为组件的宽度、高度等属性默认以像素为单位。同时，避免添加单位也可以提高代码的可读性和便于维护。 + +【正例】 + +```ts +Image('test.png') + .width(100) + .height(100) + +Text('Hello World') + .fontSize(50) +``` + +【反例】 + +```ts +Image('test.png') + .width('100vp') + .height('100vp') + +Text('Hello World') + .fontSize('50fp') +``` + +## 代码展示 + +### 【规则】行内代码使用`包裹显示 + +【描述】 + +正文描述中涉及代码的内容，比如实际代码中的方法名、参数名或代码文件名等，使用`包裹显示。 + +【正例】 + +在`Index.ets`文件中实现页面跳转。 + +【反例】 + +在Index.ets文件中实现页面跳转。 + +### 【规则】代码示例、命令行使用代码样式进行代码染色 + +【描述】 + +对代码示例、命令行使用代码样式。在Markdown中，使用```呈现代码样式，同时指定语言类型。 + +代码染色是指在编辑器中对代码进行不同颜色的标记，以区分不同语法元素的功能。例如在编辑器中对不同的关键字、变量名、注释等使用不同的颜色进行标记，可以让代码更加易读易懂。 + +![代码块示例](figures/code-block-example.png) + +### 【规则】代码格式化 + +【描述】 + +在将代码示例放入指南之前，使用DevEco Studio中的代码格式化功能对代码进行格式化，以确保代码的一致性和可读性。 + +格式化代码的方法包括缩进、空格、换行等，这些方法可以使代码更易于阅读和理解，提高代码的可维护性和扩展性。 + +【正例】 + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import window from '@ohos.window'; + +export default class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage: window.WindowStage) { + windowStage.loadContent('pages/Index', (err, data) => { + }); + } +} +``` + +【反例】 + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import window from '@ohos.window'; + +export default class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage: window.WindowStage) { + // 代码未格式化 + windowStage.loadContent('pages/Index', (err, data) => { + }); + } +} +``` + +### 【规则】省略代码展示 + +【描述】 + +当需要在文档或代码中展示省略的部分时，使用统一的省略代码格式。省略代码应该简洁明了，避免冗长或混乱的格式。 + +【正例】 + +```ts +// 正例1： +... + +// 正例2： +// To do sthing. +``` + +【反例】 + +```ts +// 反例1： +// ... + +// 反例2： +.... + +// 反例3： +...... +``` + +### 【规则】代码注释展示 + +【描述】 + +示例代码中的关键内容和逻辑需要添加注释来说明，以确保开发者理解代码的作用。 + +适时为代码块添加注释，特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性，帮助开发者快速掌握开发过程。 + +注释符与代码块语法保持一致，禁止自创注释符。注释符与注释内容间统一添加一个空格。例如：对于ArkTS代码块，注释写法为“// 注释内容”。 + +当一行注释内容过长时，注意断句切分到下一行呈现。 + +示例代码中的关键内容和逻辑需要添加注释来说明，以确保开发者理解代码的作用。 + +代码注释应该清晰、简洁、有用，能够方便别人理解代码的含义和作用。注释应该写在代码上方或右方。 + +【正例】 + +```ts +// 正例1： +// 定义生命周期回调对象 +let abilityLifecycleCallback = {}; + +// 正例2： +let abilityLifecycleCallback = {}; // 定义生命周期回调对象 +``` + +【反例】 + +```ts +// 反例1：注释符与注释内容之间没有添加空格 +//定义生命周期回调对象 +let abilityLifecycleCallback = {}; + +// 反例2：注释符与注释内容之间没有添加空格 +let abilityLifecycleCallback = {}; //定义生命周期回调对象 + +// 反例3：注释符与注释内容之间添加了多个空格 +let abilityLifecycleCallback = {}; // 定义生命周期回调对象 +``` + +## 异常处理 + +### 【规则】在可能出现异常的代码段加上异常捕获，并按不同的异常类型进行分支判断 + +【描述】 + +在可能出现异常的代码段加上异常捕获，并按不同的异常类型进行分支判断，针对不同的异常类型需要使用统一的异常分支判断方式。 + +【正例】 + +```ts +// 情形1：err为undefined的场景 +if (err) { + ... +} + +// 情形2：err.code为非0的场景 +if (err.code) { + ... +} +``` + +【反例】 + +```ts +// 反例1： +if (err == null) { + ... +} + +// 反例2： +if (err != null) { + ... +} + +// 反例3： +if (err == undefined) { + ... +} + +// 反例4： +if (err === undefined) { + ... +} + +// 反例5： +if (err !== undefined) { + ... +} +``` + +### 【规则】使用console.error输出异常的详细信息，包含错误码和相关的message信息 + +【描述】 + +当存在异常情况时，统一使用`console.error(...)`方法将异常信息打印到控制台，以便在调试时能够快速发现问题。 + +在异常处理中，应该打印出异常的详细信息以便调试。 + +在打印异常信息时，应该使用模板字符串，并标明异常信息的`code`和`message`参数。 + +【正例】 + +```ts +// 模板： +console.error(`Failed to do sthing. Code: ${err.code}, message: ${err.message}`); + +// 正例： +notificationManager.publish(notificationRequest, (err) => { + if (err) { + // 异常分支打印 + console.error(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`); + return; + } + ... +}); +``` + +【反例】 + +```ts +// 反例1：错误日志使用console.log输出，不足以让开发者在调试时快速找到问题 +notificationManager.publish(notificationRequest, (err) => { + if (err) { + // 异常分支打印 + console.log(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`); + return; + } + ... +}); + +// 反例2：错误日志使用console.info输出，而非console.error，不利于开发者区分日志级别，快速找到问题 +notificationManager.publish(notificationRequest, (err) => { + if (err) { + // 异常分支打印 + console.info(`Failed to publish notification. Code: ${err.code}, message: ${err.message}`); + return; + } + ... +}); + +// 反例3：异常信息缺乏具体的code和message参数，不利于开发者定位和解决问题 +console.error(`Failed to publish notification, err: ${err}`); + +// 反例4：使用单引号而非模板字符串的双引号，导致变量无法解析，输出的日志信息不正确 +console.error('Failed to publish notification, err: ${err}'); + +// 反例5：使用字符串拼接和JSON序列化输出错误信息，不够直观和简洁，会增加日志产生量，不利于快速定位问题 +console.error('Failed to publish notification, err: ' + JSON.stringify(err)); +``` + +## 日志打印 + +### 【规则】正常日志打印使用console.info，以提供程序运行的状态和关键信息 + +【描述】 + +在代码编写过程中，为了更好地记录程序运行过程中的信息，开发者需要使用日志打印，以便于在程序出现异常时进行定位和排查。 + +在正常情况下，使用`console.info(...)`来打印正常日志信息。 + +【正例】 + +```ts +// 模板： +console.info('Succeeded in doing sthing.'); + +// 正例： +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Succeeded in publishing notification.'); +}); +``` + +【反例】 + +```ts +// 反例1：使用console.log(...)可能会让程序员产生困惑，无法明确该日志信息是正常日志还是错误日志 +notificationManager.publish(notificationRequest, (err) => { + ... + console.log('Succeeded in publishing notification.'); +}); + +// 反例2：使用了console.error(...)而不是console.info(...)来打印正常日志信息。console.error通常用于打印错误信息，而不是正常的日志信息 +notificationManager.publish(notificationRequest, (err) => { + ... + console.error('Succeeded in publishing notification.'); +}); +``` + +### 【规则】正常成功日志打印使用succeeded，以表示程序执行成功的结果 + +【描述】 + +在日志打印中使用一致的语言，例如成功日志可以使用`succeeded`来表达。 + +【正例】 + +```ts +// 模板： +console.info('Succeeded in doing sthing.'); + +// 正例： +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Succeeded in publishing.'); +}); +``` + +【反例】 + +```ts +// 反例1： +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Invoke publish success.'); +}); + +// 反例2： +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Invoke publish successful.'); +}); + +// 反例3： +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Invoke publish successfully.'); +}); +``` + +## 代码逻辑 + +### 【规则】回调方法中使用箭头函数替代常规函数 + +【描述】 + +在使用回调方法时，应该尽可能使用箭头方法代替常规方法，箭头方法的一个主要优点是可以避免 `this` 指向问题。在箭头方法中，`this` 绑定的是它所处的上下文的 `this` 值，而不是方法被调用时的 `this` 值。这样可以避免在使用常规方法时需要使用 `bind()` 或 `call()` 来绑定 `this` 的问题，从而简化代码并提高可读性。 + +【正例】 + +```ts +notificationManager.publish(notificationRequest, (err) => { + ... + console.info('Invoke publish succeeded.'); +}); +``` + +【反例】 + +```ts +notificationManager.publish(notificationRequest, function (err) { + ... + console.info('Invoke publish succeeded.'); +}); +``` + +### 【规则】禁止使用废弃接口 + +【描述】 + +禁止使用废弃接口，因为他们可能会在未来的版本中被删除或更改。使用最新的接口可以确保代码的稳定性和可维护性。 + +使用废弃接口可能导致代码不稳定，也可能会因为该接口在后续版本的更新中被废弃而引发编译错误、运行错误等问题。 + +如果在后续的版本中废除了某些接口，所有依赖这些接口的示例代码都需要同步适配修改。 + +【正例】 + +```ts +import fs from '@ohos.file.fs'; + +function createFile() { + // 获取应用文件路径 + let context = ...; // UIAbilityContext + let filesDir = context.filesDir; + + // 新建并打开文件 + let file = fs.openSync(filesDir + '/test.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + // 写入一段内容至文件 + let writeLen = fs.writeSync(file.fd, 'Try to write str.'); + // 从文件读取一段内容 + let buf = new ArrayBuffer(1024); + let readLen = fs.readSync(file.fd, buf, { offset: 0 }); + // 关闭文件 + fs.closeSync(file); +} +``` + +【反例】 + +```ts +// 使用了废弃的fileio接口，而不是推荐的fs接口 +import fileio from '@ohos.fileio'; + +function createFile() { + // 获取应用文件路径 + let context = ...; // UIAbilityContext + let filesDir = context.filesDir; + + // 新建并打开文件 + let fileFD = fileio.openSync(filesDir + '/test.txt', 0o102, 0o640); + // 写入一段内容至文件 + let writeLen = fileio.writeSync(fileFD, 'Try to write str.'); + // 从文件读取一段内容 + let buf = new ArrayBuffer(1024); + let readLen = fileio.readSync(fileFD, buf, { offset: 0 }); + // 关闭文件 + fileio.closeSync(fileFD); +} +``` +