@besaitech/ng-design-system (英语)

可重复使用 角数 20 组件库sds- 前缀) 尾风 CSS v4,基于 (原始内容存档于2017-10-21). Saitech视觉语言. 按钮,输入,选择,表格,标签,手风琴,一个取枣器, 电话输入,加上应用程序外壳(上行+侧行).

重要内容: 组件的样式为存在 Tailwind 工具类 在其模板中 —— 说 软件包有 没有 舰只编译 CSS. 您的应用程序必须运行 Tailwind v4, 扫描此软件包,以及 定义设计符 (参见 尾风设置) (中文(简体) ). 没有这个步骤 组件变为无样式.

所需资源

• 角质 20.3+, 21.x或22.x (单位:千美元)@angular/common, (中文(简体) ), core, (中文(简体) ), forms, (中文(简体) ), platform-browser, (中文(简体) ), router(中文(简体) )
• 尾风 CSS 页:1 在消费应用中

1. 安装

npm install @besaitech/ng-design-system

公共npm登记——无 .npmrc,不需要瞄准镜映射和读取符号.

2. 牵引装置

角对等依赖关系( E)@angular/common, (中文(简体) ), core, (中文(简体) ), forms,)已经存在于任何 角20.3+ / 21/ 22 应用. 如果你还没有Tailwind,添加它作为一个 dev依赖:

npm install -D tailwindcss @tailwindcss/postcss

3. 尾风v4设置

这是让组件看起来正确的步骤。 尾风v4是CSS第一——没有 tailwind.config.js。 。 。 .

a. 注册 PostCSS 插件. 创建 .postcssrc.json 在您的工程根 :

{
  "plugins": {
    "@tailwindcss/postcss": {}
  }
}

b. 导入 Tailwind,扫描库并定义符号 在您的全局样式表 (单位:千美元)src/styles.css) (中文(简体) ). 这个 @source 线条是告诉 Tailwind 生成所使用的工具类 内部 图书馆,以及 @theme 块定义这些类所指的颜色/辐射 -- 两者都需要数字 :

@import "tailwindcss";

/* Generate the utilities used inside @besaitech/ng-design-system templates.
   Path is relative to THIS file (src/styles.css → ../node_modules). */
@source "../node_modules/@besaitech/ng-design-system";

/* Tokens. BOTH imports are required, and both must come AFTER the tailwindcss import —
   Tailwind v4 processes @theme in imported files and later declarations win.
   base.css = surfaces, ink, accents, status, radius, layout vars (15 tokens).
   The brand preset = the 11 --color-brand-* steps, and nothing else. */
@import "@besaitech/ng-design-system/themes/base.css";
@import "@besaitech/ng-design-system/themes/saitech.css";  /* blues */
/* @import "@besaitech/ng-design-system/themes/belvigo.css";   black */
/* @import "@besaitech/ng-design-system/themes/belvigo-emerald.css";   emerald (Belvigo merchant);
   keeps green primary fills in dark mode through the --sds-dark-* hooks listed in base.css */

/* Override any base default in your own @theme afterwards, e.g. the typeface. */
@theme {
  /* Neutrals / surfaces (already provided by base.css — shown for reference) */
  --color-canvas: #f5f6f8;
  --color-surface: #ffffff;
  --color-muted: #f8f9fb;
  --color-border: #e6e9f0;
  --color-ink: #1b2440;
  --color-ink-soft: #5b6577;
  --color-ink-faint: #8a93a6;

  /* Accent icon-tiles (foreground + soft background) */
  --color-accent-blue: #2f6bd4;
  --color-accent-blue-soft: #e8effb;
  --color-accent-green: #1f9d57;
  --color-accent-green-soft: #e6f5ec;
  --color-accent-amber: #e0902a;
  --color-accent-amber-soft: #fdf0dd;
  --color-accent-red: #df4f6b;
  --color-accent-red-soft: #fde7ec;
  --color-accent-indigo: #6c5ce7;
  --color-accent-indigo-soft: #ece9fb;

  /* Status */
  --color-success: #27c06b;
  --color-warning: #f3b73c;
  --color-danger: #df4f6b;

  /* Radius */
  --radius-control: 0.5rem;
  --radius-card: 0.75rem;

  /* Typography */
  --font-sans: "Inter", "Segoe UI", system-ui, -apple-system, sans-serif;
}

/* Layout dimensions used by <sds-shell> / <sds-sidebar> / <sds-topbar>.
   Only needed if you use the layout components. */
@layer base {
  :root {
    --sds-topbar-h: 64px;
    --sds-sidebar-w: 256px;
    --sds-sidebar-w-collapsed: 76px;
  }

  body {
    margin: 0;
    font-family: var(--font-sans);
    background-color: var(--color-canvas);
    color: var(--color-ink);
  }
}

