Mendix 9.9 样式编辑器
收费的阳光
2021.12.30 17:26发布于技术 - 前端与UI
1221
集成了样式编辑器之后,整体性更加统一

自定义样式

此为官方文档译文,在中文镜像出现之前,我会尽量翻译一些新特性给大家了解;如果需要品尝原汁原味的文档,请跳转英文原文
 

1 简介

本页面介绍了开发人员如何使用Studio Pro更改应用程序的样式并创建可重复使用的样式。对于PWA和 Web 应用程序,使用 SASS (SCSS),对于移动原生应用程序,使用 JavaScript。尽管技术不同,自定义样式的方法是相同的。

2 更改应用程序外观

开发人员有多种选择来更改应用程序的外观。根据您是 Studio 还是 Studio Pro 用户,有不同的选项。

2.1 更改默认主题设置

定制应用程序的外观时,简单的第一步是更改主题设置。这可以通过更改颜色快速将主题调整为公司品牌风格。

对于 Studio 用户,使用主题定制器更改应用程序的基本外观。差异将立即显现。

对于 Studio Pro 用户,有更多选项可以更改默认主题设置。要自定义默认主题设置,从Studio Pro 9.9开始,您可以从应用程序资源管理器中打开并编辑自定义变量文件(App>Styling> web > custom-variables.scss用于 Web 应用程序,App>Styling> native custom-variables.js 用于移动原生应用程序)。

有关如何快速预览更改的更多信息,请参阅下面的预览样式更改部分。

2.2 使用样式编辑器

样式编辑器基于支持 Visual Studio Code 的编辑器,也用于 JavaScript 操作。您可以在 App Explorer 中找到样式文件(JS、SCSS)和主题设置(JSON),并使用此编辑器进行编辑。默认情况下,Studio Pro 在应用程序级别和 UI 资源模块(例如Atlas_Core )中显示样式文件。这可以在首选项Edit Preferences > General > Interface)中更改,或者只需在应用程序资源管理器中右键单击Styling

样式编辑器设置

要了解有关文件和文件夹结构的更多信息,请参阅下面的文件和文件夹结构部分。

2.3 添加自定义样式

开发人员可以为theme/webtheme/native文件夹中的应用程序添加自定义样式。

对于(PWA)Web 应用程序,自定义样式应theme/web放置在main.scss中并从中链接(或放置在)main.scss 中。对于移动原生应用程序,自定义样式应放置在theme/native 中,并从(或放置在)main.js 中链接

虽然自定义样式可以直接添加到main.scssmain.js 中,但最佳做法是在文件中分离样式并将这些文件包含在main.scssmain.js 中

在自定义样式中,可以重复使用在custom-variables.scsscustom-variables.js 中配置的主题设置(颜色、间距等)。我们也建议这样做以提供一致的用户体验。

2.3.1. web应用示例

在以下示例中,添加了自定义样式以在使用时更改任何匹配元素的字体大小。

步骤:

  1. theme/web/custom-variables.scss 中,通过将以下代码添加到文件中来添加 SCSS 变量:

    $company-header-text-size: 30px;
     
  2. 创建一个新文件theme/web/company-header.scss。在新文件中,创建一个具有选择器名称 ( .company-header)的类,并包含一个引用在步骤 1 中创建的变量的 CSS 属性。

    .company-header { font-size: $company-header-text-size; }
     
  3. 通过添加以下内容,在theme/web/main.scss 中导入新文件:

    @import “company-header”;
     

这确保了 SCSS 包含在 CSS 编译中。

2.3.2 原生环境示例

在此示例中,我们将创建一个自定义样式,该样式将在使用时更改文本的字体大小:

  1. 使用以下代码在theme/native/custom-variables.js 中添加一个 JavaScript 变量:

    export const companyHeaderTextSize = 30;
     
  2. 创建一个新文件theme/native/company-header.js。在新文件中,需要导入step中定义的新定义的变量。创建一个具有对象值的变量,其中包含fontSize引用新定义的自定义变量的值的属性,然后导出该变量。以下代码实现了这一点:

    import { companyHeaderTextSize } from “./custom-variables”;
    export const companyHeader = { fontSize: companyHeaderTextSize };
     
  3. 导入在company-header.js 中定义的对象,并在theme/native/main.js 中公开它,如下所示:

    import {companyHeader} from “./company-header”;
    module.exports = {companyHeader};
     

