> [!IMPORTANT]  
> 本项目原名为 `tkintertools`，经社区[投票](https://github.com/Xiaokang2022/maliang/discussions/41)，已重命名为 `maliang`！🎉

<h1 align="center">maliang</h1>

<p align="center"><img src="docs/logo.png" alt="Logo" title="Logo" /></p>

<p align="center"><a href="README.md">English</a> · 简体中文 · <a href="README.zh-Hant.md">繁體中文</a></p>

<p align="center"><a title="官方网站" href="https://xiaokang2022.github.io/maliang/">https://xiaokang2022.github.io/maliang/</a></p>

<p align="center">
一个基于 <code>tkinter</code> 且控件都由 <code>Canvas</code> 绘制的轻量级 UI 框架
</p>

<p align="center">
<a href="https://github.com/Xiaokang2022/maliang/releases"><img alt="版本" title="版本" src="https://img.shields.io/github/v/release/Xiaokang2022/maliang?label=%e7%89%88%e6%9c%ac&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://pypistats.org/packages/maliang"><img alt="下载" title="下载" src="https://img.shields.io/pypi/dm/maliang?label=%e4%b8%8b%e8%bd%bd&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://github.com/Xiaokang2022/maliang/actions"><img alt="检查和测试" title="检查和测试" src="https://img.shields.io/github/actions/workflow/status/Xiaokang2022/maliang/python-package.yml?label=%e6%a3%80%e6%9f%a5%e5%92%8c%e6%b5%8b%e8%af%95&logo=data:image/svg+xml;charset=utf-8;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgd2lkdGg9IjE2IiBoZWlnaHQ9IjE2Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTggMGE4IDggMCAxIDEgMCAxNkE4IDggMCAwIDEgOCAwWk0xLjUgOGE2LjUgNi41IDAgMSAwIDEzIDAgNi41IDYuNSAwIDAgMC0xMyAwWm00Ljg3OS0yLjc3MyA0LjI2NCAyLjU1OWEuMjUuMjUgMCAwIDEgMCAuNDI4bC00LjI2NCAyLjU1OUEuMjUuMjUgMCAwIDEgNiAxMC41NTlWNS40NDJhLjI1LjI1IDAgMCAxIC4zNzktLjIxNVoiPjwvcGF0aD48L3N2Zz4=" /></a>
<a href="https://codecov.io/gh/Xiaokang2022/maliang"><img alt="代码覆盖率" title="代码覆盖率" src="https://img.shields.io/codecov/c/github/Xiaokang2022/maliang?label=%e4%bb%a3%e7%a0%81%e8%a6%86%e7%9b%96%e7%8e%87&logoColor=white&logo=codecov" /></a>
<br/>
<a href="https://github.com/Xiaokang2022/maliang/watchers"><img alt="关注" title="关注" src="https://img.shields.io/github/watchers/Xiaokang2022/maliang?label=%e5%85%b3%e6%b3%a8&style=flat&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://github.com/Xiaokang2022/maliang/forks"><img alt="复刻" title="复刻" src="https://img.shields.io/github/forks/Xiaokang2022/maliang?label=%e5%a4%8d%e5%88%bb&style=flat&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://github.com/Xiaokang2022/maliang/stargazers"><img alt="星标" title="星标" src="https://img.shields.io/github/stars/Xiaokang2022/maliang?label=%e6%98%9f%e6%a0%87&color=gold&style=flat&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://github.com/Xiaokang2022/maliang/issues"><img alt="议题" title="议题" src="https://img.shields.io/github/issues/Xiaokang2022/maliang?label=%e8%ae%ae%e9%a2%98&logo=data:image/svg+xml;charset=utf-8;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgd2lkdGg9IjE2IiBoZWlnaHQ9IjE2Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTggOS41YTEuNSAxLjUgMCAxIDAgMC0zIDEuNSAxLjUgMCAwIDAgMCAzWiI+PC9wYXRoPjxwYXRoIGZpbGw9IndoaXRlIiBkPSJNOCAwYTggOCAwIDEgMSAwIDE2QTggOCAwIDAgMSA4IDBaTTEuNSA4YTYuNSA2LjUgMCAxIDAgMTMgMCA2LjUgNi41IDAgMCAwLTEzIDBaIj48L3BhdGg+PC9zdmc+" /></a>
<a href="https://github.com/Xiaokang2022/maliang/pulls"><img alt="拉取请求" title="拉取请求" src="https://img.shields.io/github/issues-pr/Xiaokang2022/maliang?label=%e6%8b%89%e5%8f%96%e8%af%b7%e6%b1%82&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
<a href="https://github.com/Xiaokang2022/maliang/discussions"><img alt="讨论" title="讨论" src="https://img.shields.io/github/discussions/Xiaokang2022/maliang?label=%e8%ae%a8%e8%ae%ba&logo=data:image/svg+xml;charset=utf-8;base64, " /></a>
</p>

<p align="center">
<a href="https://github.com/Xiaokang2022/maliang/pulse"><img src="https://repobeats.axiom.co/api/embed/b4832e0ac90defe97c7e11e0c9e926793ec7135c.svg" /></a>
</p>

<p align="center">
    <a href="https://star-history.com/#Xiaokang2022/maliang&Date">
        <picture>
            <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Xiaokang2022/maliang&type=Date&theme=dark" />
            <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Xiaokang2022/maliang&type=Date" />
            <img src="https://api.star-history.com/svg?repos=Xiaokang2022/maliang&type=Date" />
        </picture>
    </a>
</p>

## 📦 安装

要安装该包，你的 Python 版本必须 **`>=3.10`**。用以下命令进行安装：

```shell
pip install maliang
```

### 🛠️ 依赖包

下面是该项目唯一必须需要的依赖包：

* [`typing-extensions`](https://github.com/python/typing_extensions): 提供额外的类型提示

### 🎨 可选包

下面的包都是可选的，不安装也能让该项目正常运行，但安装它们可以为你提供更多的功能：

* [`darkdetect`](https://github.com/albertosottile/darkdetect): 提供操作系统主题检测
* [`pillow`](https://github.com/python-pillow/Pillow): 提供更多类型图片的使用及优化图片缩放速度
* [`pywinstyles`](https://github.com/Akascape/py-window-styles): 提供一些 Windows 系统的窗口效果
* [`hPyT`](https://github.com/Zingzy/hPyT): 提供更多 Windows 系统窗口的配置选项
* [`win32material`](https://github.com/littlewhitecloud/win32material): 提供更多 Windows 系统窗口的配置选项

**推荐**，这些包都应该安装，用以下命令可以安装全部的可选包：

```shell
pip install maliang[opt]
```

### 🧩 扩展包

除了基础功能之外，我们还提供一些扩展包来实现某些特定的功能。目前已有的官方扩展包如下：

* [`maliang-mpl`](https://github.com/Xiaokang2022/maliang-mpl): 提供 `matplotlib` 包的相关支持
* [`maliang-media`](https://github.com/Xiaokang2022/maliang-media): 提供媒体文件的相关支持
* [`maliang-three`](https://github.com/Xiaokang2022/maliang-three): 提供简单 3D 绘图的相关支持

用以下命令可以安装全部的官方扩展包：

```shell
pip install maliang[ext]
```

此外，你还可以在[这里](https://xiaokang2022.github.io/maliang/t%26d/third-party/)找到所有已被我们收集到的第三方扩展包。

> [!WARNING]  
> 上述包并不包含在本项目的源代码中，如果你使用了它们并想要再分发，请遵循它们的开源协议！

## 👀 更多

### ℹ️ 关于

本项目的徽标取自开源项目：[`fluentui-emoji`](https://github.com/microsoft/fluentui-emoji)，名称取自中国童话故事：[*《神笔马良》*](https://baike.baidu.com/item/%E7%A5%9E%E7%AC%94%E9%A9%AC%E8%89%AF/14821387)

### 🖼️ 画廊

下面是一些可以用该项目实现的演示，它们可能是用该项目的最新版本构建的，也可能是用旧版构建的，但无论怎样，它们的代码都可以在[演示存储库](https://github.com/Xiaokang2022/maliang-demos)中找到！

> [!TIP]  
> 请点击 **“展开”** 来查看画廊

<details><summary><b>展开</b></summary>

![preview_1](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo9-1.png?raw=true)

![preview_2](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo9-2.png?raw=true)

![preview_3](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo9-3.png?raw=true)

![preview_4](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo9-4.png?raw=true)

![preview_5](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo0-1.png?raw=true)

![preview_6](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo0-2.png?raw=true)

![preview_7](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo1-1.png?raw=true)

![preview_8](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo1-2.png?raw=true)

![preview_9](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo2.png?raw=true)

![preview_10](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo3.png?raw=true)

![preview_11](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo4-1.png?raw=true)

![preview_12](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo4-2.png?raw=true)

![preview_13](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo5-1.png?raw=true)

![preview_14](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo5-2.png?raw=true)

![preview_15](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo6-1.png?raw=true)

![preview_16](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo7-1.png?raw=true)

![preview_17](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo7-2.png?raw=true)

![preview_18](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo8-1.png?raw=true)

![preview_19](https://github.com/Xiaokang2022/maliang-demos/blob/main/preview/demo10-1.png?raw=true)

![project_1](https://github.com/Xiaokang2022/Intelligent-Magic-Cube/blob/main/preview.png?raw=true)

![project_2](https://github.com/Xiaokang2022/Chess/blob/master/preview.png?raw=true)

![project_3](https://github.com/Xiaokang2022/Super-Gobang/blob/main/preview.png?raw=true)

![project_4](https://github.com/Xiaokang2022/TodoList/blob/master/preview.png?raw=true)

</details>

### 🔗 链接

这里是一些可能对您有帮助的链接：

* 📑 项目许可: [*MIT License*](LICENSE.txt)
* 📘 更新日志: [*CHANGELOG.md*](CHANGELOG.md)
* 📕 安全策略: [*SECURITY.md*](SECURITY.md)
* 📗 贡献指南: [*CONTRIBUTING.md*](CONTRIBUTING.md)
* 📙 行为准则: [*CODE_OF_CONDUCT.md*](CODE_OF_CONDUCT.md)
* 📚 教程和文档: [Tutorials & Documents](https://xiaokang2022.github.io/maliang-docs/) ([Mirror](https://maliang-docs.netlify.app/))
* ❤️ 赞助我们: [Sponsor](https://xiaokang2022.github.io/maliang/Sponsor/)
* 🚀 存储库镜像源:
[Gitee](https://gitee.com/Xiaokang2022/maliang),
[GitCode](https://gitcode.com/Xiaokang2022/maliang)

### 😉 贡献者

非常感谢下面这些人的贡献：

[![贡献者](https://contrib.rocks/image?repo=Xiaokang2022/maliang)](https://github.com/Xiaokang2022/maliang/graphs/contributors)
