首页 开发规范


开发规范总结

  1. 命名规范:

    • 根类名: 必须是 ul-{type}-{name} 格式，如 .ul-card-user。
    • 内部元素: 遵循 BEM 规范，使用双下划线 __ 连接，如 .ul-card-user__header。
    • 状态: 使用独立的状态类进行组合，而非 BEM 的修饰符，如 .ul-card-user.dark。
    • 列表类型例外:对于类似list类型的组件，一般会搭配item的子类，BEM一般基于item实现。因为list一般不设置具体样式，主要改变盒模型，也用于统一设置不同的模式，此时类名组合的规则一般是ul-{name}-list，ul-{name}-item。
      • 因此，.ul-user-list 和 .ul-user-item 是允许的。
      • 因此，一般组件不要以-item结尾，因为item一般是列表的子类。

  2. 开发规范:

    • 严格遵守命名规范。
    • 样式变量: 优先使用 _common.scss 中定义的全局变量（如颜色、尺寸、间距等），直接使用scss变量。
    • 响应式设计: 组件必须具备良好的响应式能力。在开发或重构时，需要同步实现手机端效果，确保在桌面和移动设备上都能正常显示。
    • 主题设计: 组件不需要支持主题，应当通过页面修改root的css变量来实现主题切换，不需要在组件中考虑。

  3. 文件结构:

    • 组件位于 source/components/ 目录下，每个组件一个独立文件夹。
    • 每个组件包含 _index.html, _index.scss, _index.md 等文件。
    • source/components/_index.scss 文件会自动引入所有组件的样式。
    • 尽量在html中实现各种状态和模式的效果，而不是在markdown中说明。
    • 不需要在html中专门实现移动端的效果，因为网站提供了移动端的预览功能。

  4. 组件文档:

    • 组件文档应简洁明了，只包含必要的用法说明
    • 标题应当从三级标题开始，避免与页面主标题冲突
    • 大多数情况下不提供文档，有些组件有特殊用法才会进行说明

  5. 创建方式:

    • 使用命令 php think make:component {模板名} {组件名} {组件标题} 来快速生成标准结构的组件文件。

开发说明

本站是一个基于ulthon_admin的官网项目,有关样式的代码在source/scss目录下.

关于样式组件,目前开始使用scss重构开发.

推荐使用vscode开发,安装Live Sass Compiler扩展并启用以下配置: 在项目目录下创建配置文件.vscode/settings.json;

{
    "liveSassCompile.settings.formats": [
        {
            "format": "compressed",
            "extensionName": ".min.css",
            "savePath": "/public/cdn/"
        },
        {
            "format": "expanded",
            "extensionName": ".css",
            "savePath": "/public/cdn/"
        },
    ],
    "liveSassCompile.settings.generateMap": false
}

SCSS 结构说明

项目的 SCSS 遵循模块化的组织方式，核心文件结构如下：

  • source/scss/ului.scss: 这是样式的主入口文件。它负责按顺序导入所有其他 SCSS 文件，最终编译成 ului.css。

  • source/scss/_common.scss: 定义了项目的全局样式、变量（如颜色、字体、间距）、混合宏（Mixins）和基础重置样式。所有通用样式都应在此文件中定义。

  • source/components/_index.scss: 这是一个自动生成的文件，它会引入所有位于 source/components/ 目录下的独立组件样式。当你使用 php think make:component 命令创建新组件时，该文件会自动更新以包含新组件的 SCSS。

基本的目录结构。

source                              
├─ components                                       
└─ scss                             
   ├─ basic                                   
   ├─ layout                                   
   ├─ reset                                    
   ├─ state                                   
   ├─ utility                              
   ├─ ului.scss

组件命名规范