2.4 导入 CSS(仅限 Web)

应用程序的主题基于 SASS(.scss文件),但也可能需要来自第三方库的 CSS 文件。这可以通过将第三方库文件添加到theme/web/settings.json 中cssFiles属性来完成。

请参阅以下片段作为如何向您的应用程序添加额外 CSS 的示例。下面,添加了第三方 CSS 文件water.css并将其应用于应用程序。第三方 CSS 文件应该在theme/web 中

{
	"cssFiles": ["theme.compiled.css", "water.css"]
}
 

3 创建可重用的样式

上一节介绍了开发人员如何自定义应用程序的样式。除此之外,可以在模块中放置样式,然后可以在其他应用程序中重复使用。这可用于创建主题模块公司设计系统

向模块添加样式类似于向应用程序添加样式,不同之处在于样式资源放置在themesource文件夹中,如下面的文件和文件夹结构部分所述。

对于通用类或应该很容易发现的类,开发人员可以考虑为此创建设计属性。有关更多信息,请参阅如何扩展设计属性

4 创建主题模块

主题模块对于样式很有用,可以通过跨应用程序的模块轻松重用。默认情况下,主题设置(如颜色、字体、间距等)位于主题文件夹中,该文件夹特定于每个应用程序。但是,这些设置通常应该重新使用,以在应用程序之间创建一致的外观和感觉。

这可以通过创建一个主题模块,使theme文件夹下的custom-variables文件指向你的主题模块中的自定义变量(custom variables)。要创建完整的设计系统,请参阅如何创建公司设计系统

有关创建可重用主题模块的更多信息,请参阅下面的示例。

4.1 标记为 UI 资源模块

包含主题样式的模块应标记为 UI 资源模块。为此,请右键单击App Explorer 中的模块名称,然后单击标记为 UI 资源模块(Mark as UI resources modul)。这将为模块提供一个绿色图标,以便于将主题模块与其他模块区分开来,并且还会影响从这些模块应用样式的顺序:

绿色模块

4.2 订购 UI 资源模块

当模块包含样式 (SCSS/CSS) 时,请确保以相对于其他文件的正确顺序将其添加到已编译的 CSS 文件中。举例来说,如果一个主题模块应该覆盖中定义的造型Atlas_Core,那么要注意,主题模块必须添加 在Atlas_Core之后(根据css的生效原则)

您可以在主题设置(App Settings > Theme)中设置明确的顺序。这包含标记为 UI 资源模块的所有模块的列表,并允许您设置将它们添加到 CSS 文件的显式顺序。请注意,模块在列表中的排序越低,其优先级就越高。例如,可以按如下方式订购使用公司主题模块的应用程序:

应用主题设置

4.3 例子

4.3.1 web

例如,theme/web/custom-variables.scss 中的以下变量将被制成可重用的主题模块:

$gray-primary: #e7e7e9;

$brand-default: $gray-primary;
$brand-primary: #264ae5;
$brand-success: #3cb33d;
$brand-warning: #eca51c;
$brand-danger: #e33f4e;
 

要创建可重用的主题模块,请执行以下操作:

  1. 在 Studio Pro 中创建一个新模块。在 App Explorer 中右键点击App {name},然后点击Add module...。给它一个名字。在这个例子中,模块的名称是“mytheme”。

  2. 在您的 Mendix 应用程序目录中,创建一个新文件themesource/mytheme/web/custom-variables.scss

  1. theme/web/custom-variables.scss剪切变量并将它们粘贴到themesource/mytheme/web/custom-variables.scss 中

  2. theme/web/custom-variables.scss添加@import "../../themesource/mytheme/web/custom-variables.scss到文件的顶部,用你的模块名称替换“mytheme”。

这两个文件最终应如下所示:

theme/web/custom-variables.scss:

@import "../../themesource/mytheme/web/custom-variables.scss";
 

themesource/mytheme/web/custom-variables.scss

$gray-primary: #e7e7e9;

$brand-default: $gray-primary;
$brand-primary: #264ae5;
$brand-success: #3cb33d;
$brand-warning: #eca51c;
$brand-danger: #e33f4e;
 