为什么 @source尾风 v4 忽略 node_modules 默认。 明确 @source 重新包含 这个软件包,所以被烤成其所编译的模板的类产生了真正的CSS. 如果组件显示 上行(或错误的相对路径)几乎总是原因.

4. 使用组件

所有组件都是 独立 ——将您需要的直接导入到组件的 imports数字 :

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { SdsButton, SdsInput, SdsIcon } from '@besaitech/ng-design-system';

@Component({
  selector: 'app-member-form',
  imports: [FormsModule, SdsButton, SdsInput, SdsIcon],
  template: `
    <sds-input label="Nom" [(ngModel)]="name" leadingIcon="search" clearable />

    <sds-button variant="primary" (click)="save()">
      <sds-icon sdsIconLeading name="user-plus" [size]="18" />
      Créer un membre
    </sds-button>
  `,
})
export class MemberForm {
  name = '';
  save() {/* ... */}
}

表格控件( E)sds-input, (中文(简体) ), sds-textarea, (中文(简体) ), sds-select, (中文(简体) ), sds-multi-select, (中文(简体) ), sds-toggle-switch, (中文(简体) ), sds-date-picker, (中文(简体) ), sds-phone-input执行 ControlValueAccessor,所以他们与两者合作 模板驱动 ([(ngModel)])和反应性(formControlName(d) 表格.

组件目录

导入名称为 Sl… 类; 标记选择符为 sds-…。 。 。 .

控件原始( R)

复合

版式 (使用从第3步起的设计符号/布局 vars)

图表 (D3是数学的,Angular是SVG的,所以是OnPush,SSR安全并用活物来表示) a 包括: 二级进入点, (中文(简体) ), @besaitech/ng-design-system/charts数字 :

import { SdsLineChart, SdsKpi, SdsChartSeries } from '@besaitech/ng-design-system/charts'; // components + chart data types
import { provideSdsCharts, SdsChartLabels } from '@besaitech/ng-design-system';            // config + strings (root)

根入为一单元:无论应用程序在任何地方——甚至在懒惰的路线上——都使用它 应用程序的初始块。 在自己的条目中保留图表(和d3)让捆绑者把它们留在 吸引他们的页面的懒散块。 配置( E)provideSdsCharts, (中文(简体) ), SDS_CHART_CONFIG, (中文(简体) ), SdsChartConfig, (中文(简体) ), SdsChartLabels, (中文(简体) ), SDS_CHART_LABELS_EN 和标签文本类型)留在根中—— 它很小,没有d3,所以 app.config 它可以提供热心 而不拉出图表。 自兹 0.0.68 根不再再出口图表组件或图表类型.

