docs: update v25 dcc interface documentation #2978
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Reviewer's GuideUpdates the V25 DCC interface Chinese documentation and example plugin to align with Qt QML naming conventions and Qt6 qml plugin packaging, including renaming QML entry/metadata files, adjusting the documented plugin loading flow, raising CMake minimum versions, and fixing the placement of a sample DccObject in example pages. Sequence diagram for updated plugin loading flow with Qt QML pluginsequenceDiagram
participant CC as DDEControlCenter
participant PM as PluginManager
participant QE as QmlEngine
participant QP as QmlPlugin_example
participant Meta as Example_qml
participant Main as ExampleMain_qml
participant DObj as example_so_object
participant example_so as example_so
CC->>PM: request load module example
PM->>PM: check visibility config
alt module hidden
PM-->>CC: stop loading
else module visible
PM->>QP: load Qt QML plugin example (qmldir)
QP->>QE: register libexample_qml.so and example.so
PM->>QE: load Example.qml
QE->>Meta: create root DccObject
Meta-->>PM: visible property
alt visible is false
PM-->>CC: stop loading
else visible is true
PM->>example_so: load in worker thread
example_so-->>PM: created example_so_object
PM->>DObj: move to main thread
PM->>QE: set dccData to example_so_object
PM->>QE: load ExampleMain.qml
QE->>Main: create root DccObject (entry)
Main->>DObj: call dccData.xxx()
PM->>CC: insert DccObject tree into module tree
end
end
Flow diagram for DccObject calcType placement in example pagesflowchart TD
A["Start: define DccObject calcType"] --> B["Set name = calcType"]
B --> C["Set parentName = example_2/body"]
C --> D["Set weight = 80"]
D --> E["Place DccObject inside ExamplePage2.qml"]
subgraph ExampleMain_qml["ExampleMain.qml"]
EM_root["Root DccObject"]
EM_body["example_2/body container"]
end
subgraph ExamplePage2_qml["ExamplePage2.qml"]
EP2_root["DccObject example_2"]
EP2_body["example_2/body"]
EP2_calc["DccObject calcType"]
end
E --> F["Loader loads ExamplePage2.qml into example_2/body"]
EM_root --> EM_body
EM_body --> EP2_root
EP2_root --> EP2_body
EP2_body --> EP2_calc
F --> G["Module tree uses parentName and weight to position calcType"]
G --> H["Result: calcType appears under example_2 in UI, independent of its declaration location"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- In the Chinese docs, the bullet
example.so、qmldir为qml插件c++导出的动态库is misleading becauseqmldiris not a dynamic library; consider rephrasing to distinguish the role ofqmldir(module descriptor) from the.solibraries. - The CMake comment says
qt_add_qml_moduleis supported from 3.18 but the minimum required version is set to 3.23; it would be clearer either to justify why 3.23 is required or to align the comment with the actual minimum requirement.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the Chinese docs, the bullet `example.so、qmldir为qml插件c++导出的动态库` is misleading because `qmldir` is not a dynamic library; consider rephrasing to distinguish the role of `qmldir` (module descriptor) from the `.so` libraries.
- The CMake comment says `qt_add_qml_module` is supported from 3.18 but the minimum required version is set to 3.23; it would be clearer either to justify why 3.23 is required or to align the comment with the actual minimum requirement.
## Individual Comments
### Comment 1
<location> `docs/v25-dcc-interface.zh_CN.md:113-114` </location>
<code_context>
│ ├── dcc_example.dci # 图标文件
│ ├── ExamplePage1.qml # 第一个示例页面的QML文件，在exampleMain.qml中加载
│ ├── ExamplePage2.qml # 第二个示例页面的QML文件，在exampleMain.qml中加载
-│ ├── example.qml # 主QML文件，包含简单的插件信息
-│ └── exampleMain.qml # 主QML文件，包含插件所有页面
</code_context>
<issue_to_address>
**suggestion (typo):** 示例注释中仍然使用旧的 `exampleMain.qml` 名称，建议改为 `ExampleMain.qml` 以与前文统一。
当前注释里的“在exampleMain.qml中加载”与前文统一约定的入口文件名 `ExampleMain.qml` 不一致，可能让人误以为是两个文件。请将这两行注释中的 `exampleMain.qml` 同步改为 `ExampleMain.qml`。
```suggestion
│ ├── ExamplePage1.qml # 第一个示例页面的QML文件，在ExampleMain.qml中加载
│ ├── ExamplePage2.qml # 第二个示例页面的QML文件，在ExampleMain.qml中加载
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
113
to
114
| │ ├── ExamplePage1.qml # 第一个示例页面的QML文件，在exampleMain.qml中加载 | ||
| │ ├── ExamplePage2.qml # 第二个示例页面的QML文件，在exampleMain.qml中加载 |
There was a problem hiding this comment.
suggestion (typo): 示例注释中仍然使用旧的 exampleMain.qml 名称，建议改为 ExampleMain.qml 以与前文统一。
当前注释里的“在exampleMain.qml中加载”与前文统一约定的入口文件名 ExampleMain.qml 不一致，可能让人误以为是两个文件。请将这两行注释中的 exampleMain.qml 同步改为 ExampleMain.qml。
Suggested change
| │ ├── ExamplePage1.qml # 第一个示例页面的QML文件，在exampleMain.qml中加载 | |
| │ ├── ExamplePage2.qml # 第二个示例页面的QML文件，在exampleMain.qml中加载 | |
| │ ├── ExamplePage1.qml # 第一个示例页面的QML文件，在ExampleMain.qml中加载 | |
| │ ├── ExamplePage2.qml # 第二个示例页面的QML文件，在ExampleMain.qml中加载 |
mhduiy
approved these changes
Jan 31, 2026
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: caixr23, mhduiy The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Updated the V25 DCC interface documentation to reflect the latest plugin
structure changes and QML naming conventions. Changed {name}.qml to
{Name}.qml to follow QML naming standards. Updated plugin file structure
to use Qt's qml plugin format with qmldir and lib{name}_qml.so files.
Modified the plugin loading sequence description to match the new
structure. Updated CMakeLists.txt minimum version requirement to 3.23+
for qt_add_qml_module support. Fixed the position of calcType DccObject
in example files to be properly placed within the correct parent
hierarchy.
Log: Updated plugin documentation for QML naming conventions and file
structure
Influence:
1. Verify plugin documentation accurately reflects current plugin
structure
2. Test plugin loading with the new file naming conventions
3. Check that example plugins compile correctly with updated CMake
requirements
4. Validate that DccObject hierarchy and positioning works as described
5. Confirm plugin metadata files follow proper naming standards
docs: 更新 V25 DCC 接口文档
更新了 V25 DCC 接口文档以反映最新的插件结构变更和 QML 命名规范。将
{name}.qml 改为 {Name}.qml 以遵循 QML 命名标准。更新了插件文件结构以使用
Qt 的 qml 插件格式，包含 qmldir 和 lib{name}_qml.so 文件。修改了插件加载
顺序描述以匹配新结构。将 CMakeLists.txt 最低版本要求更新为 3.23+ 以支持
qt_add_qml_module 函数。修复了示例文件中 calcType DccObject 的位置，确保
其正确放置在适当的父层级中。
Log: 更新插件文档以符合 QML 命名规范和文件结构
Influence:
1. 验证插件文档准确反映当前插件结构
2. 测试使用新文件命名规范的插件加载
3. 检查示例插件是否使用更新的 CMake 要求正确编译
4. 验证 DccObject 层级结构和定位按描述工作
5. 确认插件元数据文件遵循正确的命名标准
Contributor
Author
|
/forcemerge |
|
This pr force merged! (status: blocked) |
deepin pr auto reviewGit Diff 审查报告1. 语法逻辑审查1.1 版本号问题问题: 文档中的日期 | 2026.1.14 | 1.1 | 修改{name}.qml为{Name}.qml(qml命名规范) | 6.1.71 |建议: 修改为正确的日期，如 1.2 CMake版本要求问题: CMake最低版本要求从3.7提升到3.23，但注释说明3.18即可支持 cmake_minimum_required(VERSION 3.23) # qt_add_qml_module函数支持最小版本3.18,建议版本3.23+建议:
1.3 QML文件命名规范变更: 将小写qml文件名改为大写开头，如 2. 代码质量审查2.1 文档一致性问题: 文档中示例代码与实际文件结构不一致
建议: 确保文档与实际代码保持一致，或者明确说明哪些是文档示例，哪些是实际实现。 2.2 注释质量优点:
建议:
3. 代码性能审查3.1 插件加载顺序变更: 修改了插件加载顺序的描述 2. 以Qt的qml插件形式加载example模块
3. 加载Example.qml，若Example.qml中根对象DccObject对象visible属性为false，则加载结束
4. 在线程中加载example.so，最后会将example.so导出的对象移动到主线程
5. 将example.so导出的对象设置为dccData,加载ExampleMain.qml。此时，ExampleMain.qml中可以使用dccData.xxx()调用example.so导出的函数
6. 加载完成，将DccObject对象插入到模块树中评价:
建议:
3.2 资源管理变更: 将QML资源编译为动态库 libexample_qml.so为qml资源文件编译成的动态库。包含资源有：评价:
建议:
4. 代码安全审查4.1 插件命名规范变更: 强调插件命名规范 # 该name会设置为插件名，只支持字母加数字，需要与{Name}.qml中DccObject的name相同，用于插件禁用操作
set(PLUGIN_NAME "example")评价:
建议:
4.2 线程安全问题: 文档中提到插件对象会被移动到主线程，但没有详细说明线程安全注意事项 控制中心插件加载是在线程中，但最终会将插件对象移到主线程。所以example.so构造函数中创建的对象需要在example.so导出类的树结构中(即子对象的父对象或祖先对象是example.so导出类)，否则不会被移动到主线程，导致其中信号槽线程等不到，无法正常使用。建议:
4.3 调试安全问题: 文档中提到调试时不要使用asan 另外提醒，调试时候不要使用asan，因为没有使用asan的控制中心无法加载使用了asan编译的插件建议:
5. 其他建议
总结这次diff主要改进了QML文件的命名规范，使其更加符合QML开发惯例，并更新了插件加载顺序的描述，使其更加清晰。同时，将QML资源编译为动态库，提高了资源管理效率。 主要需要改进的地方包括：
总体而言，这些改进有助于提高插件开发的规范性和可维护性，但文档和代码的一致性需要进一步加强。 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updated the V25 DCC interface documentation to reflect the latest plugin structure changes and QML naming conventions. Changed {name}.qml to {Name}.qml to follow QML naming standards. Updated plugin file structure to use Qt's qml plugin format with qmldir and lib{name}_qml.so files. Modified the plugin loading sequence description to match the new structure. Updated CMakeLists.txt minimum version requirement to 3.23+ for qt_add_qml_module support. Fixed the position of calcType DccObject in example files to be properly placed within the correct parent hierarchy.
Log: Updated plugin documentation for QML naming conventions and file structure
Influence:
docs: 更新 V25 DCC 接口文档
更新了 V25 DCC 接口文档以反映最新的插件结构变更和 QML 命名规范。将
{name}.qml 改为 {Name}.qml 以遵循 QML 命名标准。更新了插件文件结构以使用 Qt 的 qml 插件格式，包含 qmldir 和 lib{name}_qml.so 文件。修改了插件加载 顺序描述以匹配新结构。将 CMakeLists.txt 最低版本要求更新为 3.23+ 以支持
qt_add_qml_module 函数。修复了示例文件中 calcType DccObject 的位置，确保 其正确放置在适当的父层级中。
Log: 更新插件文档以符合 QML 命名规范和文件结构
Influence:
Summary by Sourcery
Update V25 DCC interface documentation and example plugin to reflect the new QML plugin structure, naming conventions, and CMake requirements.
Documentation:
Tests: