@xinmier/ui--words NPM

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

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

在代码中使用本组件

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

简单示例

【类 HTML】段的写法

<XmeUiWords text-snippets="为中华之崛起而奋斗！" />

<XmeUiWords :text-snippets="[ '台湾省', '是中华人民共和国', '不可分割的一部分！' ]" />

<XmeUiWords :text-snippets="{ isHTML: true, htmlText: '&copy;' }" />

<XmeUiWords :text-snippets="textSnippets4" />

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 接口

【类 HTML】标记的写法

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

TypeScript 的写法
无。

TypeScript 诸接口详解

props.textSnippets?
```
props.textSnippets?: T_Xme_UiTextConfigStatic;
```
该字段用以接受外界给出的文本片段表。
默认值为 undefined 。

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

```typescript
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;
```

props.shouldRenderDummyInDarkColor?
```
props.shouldRenderDummyInDarkColor?: boolean;
```
当外界并未给出合规的文本片段表时，本组件会呈现一个矩形的文字占位假体。该字段用以规定前述假体是否采用深色。当该字段取 true ，则假体着深色；否则，假体着浅色。
默认值为 false 。

层叠样式表接口

样式类名

【身份标识】类名：
- 根 .xme--ui-words
- 内层 .shi-ti--text-snippet
- 内层 .shi-ti--text-empty-hint
- 内层 .shi-ti--text-dummy-substitution
【状态】类名：
- 凡用以配合 .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-- 。