UI Kit vs. Custom UI

为Forge应用程序构建用户界面有两种选择——UI工具包和自定义UI. UI工具包允许您使用一组atlassian提供的组件创建一个简单的UI, put together using relatively simple code. Custom UI gives you more room to use Atlassian-supplied and third-party hooks, components and such, while also allowing you to employ more complex HTML, CSS, static resources (such as images) and source code, 所有这些都可以托管在Atlassian的云上，使用自定义UI，但不使用UI工具包. 这两种类型的UI都涉及到以类似react的模式编写代码, 这是有道理的，因为Atlassian提供的各种组件都基于React.

注意:我的建议是从一开始就使用自定义UI. Custom UI imposes fewer limitations on you, the developer, and if you already have experience with React, 那么使用自定义UI的工作量并不比UI工具包多多少. 也就是说，在同一个应用程序中可以同时使用自定义UI和UI工具包[1].

React Support

目前，Forge所基于的前端框架React的版本是18.x. 然而，Atlassian Design System组件[2]明确支持React 16.x only [3]. 因为React的策略通常是一旦一个新的主要版本发布，就停止发布新的主要版本的修复程序(除了严重的错误)[4], 你应该选择最新的React版本.

Unfortunately, 当试图在React 17或更高版本中使用Design System组件时, you might get errors like the following while running npm install:

npm ERR! code ERESOLVE

npm ERR! ERESOLVE could not resolve

npm ERR!

npm ERR! While resolving: @atlaskit/button@16.7.3

npm ERR! Found: react@18.2.0

npm ERR! node_modules/react

npm ERR! react@"^18.2.0" from the root project

npm ERR! peer react@">=16.8.0" from @emotion/react@11.10.6

npm ERR! node_modules/@emotion/react

npm ERR! @emotion/react@"^11.7.1" from @atlaskit/button@16.7.3

npm ERR! node_modules/@atlaskit/button

npm ERR! @atlaskit/button@"^16.7.3" from the root project

npm ERR! @emotion/react@"^11.7.1" from @atlaskit/focus-ring@1.3.2

npm ERR! node_modules/@atlaskit/focus-ring

npm ERR! @atlaskit/focus-ring@"^1.3.0" from @atlaskit/button@16.7.3

npm ERR! node_modules/@atlaskit/button

npm ERR! @atlaskit/button@"^16.7.3" from the root project

npm ERR! 9 more (@atlaskit/icon, @atlaskit/motion, @atlaskit/popup, ...)

npm ERR! 24 more (@emotion/use-insertion-effect-with-fallbacks, ...)

You can work around this issue with the --legacy-peer-deps command-line switch provided by npm install. Importantly, while this will mask errors like the above, React 17或更高版本总是有可能弃用或消除设计系统组件所依赖的功能. 我强烈建议您密切关注前端控制台日志，查找指示此类潜在问题的警告或错误.

Checking Your Forge App’s License

如果你打算将Forge应用作为付费应用授权给用户[5], 你需要编写代码来检查应用程序的许可是否有效. Once you know what to do, it’s a fairly simple process.

NOTE: The following assumes that your app is using custom UI, and also that you’re familiar with the React framework.

First, in your back-end code, create a custom UI resolver function [6] like the following, which is modeled after [7]. Note that we’ll be creating a LICENSE_OVERRIDE 锻造环境变量，这将帮助mg官方游戏中心测试许可证检查.

当然，应用程序的前端运行在用户的浏览器中. Thus, it could be tampered with to skip license checks. 为了防止跳过这类检查，您需要添加 isLicenseActive() 调用不希望未经许可的用户访问的任何后端代码, then deny such access if it returns false. 这取决于您希望后端如何指示拒绝访问您的前端.

接下来，在后端代码中，将该函数添加到解析器定义中:

Then, in your front-end code, let’s use TanStack Query [8], a very handy data-fetching library, to create a hook named useIsLicenseActive() for calling the above back-end function:

Now, call useIsLicenseActive() as appropriate from your front-end code:

Finally, set the LICENSE_OVERRIDE Forge environment variable appropriately. 如果您正在使用forge tunnel命令测试本地代码副本, 您可以在您选择的类unix shell中使用export命令设置变量的值. If you’re not using forge tunnel, then use the forge variables set 命令，为您希望测试的任何环境设置变量的值. Generally, you will not 想要通过在应用的生产环境中设置这个变量来覆盖许可证检查.

注意:如果您从Windows shell中进行隧道操作，则需要执行以下操作才能使用 LICENSE_OVERRIDE variable or any other environment variable. 否则，将不能正确设置变量以供您使用.

Run the forge variables set -e development LICENSE_OVERRIDE 命令在开发环境中设置变量的值.
Run the forge deploy 命令将变量(和您的代码)部署到开发环境.
Run the forge tunnel command. Your local copy of the app will be run, 但是环境变量的值将按照上面指定的方式设置.

Surprise! Bonus Tip (Well, Several Tips): Personal Data Handling Requirements

Atlassian sells its services to customers around the world, some of whom are in the European Union (EU). Thus, Atlassian要求Forge应用程序按照欧盟的通用数据保护条例(GDPR)处理用户个人数据。. User personal data is any data that could be used, by itself or in conjunction with other data, to identify an individual user. Here are some tips on working with user personal data:

不要在应用程序或外部系统中存储用户个人数据. Instead, query user personal data as needed.
Don’t write user personal data to logs.
If you absolutely must do any of the above, 那么我强烈建议对存储或记录的用户个人数据进行散列或屏蔽.
If user personal data is stored, logged or otherwise collected in any fashion, regardless of where your app stores or logs that data, Atlassian将要求您在应用程序的隐私政策中注明您的应用程序收集此类数据. 该应用程序还必须通过Atlassian的个人数据报告API报告其收集的此类数据.
If your app stores user personal data, 应用程序必须实现一种机制来检测请求已经更改或删除用户个人数据(通过上面提到的API), then act on that request.
在某些情况下，您可能需要在收集用户个人资料时获得用户同意.
您必须采取合理的步骤来保护存储的任何用户个人数据, logged or otherwise collected.
长话短说:如果可能的话，不要收集用户的个人数据.

有关上述功能的更多信息，例如如何与个人数据报告API交互, how to explain your data privacy practices to users, 哪些用户的个人资料应该或不应该被记录-请浏览[9], [10] and [11]. 记住，你和你的团队要对你的应用的安全性负责!