{"id":15160127,"url":"https://github.com/unity-technologies/com.unity.uiwidgets","last_synced_at":"2025-09-30T10:31:33.955Z","repository":{"id":37976160,"uuid":"276520081","full_name":"Unity-Technologies/com.unity.uiwidgets","owner":"Unity-Technologies","description":"UIWidgets is a Unity Package which helps developers to create, debug and deploy efficient, cross-platform Apps.","archived":true,"fork":false,"pushed_at":"2022-09-07T08:03:53.000Z","size":113880,"stargazers_count":625,"open_issues_count":21,"forks_count":78,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-11-10T09:37:42.464Z","etag":null,"topics":["android","app","cross-platform","flutter","ios","mobile","ui","uiwidgets","unity","unity-editor","unity-engine","webgl"],"latest_commit_sha":null,"homepage":"https://unity.cn/uiwidgets","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Unity-Technologies.png","metadata":{"files":{"readme":"README-ZH.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-02T01:33:39.000Z","updated_at":"2024-10-27T08:51:01.000Z","dependencies_parsed_at":"2022-08-08T22:45:21.093Z","dependency_job_id":null,"html_url":"https://github.com/Unity-Technologies/com.unity.uiwidgets","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unity-Technologies%2Fcom.unity.uiwidgets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unity-Technologies%2Fcom.unity.uiwidgets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unity-Technologies%2Fcom.unity.uiwidgets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unity-Technologies%2Fcom.unity.uiwidgets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Unity-Technologies","download_url":"https://codeload.github.com/Unity-Technologies/com.unity.uiwidgets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234724903,"owners_count":18877279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","app","cross-platform","flutter","ios","mobile","ui","uiwidgets","unity","unity-editor","unity-engine","webgl"],"created_at":"2024-09-26T22:22:08.711Z","updated_at":"2025-09-30T10:31:26.541Z","avatar_url":"https://github.com/Unity-Technologies.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":":warning: 为了便于项目的持续维护，很抱歉UIWidgets代码仓库即日起将迁往 https://github.com/UIWidgets/com.unity.uiwidgets ，并改为在该新仓库进行日常维护。您虽然仍然可以在这里提交您的issue报告，但请前往我们的新仓库来获取最新的UIWidgets项目。谢谢！\n\n# UIWidgets 2.0 （preview）\n\n## :rocket:  加入我们  :rocket:\n团队目前计划招募数位软件开发工程师（software engineer），工作地点为Unity中国 :cn: 的上海总部。\n\n竭诚欢迎有一定Unity或flutter开发经验并对UIWidgets感兴趣的工程师加入我们的官方QQ群 UIWidgets (Group ID: **234207153**)，微信群 UIWidgets 二群，或直接联系我们 (QQ: **541252510**) ，我们将帮助您成为Unity中国的UIWidgets开发团队的一员！\n\n## 介绍\n\nUIWidgets是Unity编辑器的一个插件包，可帮助开发人员通过Unity引擎来创建、调试和部署高效的跨平台应用。\n\nUIWidgets主要来自[Flutter](https://github.com/flutter/flutter)。但UIWidgets通过使用强大的Unity引擎为开发人员提供了许多新功能，显著地改进他们开发的应用性能和工作流程。\n\n**UIWidgets 2.0**是UIWidgets的最新版本，它针对**中国版Unity**开发并主要着力于UI绘制相关的整体性能优化。经测试，UIWidgets 2.0在iPhone 6等部分机型上的帧率相对1.0版本可以取得10%左右的提升。\n\n如果因为各种原因您还需要使用UIWidgets 1.0，请在Releases中下载对应的包或者使用uiwidgets_1.0分支。\n\n#### 效率\n通过使用最新的Unity渲染SDK，UIWidgets应用可以非常快速地运行并且大多数时间保持大于60fps的速度。\n\n#### 跨平台\n与任何其他Unity项目一样，UIWidgets应用可以直接部署在各种平台上，包括PC和移动设备等。\n\n#### 多媒体支持\n除了基本的2D UI之外，开发人员还能够将3D模型，音频，粒子系统添加到UIWidgets应用中。\n\n#### 开发者友好\n开发者可以使用许多高级工具，如CPU/GPU Profiling和FPS Profiling，直接在Unity Editor中调试UIWidgets应用。\n\n## 示例\n\n\u003cdiv style=\"text-align: center\"\u003e\u003ctable\u003e\u003ctr\u003e\n\u003ctd style=\"text-align: center\"\u003e\n  \u003cimg src=\"https://connect-prd-cdn.unity.com/20190323/p/images/2a27606f-a2cc-4c9f-9e34-bb39ae64d06c_uiwidgets1.gif\" width=\"200\"/\u003e\n\u003c/td\u003e\n\u003ctd style=\"text-align: center\"\u003e\n  \u003cimg src=\"https://connect-prd-cdn.unity.com/20190323/p/images/097a7c53-19b3-4e0a-ad27-8ec02506905d_uiwidgets2.gif\" width=\"200\" /\u003e\n\u003c/td\u003e\n\u003ctd style=\"text-align: center\"\u003e\n  \u003cimg src=\"https://connect-prd-cdn.unity.com/20190323/p/images/1f03c1d0-758c-4dde-b3a9-2f5f7216b7d9_uiwidgets3.gif\" width=\"200\"/\u003e\n\u003c/td\u003e\n\u003ctd style=\"text-align: center\"\u003e\n  \u003cimg src=\"https://connect-prd-cdn.unity.com/20190323/p/images/a8884fbd-9e7c-4bd7-af46-0947e01d01fd_uiwidgets4.gif\" width=\"200\"/\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\u003c/div\u003e\n\n### 基于UIWidgets的项目\n\n#### Unity Connect App\nUnity Connect App是使用**UIWidgets 2.0**开发的一个移动App产品，您随时可以在Android (https://unity.cn/connectApp/download)\n以及iOS (Searching for \"Unity Connect\" in App Store)端下载到它最新的版本. 本项目的所有代码均开源@https://github.com/UIWidgets/ConnectAppCN2.\n\n#### Unity中文官方文档\nUnity的线上中文官方文档由UIWidgets 1.0开发，您可以点击以下网址 https://connect.unity.com/doc 来访问它的全部内容。该项目目前已开源，所有代码可以在\nhttps://github.com/UnityTech/DocCN 查看。\n\n## 使用要求\n\n#### Unity\n:warning: **注意：UIWidgets 2.0仅仅适用于中国版Unity**\n\nUIWidgets的各个版本所需的Unity版本如下表所示。您可以从[https://unity.cn/releases](https://unity.cn/releases)下载最新的Unity。\n\n| UIWidgets 版本     |  Unity 2019 LTS  |  Unity 2020 LTS  | \n| -----------------------------------------------| ------------------------- | ------------------------- |\n| 1.5.4 及以下     | 2019.4.10f1 及以上  | N\\A |\n| 2.0.1   | 2019.4.26f1c1  | N\\A |\n| 2.0.3   | 2019.4.26f1c1 ~ 2019.4.29f1c1 | N\\A |\n| 2.0.4及以上 | 2019.4.26f1c1 ~ 2019.4.29f1c1 | 2020.3.24f1c2 及以上 |\n\n#### UIWidgets包\n\n访问我们的Github存储库 [https://github.com/Unity-Technologies/com.unity.uiwidgets](https://github.com/Unity-Technologies/com.unity.uiwidgets)下载最新的UIWidgets包。\n\n将下载的包文件夹移动到您Unity项目的根目录下。\n\n通常，你可以在控制台（或终端）应用程序中输入下面的代码来完成这个操作：\n\n   ```none\n    cd \u003cYourProjectPath\u003e\n    git clone https://github.com/Unity-Technologies/com.unity.uiwidgets.git com.unity.uiwidgets\n   ```\n\n此外，因为UIWidgets 2.0中为各个平台编译的C++动态库文件较大，我们使用了github提供的**Git Large File Storage**来管理它们以\n优化下载体验。为此，请您确保在下载UIWidgets前安装好该[服务](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)以便正确下载动态库文件。\n\n最后，在unity的PackageManager中，选择添加添加local file。选中```/com.unity.uiwidgets```下的```package.json```。\n\n#### 运行环境\n\n**UIWidgets 2.0**目前暂时只支持MacOS（**Intel64**，Metal/OpenGLCore），iOS（Metal/OpenGLes），Android（**OpenGLes**）以及 Windows（Direct3D11）。我们后续会针对更广泛的运行环境进行适配，敬请期待。与之相对的，UIWidgets 1.0目前支持所有Unity导出目标平台。\n\n## 入门指南（演示[视频](https://www.bilibili.com/video/BV1zR4y1s7HN/)）\n\n#### 一、 概观\n在本教程中，我们将创建一个非常简单的UIWidgets应用。 该应用只包含文本标签和按钮。 文本标签将计算按钮上的点击次数。\n\n首先，请打开或创建Unity项目并使用Unity编辑器打开它。\n\n#### 二、 场景构建\n\nUIWidgets应用通常构建在Unity UI Canvas上。 请按照以下步骤在Unity中创建一个\nUI Canvas。\n1. 选择 File \u003e New Scene来创建一个新场景。\n2. 选择 GameObject \u003e UI \u003e Canvas 在场景中创建UI Canvas。\n3. 右键单击Canvas并选择UI \u003e Panel，将面板（即面板1）添加到UI Canvas中。 然后删除面板中的 **Image** 组件。\n\n#### 三、创建小部件\n\nUIWidgets应用是用**C＃脚本**来编写的。 请按照以下步骤创建应用程序并在Unity编辑器中播放。\n1. 创建一个新C＃脚本，命名为“UIWidgetsExample.cs”，并将以下代码粘贴到其中。\n\n    ```csharp\n    using System.Collections.Generic;\n    using uiwidgets;\n    using Unity.UIWidgets.cupertino;\n    using Unity.UIWidgets.engine;\n    using Unity.UIWidgets.ui;\n    using Unity.UIWidgets.widgets;\n    using Text = Unity.UIWidgets.widgets.Text;\n    using ui_ = Unity.UIWidgets.widgets.ui_;\n    using TextStyle = Unity.UIWidgets.painting.TextStyle;\n\n    namespace UIWidgetsSample\n    {\n        public class UIWidgetsExample : UIWidgetsPanel\n        {\n            protected void OnEnable()\n            {\n                // if you want to use your own font or font icons.\n                    // AddFont(\"Material Icons\", new List\u003cstring\u003e {\"MaterialIcons-Regular.ttf\"}, new List\u003cint\u003e {0});\n                base.OnEnable();\n            }\n\n            protected override void main()\n            {\n                ui_.runApp(new MyApp());\n            }\n\n            class MyApp : StatelessWidget\n            {\n                public override Widget build(BuildContext context)\n                {\n                    return new CupertinoApp(\n                        home: new CounterApp()\n                    );\n                }\n            }\n        }\n\n        internal class CounterApp : StatefulWidget\n        {\n            public override State createState()\n            {\n                return new CountDemoState();\n            }\n        }\n\n        internal class CountDemoState : State\u003cCounterApp\u003e\n        {\n            private int count = 0;\n\n            public override Widget build(BuildContext context)\n            {\n                return new Container(\n                    color: Color.fromARGB(255, 255, 0, 0),\n                    child: new Column(children: new List\u003cWidget\u003e()\n                        {\n                            new Text($\"count: {count}\", style: new TextStyle(color: Color.fromARGB(255, 0 ,0 ,255))),\n                            new CupertinoButton(\n                                onPressed: () =\u003e\n                                {\n                                    setState(() =\u003e\n                                    {\n                                        count++;\n                                    });\n                                },\n                                child: new Container(\n                                    color: Color.fromARGB(255,0 , 255, 0),\n                                    width: 100,\n                                    height: 40\n                                )\n                            ),\n                        }\n                    )\n                );\n            }\n        }\n    }\n    ```\n\n2. 保存此脚本，并将其附加到Panel 1中作为其组件。\n3. 在Unity编辑器中，点击Play按钮来启动应用。\n\n#### 四、构建应用程序\n\n最后，你可以按以下步骤将UIWidgets应用构建成适用于任何特定平台的应用程序包。\n1. 选择**File** \u003e **Build Settings...**打开Build Settings面板。\n2. 选择目标平台，点击Build。 之后Unity编辑器将自动组装所有相关资源并生成最终的应用程序包。\n\n#### 五、如何加载图像？\n1. 将你的图像文件，如image1.png，放在StreamingAssets文件夹中。\n2. 使用Image.file(\"image1.png\")加载图像。\n\n\nUIWidgets也支持Gif！\n1. 假设你有一个loading1.gif文件，复制到StreamingAssets文件夹。\n2. 使用Image.file(\"loading1.gif\")加载gif图像。\n\n#### 六、在安卓上显示状态栏\n当一个Unity项目运行在Android设备上时，状态栏是默认隐藏且无法在编辑内进行调整的。\n如果您希望在您的UIWidgets App中显示状态栏，您可以取消```Start in fullscreen``` 与 ```record outside safe area```, 确认```UIWidgetsAndroidConfiguration```下```showStatusBar```为 ```true```\n\n#### 七、图片导入设置\n请将图片放入StreamingAssets下，而后用```Image.file```读取\n\n#### 八、外接纹理显示\n利用我们新增的Unity内置API``UIWidgetsExternalTextureHelper.createCompatibleExternalTexture``以及UIWidgets中的``Texture``组件，开发者可以生成一个兼容UIWidgets底层的Unity纹理并将它绑定并渲染到UIWidgets页面上。从而可以将3D模型、视频等添加到App中作为一个UI组件。\n\n需要注意，本功能目前只支持**OpenGLCore** (Mac), **OpenGLes** (iOS\u0026Android) 以及 **D3D11** (Windows)，且必须使用**Unity 2020.3.37f1c1**及以上版本。在我们的示例项目中有一个简单的例子 (例如``3DTest1.unity``)可供参考。\n\n#### 九、移动设备优化\n目前在默认情况下，为了保证流畅度，项目在各个平台上均会以最高的刷新频率运行。不过您可以通过在代码中设置```UIWidgetsGlobalConfiguration.EnableAutoAdjustFramerate = true```的方式来开启自动降帧的功能：该功能开启后，在UI内容不变的情况下我们将降低项目的刷新率来降低耗电。\n\n在移动设备上UI绘制的流畅度受到GC影响较大。如有卡顿，例如滑动掉帧。可开启OnDemandGC, UIWidgets将接管并优化整体GC效果，请在代码中设置```UIWidgetsGlobalConfiguration.EnableIncrementalGC = true```,并开启```Project Setting -\u003e Player -\u003e Other Settings -\u003e Use incremental GC```。\n\n## 调试UIWidgets应用程序\n\n在Editor模式下，编辑器菜单栏选择```UIWidgets-\u003eEnableDebug```。\n\n在Runtime模式下，Debug/Development build会自动开启Debug，Release build则会自动关闭Debug。\n\n## 使用Window Scope保护外部调用\n如果您在调试时遇到 `AssertionError: Window.instance is null` 或者在调用 `Window.instance` 时得到空指针, 那么您需要\n使用以下方式来保护您的调用，使之可以在正确的Isolate上执行回调逻辑：\n```csharp\nusing(Isolate.getScope(the isolate of your App)) {\n    // code dealing with UIWidgets,\n    // e.g. setState(() =\u003e {....})\n}\n```\n\n通常，在您使用外部事件，例如来自UIWidgets之外的输入事件、网络传输回调事件时需要做这样的处理。具体的您可以参考我们的 HttpRequestSample 这个样例中的写法。需要注意的是，一般情况下您在UIWidgets框架的内部调用 (如 `Widget.build, State.initState...`)中不需要额外采取上述保护措施。\n\n## 学习\n\n#### 教程\n\n包括开发组在内的广大开发者为UIWidgets提供了许多可供学习的样例和教程，你可以根据你的需求进行学习：\n- UIWidgets官方示例。目前所有官方使用的示例项目均维护在一个独立的Github仓库（ https://github.com/Unity-Technologies/com.unity.uiwidgets ）中。\n具体的，你可以在Sample项目的**Scene**子文件夹中浏览所有示例UI场景。\n此外，你还可以点击主菜单上的新增的UIWidgetsTests选项卡，并在下拉菜单中选择一个EditorWindow UI示例来运行。\n- awesome UIWidgets项目。你可以在Github仓库（ https://plastichub.unity.cn/unity-tech-cn/awesome-uiwidgets ）中找到一些UIWidgets有趣的小Demo。\n- UIWidgets Templates项目。你可以在Github仓库（ https://github.com/UIWidgets/uiwidgets-template ）中找到一些开箱即用的UIWidgets常用组件。\n- ConnectApp开源项目。这是一个完整的线上、开源、完全基于UIWidgets的第一方App项目。其中包含了大量产品级的UIWidgets工程实践细节，\n如果你想深入了解UIWidgets并且使用它构建线上项目，请访问项目Github仓库了解更多（ https://github.com/UIWidgets/ConnectAppCN2 ）。\n\n#### Wiki\n\n目前开发团队仍在改进UIWidgets Wiki。 由于UIWidgets主要来源于Flutter，你也可以参考Flutter Wiki中与UIWidgets API对应部分的详细描述。\n同时，你也可以加入我们的[讨论组](https://unity.cn/plate/uiwidgets)来和大家交流使用心得。\n\n#### 常问问题解答\n\n1. 在打开一个UIWidgets 2.0项目后Unity编辑器崩溃了。\n\n      请确定您使用的Unity编辑器版本兼容您使用的UIWidgets版本。例如，**UIWidgets 2.0.3**只支持以下中国版Unity版本：2019.4.26f1c1 ～ 2019.4.29f1c1。您可以在[这里](#unity)查找兼容您UIWidgets版本的Unity版本信息。\n\n2. 在打开一个UIWidgets 2.0项目后Unity控制台报错，报错信息为**DllNotFoundException: libUIWidgets**。\n\n      请首先检查您的UIWidgets根目录下/Runtime/Plugins中适配各个平台的C++库文件是否完整。例如，Windows平台下的libUIWidgets.dll位于*X86_64*子目录下，Mac平台下的libUIWidgets.dylib位于*osx*目录下。\n\n      如果您发现库文件不存在或者文件大小不正常（\u003c1MB)，请确认您已经在您电脑上安装了**Git Large File Storage**，然后在UIWidgets根目录下执行如下指令：\n      ```\n      git lfs pull\n      ```\n\n3. UIWidgets 2.0和UIWidgets 1.0的区别大吗？哪个更适合我的项目？\n\n      在UIWidgets 1.0中所有渲染相关代码都由C#编写并且使用了Unity [Graphics API](https://docs.unity3d.com/ScriptReference/Graphics.html)\n      进行渲染。因此它可以正确运行在任意Unity支持的平台。不过与此同时，它的运行效率较低，且渲染效果与flutter在某一些细节上并不一致。\n\n      在UIWidgets 2.0中我们将一个flutter引擎嵌入到了C++动态库中，然后Unity通过调用这个动态库来进行渲染。因此，它的渲染结果与flutter完全一致，且性能比C#实现的渲染代码有明显提升。不过为了使flutter引擎和Unity可以正确协作，我们对flutter和Unity引擎都进行了一些修改。因此，目前UIWidgets 2.0只能够运行在包含上述修改的中国版Unity中，并且暂时只支持部分Unity的目标平台。\n\n      由于UIWidgets 2.0在效果和效率上的优势，因此推荐大家使用。仅当您需要在UIWidgets 2.0暂时不支持的平台（如webgl）上开发时才推荐使用UIWidgets 1.0。此外，由于人力原因，目前只有UIWidgets 2.0我们会持续更新。\n\n4. 使用Unity 2020.3LTS打包UIWidgets 2.0的项目到iOS平台后Build失败，提示无法链接到OpenGLES库函数。\n\n      这是因为在Unity 2020.3版本中Unity导出的iOS项目默认不再包含对OpenGLES库的依赖，但UIWidgets 2.0需要依赖该库。为了解决这个问题，您需要手动用Xcode打开项目并为UnityFramework添加上对OpenGLES库的依赖。\n      \n## 联系我们\n官方QQ群: UIWidgets (群ID: 234207153)\n\n## 如何贡献\n请查看[CONTRIBUTING.md](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funity-technologies%2Fcom.unity.uiwidgets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funity-technologies%2Fcom.unity.uiwidgets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funity-technologies%2Fcom.unity.uiwidgets/lists"}