您现在可以从 Studio Pro导出mytheme模块,在您的应用程序中重新使用。请注意,对于导入模块的每个应用程序,您都需要在theme/web/custom-variables.scss 中添加该@import …行。因此,我们建议您创建一个包含此更改的公司入门应用程序。

要测试所有小部件、页面模板和构建块的主题,使用创建公司设计系统中讨论的 Atlas Design System 应用程序会很有帮助。

4.3.2 移动原生

例如,theme/native/custom-variables.js 中的以下变量将被作为主题模块中可重用的变量:

export const brand = {
    primary: "#264AE5",
    success: "#3CB33D",
    warning: "#ECA51C",
    danger: "#E33F4E",
    info: "#0086D9",
    primaryLight: "#F3F5FF",
    successLight: "#F1FCF1",
    warningLight: "#FFF9E6",
    dangerLight: "#FFEEF0",
    infoLight: "#ECF9FF"
};
 

步骤:

  1. 在 Studio Pro 中创建一个新模块。在 App Explorer 中右键点击App {name},然后点击Add module...。给它一个名字,在这个例子中模块的名字是“mytheme”。

  2. 在您的 Mendix 应用程序目录中,创建一个新文件themesource/mytheme/native/custom-variables.js

  1. theme/native/custom-variables.js 中剪切导出语句和变量,然后粘贴到themesource/mytheme/native/custom-variables.js 中

  2. theme/native/custom-variables.js 中,将以下代码添加到文件顶部,将“mytheme”替换为您的模块名称:

    export * from "../../themesource/mytheme/native/custom-variables";
     

这两个文件最终应该列出以下内容:

theme/native/custom-variables.js

export * from "../../themesource/mytheme/native/custom-variables";
 

themesource/mytheme/native/custom-variables.js

export const brand = {
    primary: "#264AE5",
    success: "#3CB33D",
    warning: "#ECA51C",
    danger: "#E33F4E",
    info: "#0086D9",
    primaryLight: "#0086D9",
    successLight: "#F1FCF1",
    warningLight: "#FFF9E6",
    dangerLight: "#FFEEF0",
    infoLight: "#ECF9FF"
};
 

如果出现错误,请仔细检查导入是否指向有效文件。

5 预览样式更改

根据您正在构建的应用程序类型,样式预览或主题更改会有所不同。

5.1 web

Mendix 会监视themethemesource文件夹,以查看.scss文件中的更改。当检测到更改时,.scss文件被编译为 CSS 并且应用程序会自动重新加载(如果它正在运行),因此不需要额外的工具。有关如何编译 SCSS 的更多信息,请参阅下面的样式输出部分。

5.2 移动原生应用

Mendix 会监视themethemesource文件夹中.js文件的更改。在 Make it Native 应用程序中加载移动原生应用程序时,您将看到启用开发人员模式选项。如果未启用此设置,则在更改样式后,您可以通过三指点击重新加载应用程序。

如果启用了“Enable developer mode ”,并且在 JavaScript 样式文件中进行了更改,则应用程序会自动使用新样式重新加载。

有关更多信息,请参阅获取Make It Native 应用程序参考指南

6 文件和文件夹结构

Mendix 为应用程序的样式编辑,提供了模块化和灵活的方法。样式可以在应用级别上开发针对特定应用的样式,也可以放在模块中以供重复使用。

为了便于应用程序和模块级别的样式设计,使用了以下文件和文件夹结构;theme文件夹是用于应用特有的样式和themesource文件夹被用于可重复使用的模块的样式和资源。

