# pyside6-qml-basics

**Repository Path**: kid-kid/pyside6-qml-basics

## Basic Information

- **Project Name**: pyside6-qml-basics
- **Description**: pyside6-qml-项目模板
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-10
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: pyside6-qml项目模板

## README

# PySide6 QML 示例

这是一个基于 PySide6 和 QML 的桌面应用示例，演示如何用 `loadFromModule` 加载自定义 QML 模块，并用 `qmldir` 组织组件。

## 项目结构说明

```
chapter1-basics/
├── main.py               # 程序入口，设置 QML import 路径并加载模块
├── qml_src/              # QML 模块根目录（模块名：qml_src）
│   ├── App.qml           # 导出为 singleton App 1.0（在 qmldir 中声明）
│   ├── content/
│   │   └── Mainscr.qml   # 主界面，import components 1.0
│   ├── components/       # 子模块 components
│   │   ├── CustomButton.qml
│   │   └── qmldir        # 声明 components 模块及类型映射
│   └── qmldir            # 声明 qml_src 模块、版本和导出类型
├── resources/            # 静态资源
├── src/                  # Python 业务代码（示例为空）
├── requirements.txt      # Python 依赖
└── README.md
```

## 文件详细说明

### main.py - 程序入口文件

初始化 `QGuiApplication`，将项目根目录与 `qml_src` 目录加入 QML 导入路径，然后通过 `engine.loadFromModule("qml_src", "App")` 加载 `App.qml`。

### src/ - Python 源代码目录

存放 Python 业务逻辑代码、模型和控制器等。

### qml_src/ - QML 模块目录

- `qmldir`: 声明模块名 `qml_src`、版本及导出类型（如 singleton App）
- `App.qml`: 模块入口（在 qmldir 中声明为 App 1.0）
- `content/Mainscr.qml`: 主界面，依赖 `components` 子模块
- `components/`: 子模块，`qmldir` 声明 `CustomButton` 类型

### resources/ - 资源文件目录

存放项目所需的各种静态资源：

- `icons/`: 应用图标
- `img/`: 图片资源
- `trans/`: 国际化翻译文件

### requirements.txt - 依赖文件

列出项目所需的 Python 包依赖。

## 运行项目

1. 安装依赖：

   ```
   pip install -r requirements.txt
   ```
2. 运行程序：

   ```
   python main.py
   ```

## QML 模块加载要点

- 需要 `engine.addImportPath(project_root)`，以便找到 `qml_src/qmldir`。
- 建议同时 `engine.addImportPath(os.path.join(project_root, "qml_src"))`，以便子模块 `components`（路径 `qml_src/components/qmldir`）被解析。
- 删除或缺失 `qmldir` 会导致对应模块无法被 QML 引擎识别。