每个图表通过访问者读取平行(一个属性名或 (row, i) => value),所以API数据 不重塑的地圖; 有交互式的传说( 颜色跟随系列, 绝不是其等级), a 键盘导航工具提示,一个数据表双(tableToggle, (中文(简体) ), loading / 空状态,和 a (pointClick) 输出。 颜色来自色盲安全 --sds-chart-1…8 插槽数 base.css (覆盖预设中的任何插槽). 设置全应用程序默认值一次 :

providers: [provideSdsCharts({ locale: 'fr-FR', labels: CHART_LABELS_FR })]
// or, switching live with the app language (both functions are read inside computed()s):
providers: [provideSdsCharts({ locale: () => lang(), labels: () => chartLabelsFor(lang()) })]

图表字符串. 每个内置字符串——空状态,表格切换和页眉,工具提示行 口语摘要、角色描述、韩国新闻社的变换句子 SdsChartLabels 键带有 英语默认值( N)SDS_CHART_LABELS_EN) (中文(简体) ). 翻译一次 provideSdsCharts({ labels }) 联合国 Partial<SdsChartLabels>,在英文默认值后合并;参数化的为函数 (单位:千美元)sliceCount(n), (中文(简体) ), gridSize(rows, columns), (中文(简体) ), labelValue(label, value), (中文(简体) ), zoomedTo(path), (中文(简体) ), versus(y, x), (中文(简体) ), sparklineSummary({ label, first, last, min, max, count }), (中文(简体) ), kpiChange({ direction, delta, period, good }),.) 逐图输入(emptyText, (中文(简体) ), otherLabel, (中文(简体) ), centerLabel, (中文(简体) ), valueLabel, (中文(简体) ), rootLabel, (中文(简体) ), sizeLabel)仍然为一个图表赢得;未设置(null(中文(简体) ) 它们会回到配置的标签.

<sds-line-chart
  heading="Admissions"
  [data]="rows"
  x="date"
  [series]="[{ key: 'urgences', label: 'Urgences' }, { key: 'programmees', label: 'Programmées' }]"
  [annotations]="[{ type: 'line', value: 150, label: 'Capacité' }]"
/>

自定义工具提示正文 : <ng-template sdsChartTooltip let-tip>…</ng-template> 在任何图表中.

丰富文本 (Tiptap / ProseMiror)——一个 二级进入点, (中文(简体) ), @besaitech/ng-design-system/rich-text, (中文(简体) ), 基于与图表相同的原因:ProseMirror留在编辑丰富文本的页面的懒散块.

import { SdsRichTextEditor, SDS_RICH_TEXT_LABELS } from '@besaitech/ng-design-system/rich-text';

释放的 HTML 通过构造是干净的 : 没有内线样式, 在启用的工具之外没有任何内容, 以及链接 限于http(s)、mailto、电话、站点路径和主机(sdsSafeHref与 rel="noopener noreferrer nofollow" ——在显示时仍保存有HTML. 表格保存为空 (无) <colgroup>,没有内含宽度)。 当装入的 HTML 持有内容时, 工具无法保存(<img>, (中文(简体) ), <iframe>页:1 没有表格 table 工具...),在任何人编辑前在字段名称下警告它——保存编辑会 放下枪 QQ/Ctrl+K 打开 链接字段,而不传递给全应用程序的QQ调色板。 字符串默认为英语: 翻译它们 每个实例 [labels] 联合国 Partial<SdsRichTextLabels>或应用宽度 { provide: SDS_RICH_TEXT_LABELS, useValue: { bold: 'Gras', … } }。 。 。 .

<sds-rich-text-editor
  label="Présentation"
  [tools]="['heading2', 'bold', 'italic', 'bulletList', 'orderedList', 'link', 'undo', 'redo']"
  [maxLength]="2000"
  formControlName="description"
/>

主题交叉应用首选项( C)

SdsThemeService 持有该人的 模式 —— 说 'system' | 'light' | 'dark',坚持 localStorage 下级 sds-theme - 并把它解决给画 主题 (单位:千美元)light编号 :dark(三); system 跟着操作系统直播. toggle() 编号 : setTheme() 设置一个明确的主题, setMode('system') 回到跟踪操作系统.

一个产品的Apps在互相链接时可以在URL中携带人物的语言和主题,所以 打开匹配的页面。 发送侧 :

import { appendUiPrefs } from '@besaitech/ng-design-system';

appendUiPrefs('https://auth.example/continue#token=abc', { lang: translate.getCurrentLang(), theme: theme.mode() });
// → https://auth.example/continue?lang=fr&theme=dark#token=abc

永远不要把它们放入一个被嵌入的重定向服务器匹配的精确位置( N)return_to, (中文(简体) ), redirect_uri)——附后 外部 URL 。 接收侧: 内含脚本 <head> 联 合 国 index.html 应用、坚持和剥去 在第一次油漆之前 (没有闪出,也没有导入根部的此库). LANG_KEY 应用程序是自己的 语言存储密钥; 保存 LANGS 与应用程序的语言同步. readUiPrefs 编号 : stripUiPrefs 一样 代码和测试的逻辑.

<script>
  (function () {
    var LANG_KEY = 'app.lang', LANGS = ['en', 'fr', 'nl'], THEME_KEY = 'sds-theme', MODES = ['system', 'light', 'dark'];
    var url = new URL(location.href), q = url.searchParams, lang = q.get('lang'), mode = q.get('theme');
    try {
      if (LANGS.indexOf(lang) >= 0) localStorage.setItem(LANG_KEY, lang);
      if (MODES.indexOf(mode) >= 0) localStorage.setItem(THEME_KEY, mode);
    } catch (e) {}
    try { lang = localStorage.getItem(LANG_KEY) || lang; mode = localStorage.getItem(THEME_KEY) || mode; } catch (e) {}
    if (LANGS.indexOf(lang) >= 0) document.documentElement.lang = lang;
    var dark = mode === 'dark' || (mode !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches);
    document.documentElement.classList.toggle('dark', dark);
    document.documentElement.style.colorScheme = dark ? 'dark' : 'light';
    if (q.has('lang') || q.has('theme')) {
      q.delete('lang'); q.delete('theme');
      history.replaceState(history.state, '', url.pathname + url.search + url.hash);
    }
  })();
</script>

标签语言( L)

图书馆的船 没有自己的翻译每一个可见或口语串——占位符, 空状态、 校验信件和可访问的仅图标按钮名称 – 是使用 a 一个 英语默认 (自0.0.54起;更早的发布默认了一些组件为法语). 应用程序 服务于一种以上语言的,约束其翻译,例如:. <sds-select [placeholder]="'common.select' | translate" [clearLabel]="'common.clear' | translate" />。 。 。 . 地方意识部分 locale 输入 : sds-date-picker编号 :sds-calendar (每月和平日名称, 默认 en-GB, (中文(简体) ), sds-input-number 财务报告和审定财务报表 sds-table (数目/货币格式), sds-phone-input (国家名称通过 Intl.DisplayNames; 空 = 内置英文名.

解决问题

版本

塞姆维尔。 工作空间发布每个版本 npm run release:lib (弹出-建) (原始内容存档于2017-03-25). Publishing. 在你的应用中刻意地打出一个版本.