下面的项目符号描述了主题文件夹和模块的文件结构:

  • theme
    • web — 此文件夹包含(PWA)Web 应用程序的应用程序特定样式资源。
      • custom-variables.scss — 该文件包含主题设置,可以通过配置轻松更改颜色、字体、间距等。
      • main.scss — 此文件是添加自定义样式的入口。
      • exclude -variables.scss — 此文件包含可以切换以选择性地排除 Atlas 核心样式的变量。
      • settings.json — 此文件包含应加载的(外部)CSS 文件。这包括 SASS 编译的 CSS 结果。
    • native — 此文件夹包含移动原生应用程序的特定于应用程序的样式资源。
      • custom-variables.js — 该文件包含主题设置,可以通过配置轻松更改颜色、字体、间距等。
      • main.js — 此文件是添加自定义样式的入口。
      • excludeVariables.js — 此文件包含可以切换以选择性地排除 Atlas 核心样式的变量。
  • themesource — 此文件夹包含特定于模块的样式和资源。每个模块都有一个文件夹,可以包含样式资源。
    • Atlas_core(必需)——来自 Atlas 核心模块的这个文件夹,它是所有 Mendix 应用程序的核心。此模块应始终是应用程序的一部分,因为其他模块依赖于此,并且它包含 Mendix 小部件的所有样式。不应更改此文件夹的内容,因为这会导致迁移/更新到较新版本时出现问题。有关从此模块禁用默认样式的信息,请参阅下面的禁用默认样式
      • web — 此文件夹(和子文件夹)包含标准 Mendix 支持的小部件的 Web 资源。
      • native — 此文件夹(和子文件夹)包含标准 Mendix 支持的小部件的移动原生资源。
    • {MODULE_NAME} — 每个模块都会创建一个文件夹,其中可以包含(PWA)web应用程序和移动原生应用程序的样式资源。
      • web — 此文件夹包含可重复使用的 Web 资源
        • main.scss — 此文件是基于 Web 的模块样式的起点。
        • design-properties.json — 此文件包含基于此模块中定义的类的现有设计属性的其他选项,或者其他设计属性。
      • native — 此文件夹包含可重复使用的移动原生资源。
        • main.js — 此文件是模块原生基于移动的样式的起点。
        • design-properties.json — 此文件包含基于此模块中定义的类的现有设计属性的其他选项,或者其他设计属性。
      • public — 此文件夹可以包含其他可重复使用的资源,例如自定义login.html页面或 Web 样式中使用的图像和字体。

7 样式输出

Mendix 应用的样式采用模块化结构,样式文件放置在不同的文件夹中。Studio (Pro) 会自动将文件合并为单个输出(Web css和原生 JavaScript),由应用程序在浏览器或设备上使用。以下部分更详细地描述了这是如何完成的。

7.1 web应用

Studio 和 Studio Pro 将不同的.scss文件按照一定的顺序组合起来,将 SASS 编译成 CSS 供浏览器使用。编译后的输出保存在名为theme-cache的文件夹中。

如果模块包含样式,例如设计系统模块,通常最佳做法是将该模块标记为 UI 资源模块。这将使在主题设置中明确设置编译顺序成为可能。有关更多信息,请参阅上面的创建主题模块部分。

.scss文件编译顺序如下:

  1. main.scss从文件themesource文件夹,具体如下:
    1. 非 UI 市场模块,按字母顺序排列。
    2. UI 资源模块,按App Settings > Theme 中的顺序排列。
    3. 非 UI 用户自定义的模块,按 Studio Pro App explorer中的顺序排列。
  2. 来自theme文件夹 ( theme/web/custom-variables.scss ) 的自定义变量
  3. main.scss来自theme文件夹 ( theme/web/main.scss )。

如果 SASS 编译失败,它将在 Studio Pro 中显示为一致性错误。此错误提供了有关出错和应修复的信息:

主题编译错误

