diff --git a/en/api/framework/feature/feature_framework.md b/en/api/framework/feature/feature_framework.md index 71b6ceb5..f4092a0c 100644 --- a/en/api/framework/feature/feature_framework.md +++ b/en/api/framework/feature/feature_framework.md @@ -6,7 +6,12 @@ In QuickApp development, new capabilities need to be added to QuickApps, and these capabilities are written in C/C++. The Feature framework is a framework, SDK, and toolset that helps system developers extend functionality for QuickApps. -Feature Framework Architecture Diagram +The overall architecture is organized into the following layers, from top to bottom: + +- **JS Layer** — QuickApp (user JS code) +- **Framework Layer** — QuickApp Framework (together with the QuickApp Engine) and Feature Framework +- **Native Layer** — Feature implementations written in C/C++ +- **OS Layer** — openvela ## Feature Framework Capabilities @@ -41,13 +46,24 @@ From a system perspective, the Feature concepts: #### Runtime Concept Model -Each Feature can associate Native data, with different associated content. The runtime concept model is as follows: +Each Feature can associate Native data, with different associated content: -Feature Runtime Concept Model +- **Module** is purely internal to the Native side and is never exposed to the JS environment. +- **Prototype** appears in JS as a `JSObject`, but cannot be used directly from JS. On the Native side, it holds `prototype Native data` whose lifetime matches the app. +- **Instance** also appears in JS as a `JSObject`, and on the Native side holds `instance Native data` whose lifetime matches the instance itself. #### Feature Lifecycle -Feature Lifecycle Diagram +The Feature lifecycle consists of six events, listed below in the order they occur: + +| Event | Triggered When | Notes | +| ---------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| **`onRegister`** (Module Registration) | When the system starts up, or when `FeatureManagerRegister` is called | Do not perform long / complex tasks during registration, otherwise system startup will slow down | +| **`onCreate`** (Prototype Creation) | The first time the app uses the Feature | Do not expect this function to be called at app startup | +| **`onRequire`** (Instance Creation) | When the app calls `require` for this Feature | Feature instance initialization can be done here | +| **`onDettach`** (Instance Destruction) | When a Feature instance is destroyed (page exit, app exit, etc.) | Feature teardown is non-deterministic; do not defer recycling of temporary data to this point | +| **`onDestroy`** (Prototype Destruction) | When the app exits | App-wide global data is recycled here | +| **`onUnregister`** (Module Unregistered) | When the Feature is unregistered | Do not rely on this callback; it may never be called | ### Feature Framework Interface Capabilities @@ -71,23 +87,25 @@ The Feature framework helps developers create Feature Prototypes and Instances. From JS to Native, the Feature framework provides parameter conversion capabilities, converting JS parameters to plain parameters. The following table shows the basic conversion capabilities: -| JS Type | C Type | Description | -| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -| number/boolean | int, float, double, bool | JS number types exist as floating point. Based on JIDL description, they can be converted to compatible types like int, float. Converting to int/bool causes loss of decimal part | -| string | FtString | `const char*` typedef | -| object | struct pointer / FtAny pointer | If a struct is defined in JIDL, converts to the corresponding C struct pointer; if defined as object/any type in JIDL, defined as FtAny pointer | -| array | FtArray pointer | Converts to a C structure FtArray | -| function | FtCallbackId | Converts to an integer representing CallbackId | -| promise | FtPromiseId | Converts to an integer representing PromiseId | +| JS Type | C Type | Description | +| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| number/boolean | int, float, double, bool | JS number types exist as floating point. Based on JIDL description, they can be converted to compatible types like int, float. Converting to int/bool causes loss of decimal part | +| string | FtString | `const char*` typedef | +| object | struct pointer / FtAny pointer | If a struct is defined in JIDL, converts to the corresponding C struct pointer; if defined as object/any type in JIDL, defined as FtAny pointer | +| array | FtArray pointer | Converts to a C structure FtArray | +| function | FtCallbackId | Converts to an integer representing CallbackId | +| promise | FtPromiseId | Converts to an integer representing PromiseId | --- - Pointer objects have built-in reference counting and can be released via `FeatureDupValue` and `FeatureFreeValue`. - Pointers passed through parameters do not need additional release. -The following diagram shows the management mechanism for Callbacks and Promises: +The Feature framework internally manages Callback and Promise objects, hiding the implementation details: -Callback and Promise Management Mechanism +- Feature developers receive opaque IDs (`FtCallbackId` / `FtPromiseId`) instead of direct references to JS Function or Promise objects. +- The real JS Function and Promise instances are held inside the Feature framework (not visible to developers), together with reference counting. +- IDs act as indices into the internal tables, and the framework is responsible for reclaiming them. The Feature framework achieves two goals by hiding details: diff --git a/en/api/framework/feature/figures/Asynchronous_model.png b/en/api/framework/feature/figures/Asynchronous_model.png index 0900bfe9..bfcf30e6 100644 Binary files a/en/api/framework/feature/figures/Asynchronous_model.png and b/en/api/framework/feature/figures/Asynchronous_model.png differ diff --git a/en/api/framework/feature/figures/JIDL.png b/en/api/framework/feature/figures/JIDL.png index 9aa70735..3ac3aa92 100644 Binary files a/en/api/framework/feature/figures/JIDL.png and b/en/api/framework/feature/figures/JIDL.png differ diff --git a/en/api/framework/feature/figures/callback_promise_manager.png b/en/api/framework/feature/figures/callback_promise_manager.png deleted file mode 100644 index 95632752..00000000 Binary files a/en/api/framework/feature/figures/callback_promise_manager.png and /dev/null differ diff --git a/en/api/framework/feature/figures/feature_framework.png b/en/api/framework/feature/figures/feature_framework.png deleted file mode 100644 index db2aa7ec..00000000 Binary files a/en/api/framework/feature/figures/feature_framework.png and /dev/null differ diff --git a/en/api/framework/feature/figures/feature_instance.png b/en/api/framework/feature/figures/feature_instance.png index 7ffa4ba0..af103c43 100644 Binary files a/en/api/framework/feature/figures/feature_instance.png and b/en/api/framework/feature/figures/feature_instance.png differ diff --git a/en/api/framework/feature/figures/feature_life.png b/en/api/framework/feature/figures/feature_life.png deleted file mode 100644 index b783be91..00000000 Binary files a/en/api/framework/feature/figures/feature_life.png and /dev/null differ diff --git a/en/api/framework/feature/figures/feature_running.png b/en/api/framework/feature/figures/feature_running.png deleted file mode 100644 index 50317fdb..00000000 Binary files a/en/api/framework/feature/figures/feature_running.png and /dev/null differ diff --git a/en/api/framework/feature/figures/feature_static.png b/en/api/framework/feature/figures/feature_static.png index 60d6863b..0df1bedc 100644 Binary files a/en/api/framework/feature/figures/feature_static.png and b/en/api/framework/feature/figures/feature_static.png differ diff --git a/en/api/framework/quickapp/basic.md b/en/api/framework/quickapp/basic.md index d9186852..059e6788 100644 --- a/en/api/framework/quickapp/basic.md +++ b/en/api/framework/quickapp/basic.md @@ -15,10 +15,6 @@ This document introduces the overall design, implementation approach, and techni - [Xiaomi openvela QuickApp Development Manual](https://iot.mi.com/vela/quickapp/zh/content/intro.html) — Complete development guide for application developers - [Feature Framework API](../feature/index.md) — Native extension APIs for QuickApp (JS and C/C++ interop) -## Overall Architecture - -![QuickApp Framework Architecture](figures/basic_structure.png) - ## Build Configuration The application framework itself has few configuration items, but has many dependencies. Among the dependencies, the renderer has the most requirements. For specific configuration, please refer to the documentation provided by the graphics team. diff --git a/en/api/framework/quickapp/figures/basic_structure.png b/en/api/framework/quickapp/figures/basic_structure.png deleted file mode 100644 index a793e23c..00000000 Binary files a/en/api/framework/quickapp/figures/basic_structure.png and /dev/null differ diff --git a/en/api/framework/telephony/figures/TapiWork.png b/en/api/framework/telephony/figures/TapiWork.png index fc3358de..7318f88b 100644 Binary files a/en/api/framework/telephony/figures/TapiWork.png and b/en/api/framework/telephony/figures/TapiWork.png differ diff --git a/zh-cn/api/framework/feature/feature_framework.md b/zh-cn/api/framework/feature/feature_framework.md index 7553d252..3aa5b093 100644 --- a/zh-cn/api/framework/feature/feature_framework.md +++ b/zh-cn/api/framework/feature/feature_framework.md @@ -6,7 +6,12 @@ 在快应用（Quick App）开发中，需要为快应用增加一些新的能力，这些能力通过 C/C++ 语言编写。Feature 框架是一个帮助系统开发者为快应用扩展功能的框架、SDK 以及工具集。 -Feature 框架整体架构图 +整体架构从上到下分为以下几层： + +- **JS 层** —— 快应用（用户编写的 JS 代码） +- **框架层** —— 快应用框架（及快应用引擎）、Feature 框架 +- **Native 层** —— Feature 的 C/C++ 实现 +- **操作系统层** —— openvela ## 二、Feature 框架能力 @@ -41,13 +46,24 @@ Feature 有 3 层概念： #### 运行时概念模型 -每个 Feature 都可以关联 Native 数据，所关联的内容有所区别。运行时概念模型如下： +每个 Feature 都可以关联 Native 数据，所关联的内容有所区别： -Feature 运行时概念模型 +- **Module** 完全位于 Native 侧，不暴露给 JS 环境。 +- **Prototype** 在 JS 中以 `JSObject` 形式呈现，但不能直接在 JS 中使用。在 Native 侧持有 `prototype Native 数据`，生命周期与 APP 一致。 +- **Instance** 在 JS 中也以 `JSObject` 形式呈现，在 Native 侧持有 `instance Native 数据`，生命周期与 Instance 本身一致。 #### Feature 的生命周期 -Feature 生命周期示意图 +Feature 的生命周期包含 6 个事件，按发生顺序依次如下： + +| 事件 | 触发时机 | 注意事项 | +| ----------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------ | +| **`onRegister`**（Module 注册） | 系统启动时调用，或者调用 `FeatureManagerRegister` 函数时触发 | 注册时不可执行长复杂任务，否则会导致系统启动变慢 | +| **`onCreate`**（Prototype 创建） | APP 第一次使用 Feature 时调用 | 不可期望该函数在 APP 启动时调用 | +| **`onRequire`**（Instance 创建） | APP Require 该 Feature 时调用 | 可在此做 Feature 实例初始化 | +| **`onDettach`**（Instance 销毁） | Feature 实例被销毁时（Page 退出、APP 退出等） | Feature 退出有一定不确定性，临时数据不能拖延到此刻回收 | +| **`onDestroy`**（Prototype 销毁） | APP 退出时调用 | 此处 APP 全局数据回收 | +| **`onUnregister`**（Module 被注销） | Feature 注销时调用 | 不可依赖此回调，该回调可能不会被调用 | ### 2、Feature 框架提供的接口能力 @@ -85,9 +101,11 @@ Feature 框架帮助开发者创建 Feature 的 Prototype 和 Instance。 - 指针对象自带引用计数，可以通过 `FeatureDupValue` 和 `FeatureFreeValue` 来释放。 - 通过参数传递的指针，不需要额外释放。 -下图展示了对 Callback 和 Promise 的管理机制： +Feature 框架内部对 Callback 和 Promise 做了统一管理，隐藏实现细节： -Callback 和 Promise 管理机制 +- Feature 开发者拿到的是不透明的整数 ID（`FtCallbackId` / `FtPromiseId`），而不是 JS Function 或 Promise 对象本身。 +- 真正的 JS Function 和 Promise 对象由 Feature 框架内部（开发者不可见）持有，并带有引用计数。 +- ID 作为索引指向内部表，资源的回收由框架负责。 Feature 框架通过隐藏细节，达到两个目的： diff --git a/zh-cn/api/framework/feature/figures/callback_promise_manager.png b/zh-cn/api/framework/feature/figures/callback_promise_manager.png deleted file mode 100644 index 95632752..00000000 Binary files a/zh-cn/api/framework/feature/figures/callback_promise_manager.png and /dev/null differ diff --git a/zh-cn/api/framework/feature/figures/feature_framework.png b/zh-cn/api/framework/feature/figures/feature_framework.png deleted file mode 100644 index db2aa7ec..00000000 Binary files a/zh-cn/api/framework/feature/figures/feature_framework.png and /dev/null differ diff --git a/zh-cn/api/framework/feature/figures/feature_life.png b/zh-cn/api/framework/feature/figures/feature_life.png deleted file mode 100644 index b783be91..00000000 Binary files a/zh-cn/api/framework/feature/figures/feature_life.png and /dev/null differ diff --git a/zh-cn/api/framework/feature/figures/feature_running.png b/zh-cn/api/framework/feature/figures/feature_running.png deleted file mode 100644 index 50317fdb..00000000 Binary files a/zh-cn/api/framework/feature/figures/feature_running.png and /dev/null differ diff --git a/zh-cn/api/framework/quickapp/basic.md b/zh-cn/api/framework/quickapp/basic.md index e38b47c6..c22f7aac 100644 --- a/zh-cn/api/framework/quickapp/basic.md +++ b/zh-cn/api/framework/quickapp/basic.md @@ -15,10 +15,6 @@ openvela 快应用（QuickApp）框架（以下简称"应用框架"），是 ope - [小米 openvela 快应用开发手册](https://iot.mi.com/vela/quickapp/zh/content/intro.html) — 面向应用开发者的完整开发指南 - [Feature 框架 API](../feature/index.md) — 快应用的 Native 扩展 API（JS 与 C/C++ 互调） -## 整体架构 - -![快应用框架整体架构图](figures/basic_structure.png) - ## 编译配置 应用框架本身的配置项不多，但依赖项较多。依赖项中渲染器的依赖较多，具体配置请参考图形组提供的文档。 diff --git a/zh-cn/api/framework/quickapp/figures/basic_structure.png b/zh-cn/api/framework/quickapp/figures/basic_structure.png deleted file mode 100644 index a793e23c..00000000 Binary files a/zh-cn/api/framework/quickapp/figures/basic_structure.png and /dev/null differ