辛米尔标准界面组件·界面简短措辞

npm 包

npm 包之名称

@xinmier/ui--words 。

npm 包之主页

https://www.npmjs.com/package/@xinmier/ui--words。

概述

该软件是一个 npm 包，下称【本软件】。

本软件包含一个界面编程组件，面向网页开发人员，而非最终用户。又，本软件因此亦可称【本组件】。

本软件包含的界面组件，应是一个容器，容纳着简短的文本。该文本可以事先根据需要，分割为多个片段。本软件会为每一个片段构建一个单独的 <span> 。

本软件中的所有组件均采用 Vuejs 3 框架编写。仅适用于 Vuejs 3 。

用法（面向网页开发人员）

安装

本资源集服务于采用 Vuejs 框架的网页开发项目。故而，欲采用本资源集，须先自行架设一个 Vuejs 项目。

在命令行环境中，cd 进入你的网页开发项目的文件夹，并执行以下命令：

npm  i  @xinmier/ui--words

在代码中使用本组件

本组件面向网页开发人员。程序员在编写其代码时，可以采用本组件。故下方所谓用法均系介绍在编程活动中如何采用本组件。因此，所谓“用法”亦称“写法”。

简单示例

1. 【类 HTML】段的写法

   <XmeUiWords text-snippets="为中华之崛起而奋斗！" />
       
   <XmeUiWords :text-snippets="[ '台湾省', '是中华人民共和国', '不可分割的一部分！' ]" />
       
   <XmeUiWords :text-snippets="{ isHTML: true, htmlText: '&copy;' }" />
   
   <XmeUiWords :text-snippets="textSnippets4" />

2. TypeScript 段的写法

   import { ref } from 'vue'
   import { XmeUiWords } from '@xinmier/ui--words'
   import type { T_Xme_UiTextConfigStatic } from '@xinmier/lei-xing--tong-yong'
   
   const textSnippets4 = ref<T_Xme_UiTextConfigStatic>(
       [
           // 注意：下方的 `htmlText` 字段的值包含了 '&regs;' 。
           { isHTML: true, htmlText: '注册商标 “&reg;” 这一符号' },
   
           '的含义和用法究竟是怎样的呢？',
   
           '让我们一起走进法律知识的海洋，',
   
           { isHTML: false, htmlText: '来探究一番吧！' },
       ]
   )

编程接口

TypeScript 接口

1. 【类 HTML】标记的写法

   <XmeUiWords
       :text-snippets="undefined"
       :should-render-dummy-in-dark-color="false"
   />

2. TypeScript 的写法

   无。

TypeScript 诸接口详解

1. props.textSnippets?

   props.textSnippets?: T_Xme_UiTextConfigStatic;

   该字段用以接受外界给出的文本片段表。

   默认值为 undefined 。

   又， T_Xme_UiTextConfigStatic 这一类型定义来自《@xinmier/lei-xing--tong-yong》。请参阅其说明书中《折行大体可控的【界面文本配置】》一节。为便于阅读本文，我亦将这些类型之定义完整摘抄如下，只是难保下方摘抄的恒为最新一稿。

   type T_Xme_UiTextConfig_SingleTextSnippet_PlainText = string;
   
   type T_Xme_UiTextConfig_SingleTextSnippet_AllowHtmlEntity = {
       isHTML: boolean;
       htmlText: string;
   };
   
   type T_Xme_UiTextConfigStatic = (
       | T_Xme_UiTextConfig_SingleTextSnippet_PlainText
       | T_Xme_UiTextConfig_SingleTextSnippet_AllowHtmlEntity
       | Array<T_Xme_UiTextConfig_SingleTextSnippet_PlainText | T_Xme_UiTextConfig_SingleTextSnippet_AllowHtmlEntity>
   );
   
   type T_Xme_UiTextConfigGenerator = (...arguments: unknown[]) => T_Xme_UiTextConfigStatic;
   
   type T_Xme_UiTextConfig = T_Xme_UiTextConfigStatic | T_Xme_UiTextConfigGenerator;

2. props.shouldRenderDummyInDarkColor?

   props.shouldRenderDummyInDarkColor?: boolean;

   当外界并未给出合规的文本片段表时，本组件会呈现一个矩形的文字占位假体。该字段用以规定前述假体是否采用深色。当该字段取 true ，则假体着深色；否则，假体着浅色。

   默认值为 false 。

层叠样式表接口

样式类名

1. 【身份标识】类名：

   • 根 .xme--ui-words

   • 内层 .shi-ti--text-snippet

   • 内层 .shi-ti--text-empty-hint

   • 内层 .shi-ti--text-dummy-substitution

2. 【状态】类名：

   • 凡用以配合 .xme--ui-words 者：

     • .zhuang-tai--dummies-are-in-dark-colors

   • 凡用以配合 .shi-ti--text-snippet 者：

     • .zhuang-tai--looks-like-in-pure-western-language

   • 凡用以配合 .shi-ti--text-empty-hint 者：

     暂无。

   • 凡用以配合 .shi-ti--text-dummy-substitution 者：

     暂无。

重要变更

• 自 v1.0.0 版始，一切【样式类名】中：

  1. 凡【实体身份标识】类的【样式类名】，凡根级，一律以 xme-- 开头。例 .xme--led-light--style-1 。
  2. 凡【实体身份标识】类的【样式类名】，凡内层，一律以 shi-ti-- 开头。例 .shi-ti--text-snippet 。
  3. 凡表征【状态】的【样式类名】，一律以 zhuang-tai-- 开头。例 .zhuang-tai--looks-like-in-pure-western-language 。

  小结：本组件库共有三种【样式类名】前缀： xme-- 、 shi-ti-- 和 zhuang-tai-- 。