部署时,public文件夹中的内容将复制到与theme.compiled.css文件相同的文件夹中。这允许您使用主题模块的SCSS 中的相对路径来引用这些资源。例如,要使用themesource / {模块} /public/images/login-background.jpg的图片时,你可以themesource / {模块} /web/main.scss,可以简单地使用url("./images/login-background.jpg)

请注意,public文件夹将按照编译.scss文件的相同顺序进行复制。因此,如果两个模块具有相同的公共资源,则最后一个复制的模块作为结束。

7.2 移动原生应用

对于移动原生应用程序,React Native 框架用于将所有 JavaScript 文件合并到一个文件中,使用“捆绑器bundler”负责创建用于运行应用程序的 JavaScript 包。不同模块的样式按以下顺序组合并准备好由捆绑器处理:

  1. 所有main.js从文件themesource以下顺序文件夹:
    1. 非 UI 市场模块,按字母顺序排列。
    2. UI 资源模块,按App Settings > Theme 中的顺序排列。
    3. 非 UI 用户模块,按 Studio Pro 中的顺序排列。
  2. main.js来自主题文件夹(theme/native/main.js)。
  3. 可能存在的theme文件夹中的原始样式.js ( theme/styles.js )。

如果编译期间出现错误,这些错误将显示在 Studio Pro 和 Make it Native 应用程序中。有关错误的详细信息,查看{Mendix 应用程序目录}/deployment/log/native_packager_log.txt中的本机打包程序日志会有所帮助。

有关样式化移动原生应用程序的更多详细信息,请参阅移动原生样式化参考指南。

8 从 Atlas Core 禁用默认样式

Mendix 的 Atlas 核心模块为平台支持的小部件提供样式。通常,对于每个小部件,都有基本样式来为小部件和辅助样式提供默认外观和感觉,这可以看作是附加样式和变体,可用于将小部件适应其上下文。样式可以被覆盖,但在某些情况下,最好禁用此默认样式。这可以通过使用可以在排除变量文件中设置的变量排除样式来实现。

8.1 禁用默认的 Web 小部件样式

要禁用 Web 小部件的默认样式,请打开{Mendix app}/theme/web文件夹中的exclude -variables.scss文件。此文件包含受支持的排除变量。请注意,这些变量也可以是自定义主题模块的一部分,就像创建主题模块中描述的自定义变量一样,通过使应用程序特定主题文件夹中的exclude-variables.scss文件指向中的排除变量文件你的主题模块。

以按钮小部件为例。成功按钮的默认样式如图 1 所示

图1

图 1 - 启用所有样式

要排除其他样式,例如成功按钮样式,需要禁用按钮助手样式。这可以通过将变量设置$exclude-button-helperstrue

$exclude-button-helpers: true;
 

生成的成功按钮在图 2 中可见:

图2

图 2 - 禁用helper样式

要删除完整的默认外观和感觉,需要禁用基本样式和辅助样式。这可以通过可变设定来实现$exclude-buttontrue,以及:

$exclude-button: true;
$exclude-button-helpers: true;
 

没有必要将两个变量都设置true为排除所有样式,因为在排除基本样式时,Atlas 会自动排除辅助helper样式。当缺少基本样式时,附加样式是无用的。因此,下面的配置相当于前面的:

$exclude-button: true;
$exclude-button-helpers: false;
 

生成的成功按钮在图 3 中可见。请注意,底层 Bootstrap 样式(Atlas UI 框架所基于的样式)现在已经变得可见。

图 3

图 3 - 禁用所有样式(可见的 Bootstrap 样式)

所有支持的网络排除变量是:

- $exclude-background-helpers
- $exclude-badge
- $exclude-badge-button
- $exclude-badge-button-helpers
- $exclude-button
- $exclude-button-helpers
- $exclude-check-box
- $exclude-custom-dijit-widget
- $exclude-custom-switch
- $exclude-data-grid
- $exclude-data-grid-helpers
- $exclude-data-view
- $exclude-data-picker
- $exclude-glyphicon
- $exclude-grid
- $exclude-group-box
- $exclude-group-box-helpers
- $exclude-header
- $exclude-helper-classes
- $exclude-input
- $exclude-image-helpers
- $exclude-label
- $exclude-label-helpers
- $exclude-layout-grid
- $exclude-list-view
- $exclude-list-view-helpers
- $exclude-modal
- $exclude-navigation-bar
- $exclude-navigation-bar-helpers
- $exclude-navigation-list
- $exclude-navigation-tree
- $exclude-navigation-tree-helpers
- $exclude-pagination
- $exclude-pop-up-menu
- $exclude-progress
- $exclude-progress-bar
- $exclude-progress-bar-helpers
- $exclude-progress-circle
- $exclude-progress-circle-helpers
- $exclude-radio-button
- $exclude-range-slider
- $exclude-range-slider-helpers
- $exclude-rating
- $exclude-rating-helpers
- $exclude-simple-menu-bar
- $exclude-simple-menu-bar-helpers
- $exclude-slider
- $exclude-slider-helpers
- $exclude-table
- $exclude-table-helpers
- $exclude-tab-container
- $exclude-tab-container-helpers
- $exclude-template-grid
- $exclude-template-grid-helpers
- $exclude-timeline
- $exclude-typography
- $exclude-typography-helpers
 

8.2 禁用默认的移动原生小部件样式

要禁用移动原生控件的默认样式,打开exclusionVariables.js所在的文件夹中的文件{Mendix应用} /theme/native。此文件包含受支持的排除变量。请注意,这些变量可以是自定义主题模块的一部分,就像在描述的自定义变量创建主题模块中一样,应用特定主题文件夹通过使用exclusionVariables.js,指向你的主题模块中需要排除的变量文件。

再次以按钮小部件为例。成功按钮的默认样式如图 4 所示

图 4

图 4 - 启用所有样式

要排除其他样式,例如成功按钮样式,需要禁用按钮helper样式。这可以通过将常量变量设置excludeButtonsHelperstrue

export const excludeButtonsHelpers = true;
 

生成的成功按钮在图 5 中可见。

图5

图 5 - 禁用helper样式

同样对于移动原生小部件,需要禁用基本样式和辅助样式,以删除完整的 Atlas 外观和感觉。这可以通过可变设定来实现excludeButtonstrue,以及:

export const excludeButtons = true;
export const excludeButtonsHelpers = true;
 

没有必要将两个变量都设置true为排除所有样式,因为在排除基本样式时,Atlas 会自动排除辅助样式。当缺少基本样式时,附加样式是无用的。因此,下面的配置相当于前面的:

export const excludeButtons = true;
export const excludeButtonsHelpers = false;
 

生成的成功按钮在图 6 中可见。请注意,按钮文本是白色的,因此不可见。

图 6

图 6 - 禁用所有样式(按钮文本为白色)

移动原生设备支持的所有排除变量是:

- excludeActivityIndicator
- excludeActivityIndicatorHelpers
- excludeAnimation
- excludeBackgroundImage
- excludeBadge
- excludeBadgeHelpers
- excludeBottomSheet
- excludeButtons
- excludeButtonsHelpers
- excludeCarousel
- excludeCheckBox
- excludeColorPicker
- excludeContainer
- excludeDatePicker
- excludeDropDown
- excludeFeedback
- excludeFAB
- excludeFABHelpers
- excludeImage
- excludeImageHelpers
- excludeIntroScreen
- excludeIntroScreenHelpers
- excludeLayoutGrid
- excludeLineChart
- excludeLineChartHelpers
- excludeBarChart
- excludeBarChartHelpers
- excludeListView
- excludeListViewHelpers
- excludeListViewSwipe
- excludeListViewSwipeHelpers
- excludeMaps
- excludeMapsHelpers
- excludePageTitle
- excludeProgressBar
- excludeProgressBarHelpers
- excludeProgressCircle
- excludeProgressCircleHelpers
- excludePopUpMenu
- excludeQRCode
- excludeRangeSlider
- excludeRangeSliderHelpers
- excludeRating
- excludeReferenceSelector
- excludeSafeAreaView
- excludeSlider
- excludeSliderHelpers
- excludeTabContainer
- excludeTabContainerHelpers
- excludeTextArea
- excludeTextBox
- excludeTextBoxHelpers
- excludeToggleButtons
- excludeTypography
- excludeTypographyHelpers
- excludeVideoPlayer
- excludeWebView
- excludeHelpers
 

9 自定义 index.html (Web)

默认情况下,Mendix根据应用配置生成index.html(加载以启动应用的页面)。在某些情况下,可能需要自定义此 HTML,这可以通过在theme/web文件夹中创建一个名为index.html的文件来完成。为了确保您的文件具有正确的结构,我们建议您将index-example.htmldeployment/web文件夹复制到theme/web,将其重命名为index.html,然后将其用作起点。此文件将在您至少在本地部署应用程序一次后创建。

10 自定义不受支持的浏览器 (Web)

当最终用户在不受支持的浏览器中打开 Mendix 应用程序时,会显示一个页面,指出当前浏览器不受支持,并说明可以使用哪些其他浏览器。要自定义此页面,您可以在theme/web文件夹中创建一个名为unsupported-browser.html的自定义 html 文件。如果需要,您可以将unsupported-browser.htmldeployment/web文件夹复制到theme/web文件夹,并将其用作起点。此文件将在您至少在本地部署应用程序一次后创建。

DannyChuang、Code_Dove、Ximeng
点赞
收藏
手机查看
举报
1个评论
倒序看帖
仅看楼主
    DannyChuang
    2021.12.30 17:50 发布
    #1
    终于可以在Studio pro 中可以使用Styling Editor了~~
    收费的阳光、红猪
    点赞
    评论
    举报