code.gitea.io/gitea@v1.22.3/docs/content/contributing/guidelines-frontend.zh-cn.md (about)

     1  ---
     2  date: "2023-05-25T16:00:00+02:00"
     3  title: "前端开发指南"
     4  slug: "guidelines-frontend"
     5  sidebar_position: 20
     6  toc: false
     7  draft: false
     8  aliases:
     9    - /zh-cn/guidelines-frontend
    10  menu:
    11    sidebar:
    12      parent: "contributing"
    13      name: "前端开发指南"
    14      sidebar_position: 20
    15      identifier: "guidelines-frontend"
    16  ---
    17  
    18  # 前端开发指南
    19  
    20  ## 背景
    21  
    22  Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
    23  
    24  HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
    25  
    26  源文件可以在以下目录中找到：
    27  
    28  * **CSS 样式**： `web_src/css/`
    29  * **JavaScript 文件**： `web_src/js/`
    30  * **Vue 组件**： `web_src/js/components/`
    31  * **Go HTML 模板**： `templates/`
    32  
    33  ## 通用准则
    34  
    35  我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
    36  
    37  ## Gitea 特定准则
    38  
    39  1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
    40  2. HTML 的 id 和 class 应使用 kebab-case，最好包含2-3个与功能相关的关键词。
    41  3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含2-3个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
    42  4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有2-3个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
    43  5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
    44  6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
    45  7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
    46  8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
    47  9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
    48  10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
    49  11. 推荐使用自定义事件名称前缀`ce-`。
    50  12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-word-break`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。
    51  13. 尽量避免内联脚本和样式，建议将JS代码放入JS文件中并使用CSS类。如果内联脚本和样式不可避免，请解释无法避免的原因。
    52  
    53  ### 可访问性 / ARIA
    54  
    55  在历史上，Gitea大量使用了可访问性不友好的框架 Fomantic UI。
    56  Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`），
    57  但仍然存在许多问题需要大量的工作和时间来修复。
    58  
    59  ### 框架使用
    60  
    61  不建议混合使用不同的框架，这会使代码难以维护。
    62  一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
    63  
    64  推荐的实现方式：
    65  
    66  * Vue + Vanilla JS
    67  * Fomantic-UI（jQuery）
    68  * htmx （部分页面重新加载其他静态组件）
    69  * Vanilla JS
    70  
    71  不推荐的实现方式：
    72  
    73  * Vue + Fomantic-UI（jQuery）
    74  * jQuery + Vanilla JS
    75  * htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
    76  
    77  为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
    78  尽管不建议混合使用不同的框架，
    79  我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例，其中应使用 htmx。如果您需要更高级的反应性，请不要使用 htmx，请使用其他框架（Vue/Vanilla JS）。
    80  但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
    81  
    82  ### `async` 函数
    83  
    84  只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
    85  
    86  不建议使用`async`事件监听器，这可能会导致问题。
    87  原因是`await`后的代码在事件分发之外执行。
    88  参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
    89  
    90  如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
    91  建议将其放在函数的开头。
    92  
    93  如果我们想在非异步上下文中调用`async`函数，
    94  建议使用`const _promise = asyncFoo()`来告诉读者
    95  这是有意为之的，我们想调用异步函数并忽略Promise。
    96  一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
    97  
    98  ### 获取数据
    99  
   100  要获取数据，请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
   101  接受内容的`data`选项，将自动设置 CSRF 令牌并返回
   102  [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
   103  
   104  ### HTML 属性和 dataset
   105  
   106  禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
   107  然而，仍然存在一些特殊情况，因此当前的准则是：
   108  
   109  * 对于旧代码：
   110    * 应将`$.data()`重构为`$.attr()`。
   111    * 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
   112  
   113  * 对于新代码：
   114    * 不应使用`node.dataset`，而应使用`node.getAttribute`。
   115    * 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
   116  
   117  ### 显示/隐藏元素
   118  
   119  * 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
   120  * Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
   121  
   122  ### Go HTML 模板中的样式和属性
   123  
   124  建议使用以下方式：
   125  
   126  ```html
   127  <div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div>
   128  ```
   129  
   130  而不是：
   131  
   132  ```html
   133  <div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div>
   134  ```
   135  
   136  以使代码更易读。
   137  
   138  ### 旧代码
   139  
   140  许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
   141  
   142  ### Vue3 和 JSX
   143  
   144  Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。
   145  
   146  ### UI示例
   147  
   148  Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。