为了保持代码的清晰和可维护性，所有组件都应遵循以下命名规范：

  • 组件根 Class: 必须采用 ul-{type}-{name} 的格式。

    • ul-: 所有组件的固定前缀，作为命名空间。
    • {type}: 组件的分类，例如 card, list, form, btn 等。
    • {name}: 组件的具体名称。推荐使用有意义的单词（如 user-info, file）。如果组件变体较多或难以找到合适的描述词，也允许使用数字序号（如 1, 2, 3）。
    • 示例: .ul-card-user, .ul-list-item, .ul-card-1。
    • 列表例外:对于类似list模式的组件，一般会搭配item的子类，BEM一般基于item实现。因为list一般不设置具体样式，主要改变盒模型，也用于统一设置不同的模式，此时类名组合的规则一般是ul-{name}-list，ul-{name}-item。
      • 因此，.ul-user-list 和 .ul-user-item 是允许的。
      • 因此，一般组件不要以-item结尾，因为item一般是列表的子类。

  • 内部元素 (BEM 规范): 组件内部的子元素命名应严格遵循 BEM (Block, Element, Modifier) 方法论，以确保样式的独立性和可维护性。

    • 块 (Block): 即组件的根 Class，如 .ul-info-card。
    • 元素 (Element): 块的组成部分，使用双下划线 __ 连接。例如：.ul-info-card__header, .ul-info-card__body。
    • 修饰符 (Modifier): 用于定义块或元素的外观或状态。我们不使用 BEM 的 -- 连接符，而是采用独立的通用状态类进行组合。例如：
      • 深色主题卡片: .ul-info-card.dark
      • 禁用状态操作: .ul-info-card__action.disabled

  • 工具/辅助 Class: 通用的辅助类也应以 ul- 开头，例如 .ul-inline-block。

样式类型

ULUI 的样式库体系结构清晰，主要包含以下几种类型，由底层到上层依次为：

  • 基础与重置 (Base & Reset): 负责统一和重置不同浏览器的默认样式，并定义全局变量（如颜色、字体、间距）、基础排版和链接样式。这是整个样式库的基石。
  • 布局组件 (Layout): 提供页面级的宏观布局能力，如栅格系统 (.ul-row, .ul-col-*)、容器 (.ul-container) 等，用于快速搭建响应式页面框架。
  • 业务组件 (Business Component): 为特定业务场景设计的、功能完整的组件，例如用户信息卡片 (.ul-card-user)、文件列表 (.ul-card-file) 等。它们是组件库的核心价值所在。一个业务组件可能由多个基础组件组合而成，也可能因为其设计的独特性而成为一个完全独立的、自成一体的样式实现。
  • 状态类 (State): 用于描述组件或元素在特定情境下的状态，例如激活 (.active)、禁用 (.disabled)、隐藏 (.hidden) 或不同的主题模式 (.dark)。
  • 工具/辅助类 (Utility): 提供原子化的、高复用性的 CSS 功能，用于微调样式。例如间距、浮动、文本对齐等。

组件开发规范

所有新贡献或修改的组件都应遵循以下基本规范：

  1. 命名规范：组件的 HTML 和 SCSS 必须严格遵循 说明文件中 的组件命名规范，确保样式的独立性和可维护性。
  2. 样式变量：优先使用 _common.scss 中定义的全局变量（如颜色、字体、间距），避免在组件样式中使用硬编码的数值。
  3. 示例内容：HTML 示例代码应使用通用、有代表性的占位内容，清晰地展示组件的结构和用途。
  4. 响应式设计：组件应具备良好的响应式能力，确保在桌面和移动设备上都能正常显示和使用。

运行站点

本站是基于ulthon_admin开发的,它是ThinkPHP6的项目,你需要掌握相关基础才行.实际上是一个CMS站点.

如果你只希望修改组件样式的话,只关注source/scss目录下的文件就可以了

git clone https://gitee.com/ulthon/ului.git

cd ului

composer install

php think migrate:run

php think seed:run

php think run

此时可以访问:127.0.0.1:8000

创建组件命令

新版本的组件支持独立的文件，更好的浏览体验，可以快捷单独复制每个文件，可以通过命令生成：

# 创建
php think make:component tpl_name component_name component_title 
# 删除
php think make:component tpl_name component_name component_title -d

比如:

php think make:component list ul-user-list 用户列表

组件代码结构：

ul-music-list   
├─ _index.env   
├─ _index.html  
├─ _index.md    
└─ _index.scss