@wulechuan/controllers-of-enum-dictionaries
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

吴乐川的〔字典机〕与〔字典群之总机〕

中国人——特别是汉族人,理应坚持广泛、规范地使用汉语。凡非必要之情形不说外国话、不用外国字。此乃天经地义!然则每当必要,亦不排斥采用外国之语言。不妨 博世界之学问,养中国之精神

本人亦支持少数民族坚持采用自己民族的传统语言。仍须强调,凡中国人,皆应会用汉语、积极使用汉语,此乃中华各民族之大一统之必由。

NPM 页

NPM 包名

@wulechuan/controllers-of-enum-dictionaries

作者

南昌吴乐川

源代码仓库

提供仓库服务之组织 仓库组织之国别 仓库地址
码云 中华人民共和国 https://gitee.com/nanchang-wulechuan/wulechuan-typescript-controllers-of-enum-dictionaries.git
阿里云之代码仓库 中华人民共和国 https://code.aliyun.com/wulechuan/wulechuan-typescript-controllers-of-enum-dictionaries.git
GitHub https://github.com/wulechuan/wulechuan-typescript-controllers-of-enum-dictionaries.git

综述

言简意赅版

此乃吴乐川的《【字典群】之管理工具集》。本工具集对外提供唯一的主接口函数,名为 作一字典群之总机 ,用以构建一个所谓【字典群之总机】以管理一个【字典群】。一个【字典群】可创建并管理多个【字典】。

并且,本工具集要求诸【字典】各自为其自身一切【条目】的【原式】构造出统一的所谓【视式】,以便在界面代码(例如 Vuejs 的模板)中统一采用。又,构造【原式】、【视式】之方法通常因【字典】而异,故均须开发者提供。

冗长版

在开发各类应用时,开发者几乎总会遇到这样一类问题——管理各色所谓【字典表】。本工具集称【字典表】为【字典】。

所谓【字典】与所谓【字典机】

一个【字典】存放着可枚举的若干【字典条目】,简称【条目】。于任何给定的【字典】,其内一切【条目】之数据形态须完全一致。 这也是实践中的惯常做法。鄙人从未见有某【字典】包含的【条目】形态各异之情形。

又,于客户端应用而言,每个【条目】至少有两个形态:鄙人所谓【原式】与【视式】。

所谓某条目的【原式】,即指该【条目】由【网络请求之响应】、【数据库】等数据来源提供的原始形式。惯常多见的、采用外国语的形式例如:

{
    id: 1,
    label: '甲',
}

{
    uuid: 'abcdef1234567890',
    displayName: '子',
}

由上述两例可见,虽然某给定的【字典】内一切【条目】均须采用完全相同的数据形态,但于不同的两个【字典】,其【条目】之数据形态可能迥异,或则说,二者【条目】之所谓【原式】可能迥异。

任凭多个【字典】之【条目】之【原式】可能迥异,每当将这些【字典条目】运用在用户界面代码(例如 Vuejs 的模板)中时,我们希望一切【字典】的一切【条目】均有统一的格式。一旦统一,既可提高界面代码之可重用性,又可减少因人为疏忽而引发之软件故障。由此,鄙人提出所谓【视式】的概念。

所谓【字典条目】的【视式】,即是为一切【字典】的一切【条目】设计的统一标准形式。 因其首要用途是用作该【条目】在界面中的视觉表达,故名。

注:在本工具集之酝酿期间,所谓【视式】一度称为【界面标准式】、【示式】。最终定名【视式】。

恰因诸【字典】的【原式】可能迥异,实践中,开发者须为每一个【字典】的每一个【条目】逐一构造其【视式】。

又,在编程实践中,开发者有时希望某【字典】的一切【条目视式】各自携带额外的数据字段。例如,开发者可能为某些【字典】的【条目视式】增设名为 负载payload 的字段。由此可见,严格而言上文所谓统一标准【视式】实际上是各色真实【视式】的公共字段的最小集。或者说,所谓统一标准【视式】是各色真实【视式】的 【最简式】

于本工具集,统一标准【视式】(亦即【最简式】)确定如下:

export interface 范_字典条目之视式_最简式<范_字典条目之值 = any> {
    唯一标识: 范_字典条目_唯一标识;
    呈示称谓: string;
    : 范_字典条目之值;
}

由所谓【原式】与【视式】这一对概念,自然引出了操纵某【字典】的任务之一:允许开发者给出从该【字典】任何【条目】之【原式】转换得到对应【视式】的办法。落实到编程代码时,该“办法”即为一个回调函数。例如:

function 开发者为某字典给出的条目转换方案 (某条目之原式) {
    const { id, label } = 某条目之原式

    const 该条目之视式 = {
        唯一标识: id,
        呈示称谓: label,
        : id,
        负载: 某条目之原式,
    }

    return 该条目之视式
}

至于在本工具集中应用上述回调函数的具体方法,见下文《【字典群之总机】可制作一批新【字典机】》。

又,在编程实践中,开发者常常遇到某【字典条目】的【唯一标识】与【呈示称谓】互查的编码任务。例如,已得到某【条目】之 iduuid 之类的【唯一标识】,须求该【条目】之 labeldisplayName 之类的字段,亦即求其【呈示称谓】。因此,【字典】不但应保有其一切【条目】(【原式】与【视式】),还应提供一些【条目内容映射表】。所谓【条目内容映射表】,目前共有两种,均为哈希表:

  1. 一种是以【唯一标识】为【键】,以对应【呈示称谓】为【值】的键值对集。

  2. 另一种则相反,是以【呈示称谓】为【键】,以对应的【唯一标识】为【值】的键值对集。

又,在编程实践中,当运用【字典】时,开发者偶尔遇到这样的技术要求:

  • 在该【字典】固有的一切【条目】之集上补充一个特殊的、“抽象”的【条目】,该特殊【条目】代表着最终用户对该【字典】中的一切【条目】“全都选中”、“全都采用” 或 “全都勾选” 。

  • 在该【字典】固有的一切【条目】之集上补充一个特殊的、“抽象”的【条目】代表 “全都不选”、“全都不用” 或 “全都不勾选” 。

上述两个特殊【条目】可能仅取其一,亦可两者并存。

又,依照多数实践中的做法,这些特殊条目不应由存放【字典】的原始数据源(例如数据库)提供。因此,本工具集要求任何【字典】均允许额外配置(或者说“携带”、“保有”、“持有”)上述两种特殊的【条目】。

又,凡用以操纵单个【字典】之工具,我称之为【字典机】。 落实到编程代码时,【字典】的一切数据和功能由【字典机】保有和体现,即是说【字典】在代码层面不能游离于【字典机】而“凭空”存在。本文中,当不影响理解时,为便于表述,【字典】与【字典机】两个词偶尔会混用,即互为替代。

所谓【字典群之总机】

又,一个应用中涉及的【字典】往往不止一个。因此本工具集设计了所谓【字典群】,用以包含多个【字典】。操纵该【字典群】即可对这些【字典】统而管之

又,凡用以操纵【字典群】之工具,我称之为【字典群之总机】,简称【总机】。 落实到编程代码时,【字典群】的一切数据和功能由【字典群之总机】保有和体现,即是说【字典群】在代码层面不能游离于【字典群之总机】而“凭空”存在。

主接口之概述

本工具集提供一个主接口。它是一个工厂函数,用以创建【总机】。创建的【总机】自带某些行为,用以(成批)创建和管理其所辖诸【字典机】。

小结

  • 任何一个【字典机】有以下主要任务或功能:

    1. 【字典机】可产生或取得其一切【条目】之【原式】。且该任务可以按需反复执行,以令该【字典】按需反复重建一切数据。

      实践中,不同的【字典】构建其【条目】之【原式】的办法各不相同。多见是凭借某 XHR 过程获取。当然也可以由写死的代码直接生成。总之,任何【字典】均可以订制其构建自身一切【条目】之【原式】的办法。

      参见下文《【字典群之总机】之功能及用法]》中的《【字典群之总机】可制作一批新【字典机】》。

    2. 【字典机】应保有并对外提供其一切【条目】之【原式】。若有必要,还额外保有两个特殊【条目】,分别代表“全选”和“全都不选”。

    3. 【字典机】应可依据开发者的设定,自动将其一切【条目】之【原式】转换成对应的【视式】,再将其一切【条目】之【视式】单独存放并对外提供。典型的,【视式】供界面代码使用。

    4. 【字典机】应保有并对外提供两种【条目内容映射表】。

  • 任何一个【字典群之总机】保有和管理零个、一个或若干个【字典机】。并可(成批)创建新的【字典机】。

  • 本工具集提供一个主接口。它是一个工厂函数,用以创建【字典群之总机】。【字典机】须由【总机】创建和管理。


术语

术语概述

本文有少数概念较为关键。为减少乃至消除歧义,先为各概念约定术语。部分术语为本人之拙见,未必见于其他文章或材料。

术语表

  1. 术语【接口全貌】

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 signature 一词来表达“某函数的接口格式“这一含义。本工具集及其配套文档则坚持称其为【接口全貌】。

  2. 术语【期待】

    本工具集及其配套文档将所谓 Promise 译为【期待】,而非〖承诺〗。

    又,【期待】可【落实】(外国话是 resolved)。

    又,【期待】可【落空】(外国话是 rejected)。

    又,【期待】之【落实】或【落空】统称为【落定】(外国话是 settled)。

    例:

    const 期待_某事落定: Promise<void> = new Promise(
        function (落实之, 落空之) {
            setTimeout(落实之, 1234)
        }
    )
  3. 术语【Vuejs 部件】

    本文所谓【Vuejs 部件】中的【部件】,对应一般文档中的〖组件〗一词,外国语是 component 。本工具集及其配套文档坚持称【Vuejs 部件】,有时简称【部件】。

  4. 术语【唯一标识

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 iduuidkey 等单词(或短语)来表达“某数据实体之唯一标识”这一含义。本工具集及其配套文档则坚持采用【唯一标识】这一汉语短语来代替它们。

    该汉语短语既用于相关描述本文,也用于编程代码中各属性、变量之命名。

  5. 术语【呈示称谓

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 labelnamedisplayNamecaption 等单词或短语来表达“用以呈示在界面上的文本”这一含义。本工具集及其配套文档则坚持采用【呈示称谓】一词来代替它们。

    该汉语短语既用于相关描述本文,也用于编程代码中各属性、变量之命名。

  6. 术语【范】

    所谓【范】,对应 TypeScript 或 JSDocs 概念中的 type 。一般译为〖类型〗。但本工具集及其配套文档坚持称【范】。例如:

    • TypeScript

      export type 范_字典_唯一标识 = string;
      export type 范_字典条目_唯一标识 = string | number;
      
      export interface 范_字典条目之视式_最简式<范_字典条目之值 = any> {
          唯一标识: 范_字典条目_唯一标识;
          呈示称谓: string;
          : 范_字典条目之值;
      }
    • JSDocs

      /**
       * @typedef {string} 范_字典_唯一标识
       */
      
      /**
       * @typedef {string | number} 范_字典条目_唯一标识
       */
      
      /**
       * @typedef {object} 范_字典条目之视式_最简式
       * @property {范_字典_唯一标识} 唯一标识
       * @property {string} 呈示称谓
       * @property {any} 值
       */
  7. 术语【范】之【形参准用式】与【完备式】

    当某工厂函数(称【甲】)构造某对象(称【乙】)时,【甲】往往接受至少一个实参,称【丙】。即,【甲】依据【丙】构造出【乙】。

    多数情形下,【乙】、【丙】看似结构高度相似乃至完全相同,但往往【乙】要求其大部分字段始终存在,而【丙】允许若干字段(乃至所有字段)缺省。故在借助 TypeScript 语言定义【乙】、【丙】二者之【范】时是有区别的。

    实践中,常见的案例类似如下情形:

    type 范_乙 = {
        : number;
        : string;
        : boolean;
        : () => void;
    };
    
    type 范_丙 = Partial<范_乙>;

    总之,用于函数参数的【范】与用于最终构建结果的【范】不完全等同。甚至可能迥异。但从功能、用途等层面主观理解,二者又颇有联系(或则说渊源),开发者为二者命名时也可能倾向于采用近同之字眼。由是,鄙人主张,二者之【范】之命名主体采用完全相同的字眼或短语,仅补以后缀作为区别。其中:

    • 凡用于某函数参数者,称为【形参准用式】,其【范】之名称后缀为 _形参准用式
    • 凡用于产出的所谓“实用”数据者,称为【完备式】,其【范】之名称后缀为 _完备式

    据此命名规则,上例可改写如下:

    type 范_某物_完备式 = {
        : number;
        : string;
        : boolean;
        : () => void;
    };
    
    type 范_某物_形参准用式 = Partial<范_某物_完备式>;
  8. 术语【形制要求】、【形制要求集】与【形制项集】

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 option 或其复数 options 、或者 configconfigurationsettings 等词来表达“可配置项”、“选项”之类的含义。本工具集及其配套文档则采用【形制要求】一词表述它们。并且,在为相关常量、变量命名时,采用【形制要求集】或其变形(如【形制要求总集】、【形制要求杂集】、【形制杂集】和【形制杂项集】)等汉语短语来代替它们。

    一般的,在某函数的参数中,如果某【形制要求】之结构较为简单,为其命名时鄙人倾向于采用【形制要求集】一词。如果某【形制要求】之结构较复杂,类似 eslint 、 vue.config 等,鄙人则会采用【形制要求总集】一词。

    又,在所谓“实用”对象中的【形制要求】,为其命名时鄙人倾向于采用【形制杂集】和【形制杂项集】等词。

  9. 术语【还应持有】与【所持

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 data 一词表达“数据”之含义。偶见采用其单数形式 datum 。本工具集及其配套文档则采用【还应持有】和【所持】两个词代替它们。该二词既用于相关描述本文,也用于编程代码中各属性、变量之命名。

    一般的,在某函数参数中的数据配置,为其命名时鄙人倾向于采用【还应持有】一词。

    又,在所谓“实用”对象中的数据配置,为其命名时鄙人倾向于采用【所持】一词。

    例:

    const 某字典 = {
        所持: {
            字典特别条目_其代表全选者: null,
            字典特别条目_其代表全都不选者: null,
            该字典诸条目之原式_其列表: [],
            该字典诸条目之视式: {
                其列表: [],
                其哈希表: {},
            },
            // ……其它【所持】的属性从略。
        },
        // …… 其它属性从略。
    }
  10. 术语【诸事之应对】与【应对

    迄今在传统的编程劳动中,中国的开发者多半习惯采用外国语 event handler 这一短语来表达“事件处理程序”、“事件处理函数”之类的含义。本工具集及其配套文档则采用【诸事之应对】和【应对】两个汉语词(或汉语短语)来代替它们。

    此二者既用于相关描述本文,也用于编程代码中各属性、变量之命名。

    一般的,在某函数参数中的事件处理函数集,为其命名时鄙人倾向于采用【诸事之应对】一词。

    又,在所谓“实用”对象中的事件处理函数集,为其命名时鄙人倾向于采用【应对】一词。

    注:采用【应对】一词,一来是因为其短于【事件处理程序】一词,二来是因为“应对”是动词,其后带出具体的程序名称,更贴近汉语习惯。例如:某字典.应对.该字典每次数据重建后()

  11. 术语【字典】与【字典条目】

    见前文《本工具集之综述·冗长版》。

  12. 术语【标准字典】与【特异字典】

    【标准字典】与【特异字典】概述

    在真实的应用中,可能涉及若干个【字典】。其中一些【字典】采用的【条目】之【原式】类同,甚至恰好完全一致。另有一些【字典】其【条目】则采用独特的【原式】。

    例如,某假想应用中有【人员角色】、【甲种产品之所有型号】和【乙种产品之所有型号】三种【字典】。又假设其中【人员角色】字典的【条目】之【原式】之【范】如下:

    type 范_字典条目_人员角色_其原式 = {
        roleId: string;
        roleCategory: string;
        roleName: string;
    }

    且假定【人员角色】各候选条目的称谓应为 roleCategoryroleName 组合拼接而成的文本。

    又,假设于所有产品之型号之【字典】,其诸【条目】之【原式】之【范】均相同,如下:

    type 范_字典条目_任何产品_其原式 = {
        productCate: string;
        modelId: string;
        displayName: string;
    }

    不难理解,于上述两类【字典】,将其【原式】转换为【视式】的办法是有区别的。但特定于所有产品之型号之【字典】,它们的转换办法恰好完全相同。既然完全相同,我们希望统一处理这些【字典】之【原式】,得到其它数据,例如诸条目之【视式】,又如该【字典】 所持字典条目诸内容映射表之集

    由此,我们定义,在给定的【字典群】中,若有一组【字典】恰好采用了类同的甚至完全一致的【条目】之【原式】,则可认定这些【字典】为所谓【标准字典】。凡不认定为【标准字典】的【字典】,不妨称为【特异字典】。

    须知,一个应用中可能构建若干个【字典群】。例如,每个页面一个,或每一群类同的页面共用一个。如何设计和采用【字典群】完全是自由的。但之于任何给定的【字典群】,开发者可以任意认定哪些【字典】是该【字典群】中的所谓【标准字典】,其余是【特异字典】。换句话说,同一应用中,不同【字典群】认定的所谓【标准字典】也可以是各不相同的。

    例如,某假想应用中有【性别】、【政治面貌】、【户籍类别】、【学历】和【学位】等【字典】,又有若干种产品的【型号】字典。开发者完全可以仅构建一个【字典群】。但不少开发者可能倾向于构建两个独立的【字典群】,如下:

    1. 【人员信息字典群】,包含【性别】、【政治面貌】、【户籍类别】、【学历】和【学位】等【字典】。
    2. 【产品型号字典群】,包含各种产品的【型号】【字典】。

    倘若确实如上构建了两个独立的【字典群】,那么不难想象,这两个【字典群】各自有各自的所谓【标准字典】。且两种【标准字典】的【条目】完全可能采取迥异的【原式】之【范】。

    在程序代码中如何认定并统一处理所谓【标准字典】

    设计所谓【标准字典】之概念,是为了统一处理它们,简化开发任务。具体有以下两种统一的任务:

    1. 任何给定的【字典群之总机】,均可在其 诸事之应对 中配置 内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法 函数。

      当该【总机】确实配置了该函数时,如果该【总机】所辖某【字典机】没有给出独用的 凭字典条目原式之集构建诸字典条目内容映射表 函数,则该【字典机】在处理其数据时会自动采用【总机】提供的“默认做法”。此时,该【字典机】被视作所谓【标准字典】。

      每当某【字典机】配置了 凭字典条目原式之集构建诸字典条目内容映射表 函数时,该函数由该【字典机】独享,且该【字典机】不会采用由【总机】提供的“默认做法”。

    2. 任何给定的【字典群之总机】,均可在其 诸事之应对 中配置 内任何所谓标准字典_凭某条目之原式构建其视式_默认做法 函数。

      当该【总机】确实配置了该函数时,如果该【总机】所辖某【字典机】没有给出独用的 凭某条目之原式构建其视式 函数,则该【字典机】在处理其数据时会自动采用【总机】提供的“默认做法”。此时,该【字典机】被视作所谓【标准字典】。

      每当某【字典机】配置了 凭某条目之原式构建其视式 函数时,该函数由该【字典机】独享,且该【字典机】不会采用由【总机】提供的“默认做法”。

    由此还可以看出,虽然本工具集创造了所谓【标准字典】之概念,但鄙人并没有在【字典机】的【形制要求集】中设计任何真实的字段用以标记或表征该【字典机】之【字典】是否为所谓【标准字典】。一个【字典】是否为所谓【标准字典】,仅“暗中”取决于它是否采用【总机】提供的“默认做法”。 通俗地讲,在 JavaScript 层面(而非 TypeScript 层面,见下文)没有任何字段用以区别所谓【标准字典】和【特异字典】。二者完全在开发者内心界定。

    在 TypeScript 语言中处理【标准字典】的注意事项

    由上文可知,在 JavaScript 层面没有任何字段用以区别所谓【标准字典】和【特异字典】。

    然而,在采用 TypeScript 语言进行编程时:

    • 倘若某【总机】中确实存在所谓【标准字典】,则这类【字典】的【条目原式】之【范】必定存在,且开发者应该明确给出该【范】。换言之,该【总机】的【范_该总机_所谓标准字典_条目原式】不会是 never
    • 否则,该【总机】仅包含各色【特异字典】,它们形态各异。由此,该【总机】的【范_该总机_所谓标准字典_条目原式】应作 never 为宜(虽然为 any 亦可)。
  13. 术语【原式】与【视式】

    特定于本工具集,目前仅【字典条目】涉及所谓【原式】与【视式】这两个概念。

    见前文《本工具集之综述·冗长版》。

  14. 术语【字典机】

    见前文《本工具集之综述·冗长版》。

  15. 术语【字典群】与【字典群之总机】

    见前文《本工具集之综述·冗长版》。

用法(针对最终用户而非开发者)

无。

本工具集仅为诸应用提供“幕后”之技术或功能,并不直接面对任何应用的最终用户。

用法(针对开发者)

安装

npm  i  @wulechuan/controllers-of-enum-dictionaries

编程用法概述

各【部件】、【零件】关系之扼要

注:此处【部件】并非指代【Vuejs 部件】,而是指代本工具集提供的或构造出的各个功能块。它们多为函数或对象。

  • 本工具对外提供的唯一接口乃是一工厂函数,名曰 作一字典群之总机。每调用一次,创建一个【字典群之总机】。

    实际上,本工具也对外提供了用以构建单个【字典机】的工厂函数。但不建议手工调用(或者说人为调用)它。它应由某【总机】自动按需调用。

    因此,鄙人“佯装” 作一字典群之总机 是“唯一的”对外接口。

  • 任何【字典群之总机】包含并管理零个、一个或若干个【字典机】。并可成批创建【字典机】。

    【总机】保有诸【字典机】时,有两种数据结构。一种称 其列表 ,是一个列表(Array)。另一种称 其哈希表 ,是一个 JavaScript 对象(键值对)。

  • 任何【字典机】包含和管理唯一的【字典】。【字典机】不能脱离【总机】而单独存在,【字典机】总是隶属于某【总机】。

  • 任何【字典】可保有以下数据:

    • 一切【条目】之【原式】。

    • 一切【条目】之【视式】。

      【字典】保有【条目视式】时,采用两种数据结构。一种称 其列表 ,是一个列表(Array)。另一种称 其哈希表 ,是一个 JavaScript 对象(键值对)。

    • 两种【条目内容映射表】。一种是 从呈示称谓至值 。另一种是 从值至呈示称谓

制作【字典群之总机】

见本文之下列内容:

另见下文《应用示范集》。

制作【字典机】

见本文之下列内容:

另见下文《应用示范集》。

各【部件】之功能及用法

【字典群之总机】之功能及用法

于某给定的【字典群之总机】(简称【总机】),开发者可有以下动作。

  1. 【字典群之总机】可制作一批新【字典机】

    开发者可令【字典群之总机】制作一批新【字典机】,并追加到该【总机】所辖的【字典机】集中。此亦即制作了一批新【字典】。

    须知,空空如也的【字典】没有实用价值。【字典】须保有若干【条目】。且每个【条目】至少有【原式】和【视式】两种。一般的,【条目】的【视式】由【原式】转换而得。那么,这些【条目】的【原式】又从何而来?

    实践中,【字典】构建其【条目原式】的办法各不相同。多见是凭借某 XHR 过程获取。当然也可以由写死的代码直接生成。但无论怎样,本工具集将这些办法(或者说动作)统称为“数据构建”,简称“构建”。落实到编程代码时,则又改称“重建”而非“构建”。不论某【字典】是否首次构建其数据,均统称“重建”。

    做法:

    const 期待_新建的诸字典之数据构建任务均已落定 = 某字典群之总机..制作一批新字典(
        一批字典机之形制要求总集之列表
    )
    
    期待_新建的诸字典之数据构建任务均已落定.then(function () {
        console.log('所有本批次新建的字典中,凡须自动构建数据者均已成功构建了数据。')
    }).catch(function (本批次数据构建任务中一切异常之列表) {
        console.log('虽然本批次所有字典均已制造完毕,但其中须自动构建数据者,有部分在数据构建过程中出错。')
    })

    其中,实参 一批字典机之形制要求总集之列表 是一个列表(Array)。该列表的每个成员都是用以构造一个【字典机】的【形制要求总集】对象。该【形制要求总集】之【范】较冗长,不便阅读、理解。故不妨先给出其常量形式。常量形式相对于完整定义显得较为简略,可以辅助观察和理解。常量形式如下。

    又,下方常量形式中各字段之取值并非其默认值,而是随意值。

    const 用以构造某字典机的形制要求总集 = {
        该字典之唯一标识: '字典甲',
    
        该字典机的调试信息之详尽等级: 2,
    
        形制要求杂集: {
            该字典构建诸字典条目内容映射表之方案: '从该字典之诸条目原式之集提取而得',
            该字典在默认情形下不参与字典群总机发起的数据重建任务: false,
            应构建字典条目之视式之哈希表: true,
        },
    
        还应持有: {
            字典特别条目_其代表全选者: {
                应位于候选列表之该处: '首部',
                字典条目之视式: { 唯一标识: '-1', : -1 },
                当正常候选项个数为零时仍允许采用本特别项: false,
            },
    
            字典特别条目_其代表全都不选者: {
                应位于候选列表之该处: '首部',
                字典条目之视式: { 唯一标识: '-2', 呈示称谓: '- 全都不采用 -', : -2 },
            },
        },
    
        诸事之应对: {
            构建该字典所有条目之原式 (总机, 该字典机自身, 第三个参数搜集了从该字典机自身的_重建数据_函数传递过来的实参列表) { /* 函数体从略。 */ },
            凭某条目之原式构建其视式 (某条目_其原式) { /* 函数体从略。 */ },
            脱离字典条目原式之集构建诸字典条目内容映射表 () { /* 函数体从略。 */ },
            凭字典条目原式之集构建诸字典条目内容映射表 (该字典_诸条目原式_其列表) { /* 函数体从略。 */ },
            该字典每次数据重建后 (总机, 该字典机自身) { /* 函数体从略。 */ },
        },
    }

    用以构造一个【字典机】的【形制要求总集】之【范】之完整定义如下。

    export type 范_单个字典构建诸字典条目内容映射表之方案 = (
        | '不必构建'
        | '从该字典之诸条目原式之集提取而得'
        | '脱离该字典之诸条目原式之集而构建,仅一次即可'
        | '脱离该字典之诸条目原式之集而构建,且须反复构建'
    );
    
    
    
    export type 范_字典机_形制要求总集_形参准用式<
        范_该字典机_其This = any,
        范_该字典_条目原式 = any,
        范_该字典_条目视式 extends 范_字典条目之视式_最简式 = 范_字典条目之视式_最简式<any>,
    > = {
        该字典之唯一标识: string;
    
        该字典机的调试信息之详尽等级?: number;
    
        形制要求杂集?: {
            该字典构建诸字典条目内容映射表之方案?: 范_单个字典构建诸字典条目内容映射表之方案;
    
            /**
             * 有些【字典】之【字典条目】依赖于其它变量,须临时反复构建。
             * 且此种【字典】往往不必在模块加载初始时构建。
             *
             * 例如,假设有【中标企业】和【已参选的投标企业】两种字段。
             * 其中,【中标企业】须在【已参选的投标企业】中选择。
             * 故【中标企业】对应的候选列表【字典】应根据【已参选企业】这一字段的值来临时构建。
             */
            该字典在默认情形下不参与字典群总机发起的数据重建任务?: boolean;
    
            /**
             * 该所谓 “逆向” 哈希表用途不广,不及列表形式。故默认不构建该哈希表,以节省计算。
             * 但为了简化 “防卫性” 代码,即便不构建该哈希表,本工具仍令该哈希表之取值为 {} ,而非 null 。
             */
            应构建字典条目之视式之哈希表?: boolean;
        };
    
        还应持有?: {
            字典特别条目_其代表全选者?:
                null | {
                    应位于候选列表之该处: '首部' | '尾部';
                    字典条目之视式: 范_该字典_条目视式;
                    呈示称谓?: string;
                    当正常候选项个数为零时仍允许采用本特别项: boolean;
                };
    
            字典特别条目_其代表全都不选者?:
                null | {
                    应位于候选列表之该处: '首部' | '尾部';
                    字典条目之视式: 范_该字典_条目视式;
                    呈示称谓?: string;
                };
        };
    
        诸事之应对?:
            Partial<
                构建该字典所有条目之原式: (
                    this: 范_该字典机_其This,
    
                    该字典所属字典群之总机:
                        范_字典群之总机<
                            范_该字典机_其This,
                            any,
                            any
                        >,
    
                    该字典机:
                        范_字典机<
                            范_该字典机_其This,
                            范_该字典_条目原式,
                            范_该字典_条目视式,
                        >,
    
                    参数表_用以获取字典诸条目之原式: any[]
                ) => Promise<Array<范_该字典_条目原式>>;
    
                凭某条目之原式构建其视式: (
                    this: 范_该字典机_其This,
                    该字典_某条目之原式: 范_该字典_条目原式
                ) => 范_该字典_条目视式;
    
                脱离字典条目原式之集构建诸字典条目内容映射表?: (
                    this: 范_该字典机_其This,
                ) => Promise<范_字典条目诸内容映射表之集<范_该字典_条目视式['值']>>;
    
                凭字典条目原式之集构建诸字典条目内容映射表?: (
                    this: 范_该字典机_其This,
                    该字典_诸条目原式_其列表: Array<范_该字典_条目原式>
                ) => Promise<范_字典条目诸内容映射表之集<范_该字典_条目视式['值']>>;
    
                该字典每次数据重建后?: (
                    this: 范_该字典机_其This,
    
                    该字典所属字典群之总机:
                        范_字典群之总机<
                            范_该字典机_其This,
                            any,
                            any
                        >,
    
                    该字典机:
                        范_字典机<
                            范_该字典机_其This,
                            范_该字典_条目原式,
                            范_该字典_条目视式,
                        >,
                ) => void;
            >;
    };

    制作【字典机】时,须满足一些必要条件。如下:

    1. 因为【字典机】须构建其一切【条目】之【原式】,所以在创建任何一个【字典机】时,必须至少给出下列二者之一

      1. 该【字典机】独享的 凭某条目之原式构建其视式 函数。
      2. 【总机】给出所谓诸【标准字典】共享的 内任何所谓标准字典_凭某条目之原式构建其视式_默认做法 函数。

      于任何给定的【字典机】,若以上二者均已给出,则该【字典机】构建其自身一切【条目】之【原式】时采用前者。即,采用其独享的 凭某条目之原式构建其视式 函数。

    2. 因为【字典机】须构建两种【条目内容映射表】对象,所以在创建任何一个【字典机】时:

      1. 若该【字典机】不是所谓【标准字典】,且该【字典机】的 形制杂项集该字典构建诸字典条目内容映射表之方案 取文本值 '脱离该字典之诸条目原式之集而构建,仅一次即可', 或文本值 '脱离该字典之诸条目原式之集而构建,且须反复构建' ,则该【字典机】必须给出 脱离字典条目原式之集构建诸字典条目内容映射表 函数。

      2. 若该【字典机】不是所谓【标准字典】,且该【字典机】的 形制杂项集该字典构建诸字典条目内容映射表之方案 取文本值 '从该字典之诸条目原式之集提取而得' ,则该【字典机】必须给出 凭字典条目原式之集构建诸字典条目内容映射表 函数。

      3. 若该【字典机】应视为所谓【标准字典】,则【总机】须给出 内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法 函数。

    参阅上文《术语【标准字典】与【特异字典】》。

    另见下文《应用示范集》。

    刚一创建的【字典机】,并不会一定会构建其【条目原式】等数据。其数据构建与否,系由该【字典机】之【形制要求总集】中的【形制要求杂集】中的布尔量【该字典在默认情形下不参与字典群总机发起的数据重建任务】决定。若该布尔量取 false ,且该【字典机】确实构建成功,则该【字典机】即刻自动开始其“数据构建”任务。否则,于此时机该【字典机】不会自动构建其任何数据,即是说该新建的【字典】空空如也,等待其它代码主动调用其 重建数据 函数。又,该布尔量默认取 false

    为什么要允许【字典】“不在诞生之时自动构建数据”呢? 因为可能有些【字典】之诸【条目】依赖于其它变量,须临时反复构建。且此种【字典】往往不必在诞生时构建其数据。

    例如,假设某应用中有【中标企业】和【已参选的投标企业】两种字段。其中,【中标企业】须在【已参选的投标企业】中选择。故【中标企业】对应的候选列表【字典】总是要根据【已参选企业】这一字段的值来临时构建。每当最终用户在界面中改动了【已参选企业】之列表,则【中标企业】之候选列表亦须据此重建。是故,本工具集中的【字典】允许配置成“不在诞生之时自动构建数据”。

    凡不在诞生时自动构建数据的【字典】,可以在合适的时机主动调用其 重建数据 函数。

    所谓合适的时机,较典型的例子是在某另外的【字典】的数据变动完成后。设有【甲】、【乙】两个【字典】,【甲】配置为“不在诞生之时自动构建数据”。【乙】是否在诞生时自动构建数据则无关紧要。若欲使【乙】每次重建数据完毕后通知【甲】也重建数据,则可借助一下二者之一:

    1. 在【总机】的 诸事之应对 中的 内任何字典_某次数据重建后_统一做法 函数中侦测【乙】的变动,并在确实侦测的【乙】的变动后令【甲】重建数据。
    2. 在【乙】的 诸事之应对 中的 该字典每次数据重建后 函数中令【甲】重建数据。

    见《完整可运行的示范应用》。

  2. 【字典群之总机】可删除一批【字典机】

    开发者可令【字典群之总机】删除一批【字典机】。此亦即删除该批【字典】。

    做法:

    某字典群之总机..删除一批字典(欲删除之诸字典之唯一标识之列表)
  3. 【字典群之总机】取某【字典机】

    开发者可令【字典群之总机】取某【字典机】之实例。做法有二。

    1. 做法 1。调用【总机】的行为函数。

      const 取得的字典机 = 某字典群之总机..取某字典机(欲索取之字典_其唯一标识)
    2. 做法 2。直接访问【总机】所持的数据集。

      const 取得的字典机 = 某字典群之总机.所持.字典机群.其哈希表[欲索取之字典_其唯一标识]
  4. 【字典群之总机】可取某【字典机】之一切【条目】的列表

    开发者可令【字典群之总机】取某【字典机】之一切【条目】的列表(即 Array)。做法有二。

    1. 做法 1。调用该【总机】的行为函数。

      此为推荐之做法。因为此做法有一优势,即若欲索取之【字典】并不存在,亦不会遭遇运行时错误。

      const 该字典机条目视式之列表 = 某字典群之总机..取某字典诸条目之视式_其列表(
          所涉字典_其唯一标识
      )
    2. 做法 2。直接访问该【总机】 所持 的数据集。

      此做法假设所涉【字典机】确已存在。

      const 该字典机条目视式之列表 = 某字典群之总机.所持.字典机群.其哈希表[
          欲索取之字典_其唯一标识
      ]?.所持.该字典诸条目之视式.其列表
  5. 【字典群之总机】可取某【字典机】之一切【条目】的哈希表

    开发者可令【字典群之总机】取某【字典机】之一切【条目】的哈希表(即键值对)。做法有二。

    1. 做法 1。调用该【总机】的行为函数。

      此为推荐之做法。因为此做法有一优势,即若欲索取之【字典】并不存在,亦不会遭遇运行时错误。

      const 该字典机条目视式之哈希表 = 某字典群之总机..取某字典诸条目之视式_其哈希表(
          所涉字典_其唯一标识
      )
    2. 做法 2。直接访问该【总机】 所持 的数据集。

      此做法假设所涉【字典机】确已存在。

      const 该字典机条目视式之哈希表 = 某字典群之总机.所持.字典机群.其哈希表[
          欲索取之字典_其唯一标识
      ]?.所持.该字典诸条目之视式.其列表
  6. 【字典群之总机】令一批【字典】各自重建一切数据

    开发者可令【字典群之总机】从所有【字典】中按需筛选出一批【字典】,并令这些【字典】各自重建一切数据。

    任何【字典机】的原始数据集,亦即其一切【条目】之【原式】之集,须由该【字典机】自身“构建”而得。

    实践中,【字典】构建其【条目原式】的办法各不相同。多见是凭借某 XHR 过程获取。当然也可以由写死的代码直接生成。但无论怎样,本工具集将这些办法(或者说动作)统称为“数据构建”,简称“构建”。落实到编程代码时,则又改称“重建”而非“构建”。不论是否首次构建数据,均统称“重建”。

    做法:

    某字典群之总机..令一批字典各自重建数据(
        筛选须参与的诸字典时采用的筛选方案
    ).then(function () {
        console.log('该批数据重建任务均已成功!')
    }).catch(function (诸异常之记载) {
        console.error('该批任务中有部分遭遇故障。如下:', 诸异常之记载)
    })

    其中,参数 筛选须参与的诸字典时采用的筛选方案 可省略。又,上文所谓“按需”二字,即为该参数可控行为之表述。

    若该参数确已给出,则其值须为以下三者之一。否则视为未给出。

    1. 文本值 '仅限那些允许参与数据自动构建任务且尚无构建好之数据的字典参与'

      若取该值,则在决定该【总机】所辖诸【字典机】中的哪些【字典机】应参与本批次数据构建任务时,会先筛选出凡 该字典在默认情形下不参与字典群总机发起的数据重建任务true 的【字典机】,而后又排除其中凡已经构建并保有字典数据者。

      该筛选方案典型的应用场景为,令所有由【总机】的 制作一批新字典 函数新追加的那些【字典机】参与数据重建。诚然,此处说成“数据初次构建”更贴切,但为简化称谓,统一说“重建”。

    2. 文本值 '所有允许参与数据自动构建任务的字典均参与,不论其是否已构建好数据'

      若取该值,则在决定该【总机】所辖诸【字典机】中的哪些【字典机】应参与本批次数据构建任务时,会筛选出凡 该字典在默认情形下不参与字典群总机发起的数据重建任务true 的【字典机】,哪怕它们已经成功构建并保有字典数据。

    3. 文本值 '强制一切字典参与,不论其是否已构建好数据'

      若取该值,则会令该【总机】所辖一切【字典机】统统参与本批次的数据构建任务。换句话说,不做任何筛选,完全忽略各【字典机】的 该字典在默认情形下不参与字典群总机发起的数据重建任务 之值。

    若该参数未给出,或因取值不当而视作未给出,则等同于取文本值 '仅限那些允许参与数据自动构建任务且尚无构建好之数据的字典参与'

    还须注意,由【字典群之总机】发起的成批构建数据之任务,无法为参与该批次任务的各个【字典机】提供具体的构建参数。故而,在此种情形下这些【字典机】的 应对构建该字典所有条目之原式 函数统统得不到第三个参数

    若绕开【总机】,令某个【字典机】主动的、独立的构建数据,则该【字典机】的 重建数据 函数所获得的一切参数会形成一个参数列表(Array),并传递给由开发者为该【字典机】事先设计好的 应对构建该字典所有条目之原式 函数,作为其第三个实参。参见下文《【字典机】之功能及用法》。

【字典机】之功能及用法

于某【字典机之实例】(简称【字典机】),开发者可以有以下动作。

  1. 【字典机】可清空其保有的一切数据

    开发者可令【字典机】清空其目前保有的一切数据。

    此举将清空包括一切【原式】、一切【视式】、一切【条目内容映射表】在内的数据。且 该字典当下所持的数据系由某次构建而得 变为 false

    做法:

    某字典机..清空数据()
  2. 【字典机】可重建一切数据

    开发者可令【字典机】重建一切数据。

    任何【字典机】的原始数据集,亦即其一切【条目】之【原式】之集,须由该【字典机】自身“构建”而得。

    实践中,不同【字典】构建其【条目原式】的办法亦各不相同。多见是凭借某 XHR 过程获取。当然也可以由写死的代码直接生成。但无论怎样,本工具集将这些办法(或者说动作)统称为“数据构建”,简称“构建”。落实到编程代码时,则又改称“重建”而非“构建”。不论是否首次构建数据,均统称“重建”。

    一旦诸【条目原式】构建成功,【字典机】还会自动重新构建其一切【条目视式】、一切【条目内容映射表】,并将 该字典当下所持的数据系由某次构建而得 变为 true

    做法:

    某字典机..重建数据(
        ...由开发者自行设计的参数列表: any[]
    ).then(function () {
        console.log('该字典已完成一次数据重建!')
    }).catch(function (异常之记载) {
        console.error('该字典在数据重建时遭遇故障。如下:', 异常之记载)
    })

    【字典机】的 重建数据 函数在幕后调用该【字典机】的 应对 中的 构建该字典所有条目之原式 函数。并且,凡向 重建数据 函数提供的一切实参,会搜集在一个列表(Array)中,再令该列表作为 构建该字典所有条目之原式 函数的第三个实参。

    须注意,主动调用某【字典机】的 重建数据 函数时可向 构建该字典所有条目之原式 函数给出第三实参这一点,与【字典群之总机】令某【字典机】参与成批的数据重建任务时不同 。由【字典群之总机】发起的成批构建数据之任务,无法为参与该批次任务的各个【字典机】提供具体的构建参数。故而,在此种情形下这些【字典机】的 应对构建该字典所有条目之原式 函数得不到第三个参数。

    目前【字典机】的这一特征令其 构建该字典所有条目之原式 函数的第三个实参的实用价值不高。鄙人考虑未来禁止向 重建数据 函数给出任何参数,从而令 构建该字典所有条目之原式 函数始终仅得到两个实参,永不获得第三实参。另一个在考虑的方案是令【字典机】各自保存最末一次 重建数据 所采用的参数表,以便之后【总机】发起成批数据重建任务时复用该参数表。

    须知,每当某【字典机】调用 重建数据 函数时,不论主动(人为)调用还是被动(由【总机】)调用,如果当时该【字典机】并未处在数据重建过程当中,则【该字典机】将开始新的数据重建过程,并为此新建一个【期待】,并保有之,并令 重建数据 函数返回该【期待】。相反,若业已开始的数据重建过程尚未结束,而该【字典机】再次主动或被动调用 重建数据 函数,则该【字典机】不会启动新的数据构建过程,亦不会新建【期待】,而是令 重建数据 函数直接返回已经保有的、代表尚未结束的数据重建过程的那个【期待】。

  3. 【字典机】可凭某【条目】之【值】求对应【呈示称谓】

    开发者可令【字典机】凭某【条目】之【值】求该【条目】之【呈示称谓】。

    做法:

    const 该条目之称谓之文本 = 某字典机..凭某条目之值求其呈示称谓(所涉条目之值)
  4. 【字典机】可自毁

    开发者可令【字典机】自毁。这将彻底销毁该【字典机】,亦即销毁该【字典】。

    做法:

    某字典机..自毁()

    不妨指出,【总机】的 删除一批字典 函数,即是在幕后调用所涉各【字典机】的 自毁 函数。

诸关键编程数据之【范】

  1. 【字典条目】之范
    1. 其【原式】之【范】。

      凡【原式】者,十有八九由外界给出,且形式五花八门。故本工具集对【原式】之【范】无有特定假设或规定。

    2. 其【视式】之【最简式】之【范】。

      export type 范_字典条目_唯一标识 = string | number;
      
      export interface 范_字典条目之视式_最简式<范_字典条目之值 = any> {
          唯一标识: 范_字典条目_唯一标识;
          呈示称谓: string;
          : 范_字典条目之值;
      }
  2. 单个【字典机】之范

    该【范】之完整定义较冗长,不便阅读、理解。故不妨先给出其常量形式。常量形式相对于完整定义显得较为简略,可以辅助观察和理解。常量形式如下。

    又,下方常量形式中各字段之取值并非其默认值,而是随意值。

    const 某字典机 = {
        该字典之唯一标识: '字典甲',
    
        所持: {
            字典特别条目_其代表全选者 {
                应位于候选列表之该处: '首部' | '尾部',
                字典条目之视式: { 唯一标识: '首部', 呈示称谓: '〔全选〕', : 99999 },
                当正常候选项个数为零时仍允许采用本特别项: boolean,
            },
    
            字典特别条目_其代表全都不选者 {
                应位于候选列表之该处: '首部' | '尾部',
                字典条目之视式: { 唯一标识: '首部', 呈示称谓: '〔全都不选〕', : -1 },
            },
    
            该字典诸条目之原式_其列表: [],
    
            该字典诸条目之视式: {
                其列表: [],
                其哈希表: {},
            },
    
            字典条目诸内容映射表之集: {
                从呈示称谓至值: {
                    '〔全选〕': 99999,
                    '〔全都不选〕': -1,
                },
    
                从值至呈示称谓: {
                    '99999': '〔全选〕',
                    '-1': '〔全都不选〕',
                },
            },
        },
    
        : {
            _已销毁: false,
            该字典当下所持的数据系由某次构建而得: false,
            该字典诸字典条目内容映射表业已构建完毕: false,
            该字典当下正在构建数据: false,
            期待_该字典最末一次数据构建任务已落定: Promise.resolve(),
        },
    
        : { // wéi,指行为。
            清空数据 () { /* 函数体从略。 */ },
            重建数据 (由开发者任意设计的参数表) { /* 函数体从略。 */ },
            凭某条目之值求其呈示称谓 () { /* 函数体从略。 */ },
            自毁 () { /* 函数体从略。 */ },
        },
    
        形制杂项集: {
            该字典机的调试信息之详尽等级: 1,
            该字典构建诸字典条目内容映射表之方案: '从该字典之诸条目原式之集提取而得',
            该字典在默认情形下不参与字典群总机发起的数据重建任务: false,
            应构建字典条目之视式之哈希表: true,
        },
    
        应对: {
            构建该字典所有条目之原式 (总机, 该字典机自身, 第三个参数搜集了从该字典机自身的_重建数据_函数传递过来的实参列表) { /* 函数体从略。 */ },
            凭某条目之原式构建其视式 (某条目_其原式) { /* 函数体从略。 */ },
            脱离字典条目原式之集构建诸字典条目内容映射表 () { /* 函数体从略。 */ },
            凭字典条目原式之集构建诸字典条目内容映射表 (该字典_诸条目原式_其列表) { /* 函数体从略。 */ },
            该字典每次数据重建后 (总机, 该字典机自身) { /* 函数体从略。 */ },
        },
    }

    【字典机】之【范】之完整定义如下。

    export type 范_字典机系统_其This之默认式 = any;
    
    export type 范_字典机<
        范_该字典机_其This = 范_字典机系统_其This之默认式,
        范_该字典_条目原式 = any,
        范_该字典_条目视式 extends 范_字典条目之视式_最简式 = 范_字典条目之视式_最简式<any>
    > = {
        该字典之唯一标识: string;
    
        所持: {
            字典特别条目_其代表全选者:
                null | {
                    应位于候选列表之该处: '首部' | '尾部';
                    字典条目之视式: 范_该字典_条目视式;
                    呈示称谓: string;
                    当正常候选项个数为零时仍允许采用本特别项: boolean;
                };
    
            字典特别条目_其代表全都不选者:
                null | {
                    应位于候选列表之该处: '首部' | '尾部';
                    字典条目之视式: 范_该字典_条目视式;
                    呈示称谓: string;
                };
    
            该字典诸条目之原式_其列表:
                null | Array<范_该字典_条目原式>;
    
            该字典诸条目之视式: {
                其列表: Array<范_该字典_条目视式>;
                其哈希表: Record<string, 范_该字典_条目视式>;
            };
    
            字典条目诸内容映射表之集: {
                从呈示称谓至值: Record<string, 范_该字典_条目之值>;
                从值至呈示称谓: { [条目之值对应之文本: string]: string; };
            };
        };
    
        : {
            _已销毁: boolean;
    
            该字典当下所持的数据系由某次构建而得: boolean;
            该字典诸字典条目内容映射表业已构建完毕: boolean;
            该字典当下正在构建数据: boolean;
            期待_该字典最末一次数据构建任务已落定: Promise<void>;
        };
    
        : { // wéi,指行为。
            清空数据: () => void;
            重建数据: (...参数表_用以获取字典诸条目之原式: any[]) => Promise<void>;
            凭某条目之值求其呈示称谓: (所涉条目之值?: any) => string | null | undefined;
            自毁: () => void;
        } & ThisType<范_该字典机_其This>;
    
        形制杂项集: {
            该字典机的调试信息之详尽等级: number;
    
            该字典构建诸字典条目内容映射表之方案: 范_单个字典构建诸字典条目内容映射表之方案;
    
            /**
             * 有些【字典】之【字典条目】依赖于其它变量,须临时反复构建。
             * 且此种【字典】往往不必在模块加载初始时构建。
             *
             * 例如,假设有【中标企业】和【已参选的投标企业】两种字段。
             * 其中,【中标企业】须在【已参选的投标企业】中选择。
             * 故【中标企业】对应的候选列表【字典】应根据【已参选企业】这一字段的值来临时构建。
             */
            该字典在默认情形下不参与字典群总机发起的数据重建任务: boolean;
    
            /**
             * 该所谓 “逆向” 哈希表用途不广,不及列表形式。故默认不构建该哈希表,以节省计算。
             * 但为了简化 “防卫性” 代码,即便不构建该哈希表,本工具仍令该哈希表之取值为 {} ,而非 null 。
             */
            应构建字典条目之视式之哈希表: boolean;
        };
    
        应对: {
            构建该字典所有条目之原式: (
                this: 范_该字典机_其This,
    
                该字典所属字典群之总机:
                    范_字典群之总机<
                        范_该字典机_其This,
                        any,
                        any
                    >,
    
                该字典机:
                    范_字典机<
                        范_该字典机_其This,
                        范_该字典_条目原式,
                        范_该字典_条目视式,
                    >,
    
                参数表_用以获取字典诸条目之原式: any[]
            ) => Promise<Array<范_该字典_条目原式>>;
    
            凭某条目之原式构建其视式: (
                this: 范_该字典机_其This,
                该字典_某条目之原式: 范_该字典_条目原式
            ) => 范_该字典_条目视式;
    
            /** 该项可视具体条件而省略。 */
            脱离字典条目原式之集构建诸字典条目内容映射表?: (
                this: 范_该字典机_其This,
            ) => Promise<范_字典条目诸内容映射表之集<范_该字典_条目视式['值']>>;
    
            /** 该项可视具体条件而省略。 */
            凭字典条目原式之集构建诸字典条目内容映射表?: (
                this: 范_该字典机_其This,
                该字典_诸条目原式_其列表: Array<范_该字典_条目原式>
            ) => Promise<范_字典条目诸内容映射表之集<范_该字典_条目视式['值']>>;
    
            /** 该项可省略。 */
            该字典每次数据重建后?: (
                this: 范_该字典机_其This,
    
                该字典所属字典群之总机:
                    范_字典群之总机<
                        范_该字典机_其This,
                        any,
                        any
                    >,
    
                该字典机:
                    范_字典机<
                        范_该字典机_其This,
                        范_该字典_条目原式,
                        范_该字典_条目视式,
                    >,
            ) => void;
        } & ThisType<范_该字典机_其This>;
    };
  3. 【字典群之总机】之范

    该【范】之完整定义较冗长,不便阅读、理解。故不妨先给出其常量形式。常量形式相对于完整定义显得较为简略,可以辅助观察和理解。常量形式如下。

    又,下方常量形式中各字段之取值并非其默认值,而是随意值。

    const 字典群之总机 = {
        该字典群之称谓: '应用首页的字典群',
    
        所持: {
            字典机群: {
                其列表: [],
                其哈希表: {},
            },
        },
    
        : {
            当下仍有字典机在构建数据: false,
            期待_迄今所有批次的字典机之数据重建任务均已落定: Promise.resolve(),
        },
    
        : { // wéi,指行为。
            制作一批新字典 (一批字典机之形制要求总集之列表) { /* 函数体从略。 */ },
            删除一批字典 (欲删除之诸字典之唯一标识之列表) { /* 函数体从略。 */ },
            取某字典机 (欲索取之字典_其唯一标识) { /* 函数体从略。 */ },
            取某字典诸条目之视式_其列表 (所涉字典_其唯一标识) { /* 函数体从略。 */ },
            取某字典诸条目之视式_其哈希表 (所涉字典_其唯一标识) { /* 函数体从略。 */ },
            令一批字典各自重建数据 (筛选须参与的诸字典时采用的筛选方案) { /* 函数体从略。 */ },
        },
    
        形制杂项集: {
            该总机的调试信息之详尽等级: 0,
        },
    
        应对: {
            内任何字典_某次数据重建后_统一做法 (该总机自身, 所涉字典机) { /* 函数体从略。 */ },
            内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法 (所涉字典_诸条目原式_其列表) { /* 函数体从略。 */ },
            内任何所谓标准字典_凭某条目之原式构建其视式_默认做法 (所涉字典_某条目之原式) { /* 函数体从略。 */ },
        },
    }

    【字典群之总机】之【范】之完整定义如下。

    export type 范_字典机系统_其This之默认式 = any;
    
    export type 范_字典群之总机<
        范_该总机_其This = 范_字典机系统_其This之默认式,
        范_该总机_内所谓标准字典_条目原式 = any,
        范_该总机_内所有字典_条目视式_各色形态之交集 extends 范_字典条目之视式_最简式 = 范_字典条目之视式_最简式<any>,
    > = {
        该字典群之称谓: string;
    
        所持: {
            字典机群: {
                其列表:
                    Array<
                        范_字典机<
                            范_该总机_其This,
                            any,
                            范_该总机_内所有字典_条目视式_各色形态之交集
                        >
                    >;
    
                其哈希表:
                    Record<
                        string,
    
                        范_字典机<
                            范_该总机_其This,
                            any,
                            范_该总机_内所有字典_条目视式_各色形态之交集
                        >
                    >;
            };
        };
    
        : {
            当下仍有字典机在构建数据:
                boolean;
    
            期待_迄今所有批次的字典机之数据重建任务均已落定:
                Promise<void>;
        };
    
        : { // wéi,指行为。
    
            制作一批新字典: <
                范_该批字典_条目原式_可能的默认形态 = 范_该总机_内所谓标准字典_条目原式
            >(
                一批字典机之形制要求总集之列表?: Array<
                    范_字典机_形制要求总集_形参准用式<
                        范_该总机_其This,
                        范_该批字典_条目原式_可能的默认形态,
                        范_该总机_内所有字典_条目视式_各色形态之交集
                    >
                >
            ) => Promise<void>;
    
            删除一批字典: (
                欲删除之诸字典之唯一标识之列表?: 范_字典_唯一标识[]
            ) => void;
    
            取某字典机: <
                范_该字典_条目原式 = 范_该总机_内所谓标准字典_条目原式,
                范_该字典_条目视式 extends 范_该总机_内所有字典_条目视式_各色形态之交集 = 范_该总机_内所有字典_条目视式_各色形态之交集
            >(
                欲索取之字典_其唯一标识?: 范_字典_唯一标识
            ) => (null | 范_字典机<范_该总机_其This, 范_该字典_条目原式, 范_该字典_条目视式>);
    
            取某字典诸条目之视式_其列表: <
                范_该字典_条目原式 = 范_该总机_内所谓标准字典_条目原式,
                范_该字典_条目视式 extends 范_该总机_内所有字典_条目视式_各色形态之交集 = 范_该总机_内所有字典_条目视式_各色形态之交集
            >(
                所涉字典_其唯一标识?: 范_字典_唯一标识
            ) => 范_字典诸条目之视式_其列表<范_该字典_条目视式>;
    
            取某字典诸条目之视式_其哈希表: <
                范_该字典_条目原式 = 范_该总机_内所谓标准字典_条目原式,
                范_该字典_条目视式 extends 范_该总机_内所有字典_条目视式_各色形态之交集 = 范_该总机_内所有字典_条目视式_各色形态之交集
            >(
                所涉字典_其唯一标识?: 范_字典_唯一标识
            ) => 范_字典诸条目之视式_其哈希表<范_该字典_条目视式>;
    
            令一批字典各自重建数据: (
                筛选须参与的诸字典时采用的筛选方案?: 范_字典群之总机_成批重建字典数据之方案
            ) => Promise<void>;
    
        } & ThisType<范_该总机_其This>;
    
        形制杂项集: {
            该总机的调试信息之详尽等级: number;
        };
    
        应对: {
    
            /** 该项可省略。 */
            内任何字典_某次数据重建后_统一做法?: (
                this: 范_该总机_其This,
    
                该字典群之总机: 范_字典群之总机<
                    范_该总机_其This,
                    范_该总机_所涉所谓标准字典_条目原式,
                    范_该总机_所涉所谓标准字典_条目之值_各色形态之并集
                >,
    
                所涉字典机: 范_字典机<
                    范_该总机_其This,
                    范_该总机_所涉所谓标准字典_条目原式,
                    范_该总机_所涉所谓标准字典_条目之值_各色形态之并集
                >
            ) => void;
    
            /** 该项可省略。 */
            内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法?: (
                this: 范_该总机_其This,
                所涉字典_诸条目原式_其列表: Array<范_该总机_所涉所谓标准字典_条目原式>
            ) => Promise<
                范_字典条目诸内容映射表之集<
                    范_该总机_所涉所谓标准字典_条目之值_各色形态之并集
                >
            >;
    
            /** 该项可省略。 */
            内任何所谓标准字典_凭某条目之原式构建其视式_默认做法?: (
                this: 范_该总机_其This,
                所涉字典_某条目之原式: 范_该总机_所涉所谓标准字典_条目原式
            ) => 范_该总机_内所有字典_条目视式_各色形态之交集;
    
        } & ThisType<范_该总机_其This>;
    };

针对 Vuejs 的专门处理

在【字典群之总机】内部,当操作某列表(Array)、哈希表(Object)时,有少量用以迁就 Vuejs 的代码。具体如下:

  • 当【工厂函数】发现其 this 对象存在,且该 this 对象配有 $set 方法时,【工厂函数】所构建的【字典群之总机】在操作某列表、哈希表时,会尽量采用 $set 方法。

  • 当【工厂函数】之 this 对象不存在,或该 this 对象不具备 $set 方法时,【工厂函数】所构建的【字典群之总机】会直接操作操作诸列表、哈希表。

注意到,本工具在尝试采用 Vuejs 之专有特性时,故意借助 this 对象,而非借助全局的 vue 对象。很显然,该 this 对象须为某 【Vuejs 部件】之【实例】。因此,在针对 Vuejs 的环境中采用本工具集时,务必在工厂函数 作一字典群之总机 的第一个实参上给出某 Vuejs 之【部件】,作为 this 对象。 参阅下文《【字典群之总机】之工厂函数》。

应用编程接口(外国话所谓 API)

不妨先阅读本文的《关键数据之【范】》章节。

  1. 【字典群之总机】之工厂函数

    该函数名为 作一字典群之总机 ,共有两种重载。其【接口全貌】如下:

    declare module '@wulechuan/controllers-of-enum-dictionaries' {
        // 须知,函数 `作一字典群之总机` 共有两种重载。
    
        // 重载形式之一:要求给出两个实参。其中第一个实参系用作内部诸方法函数的 this 对象。
        export declare function 作一字典群之总机 <
            范_该总机_内所谓标准字典_条目原式 = any,
            范_该总机_内所有字典_条目视式_各色形态之交集 extends 范_字典条目之视式_最简式 = 范_字典条目之视式_最简式<any>
        >(
            该总机_其This: any,
    
            该字典群之总机之形制要求总集:
                范_字典群之总机_形制要求总集_形参准用式<
                    范_该总机_其This,
                    范_该总机_内所谓标准字典_条目原式,
                    范_该总机_内所有字典_条目视式_各色形态之交集
                >
        ): 范_字典群之总机<
            范_该总机_其This,
            范_该总机_内所谓标准字典_条目原式,
            范_该总机_内所有字典_条目视式_各色形态之交集
        >;
    
    
    
        // 重载形式之二:要求仅给出一个实参。
        export declare function 作一字典群之总机 <
            范_该总机_内所谓标准字典_条目原式 = any,
            范_该总机_内所有字典_条目视式_各色形态之交集 extends 范_字典条目之视式_最简式 = 范_字典条目之视式_最简式<any>
        >(
            该字典群之总机之形制要求总集?:
                范_字典群之总机_形制要求总集_形参准用式<
                    范_该总机_其This,
                    范_该总机_内所谓标准字典_条目原式,
                    范_该总机_内所有字典_条目视式_各色形态之交集
                >
        ): 范_字典群之总机<
            范_该总机_其This,
            范_该总机_内所谓标准字典_条目原式,
            范_该总机_内所有字典_条目视式_各色形态之交集
        >;
    
    } // declare module 语句块结束于此。

    为便于阅读、理解和记忆,上述【接口全貌】可简写作下方的非规范形式:

    declare module '@wulechuan/controllers-of-enum-dictionaries' {
        // 须知,函数 `作一字典群之总机` 共有两种重载。
    
        // 重载形式之一:要求给出两个实参。其中第一个实参系用作内部诸方法函数的 this 对象。
        export declare function 作一字典群之总机 <...>(
            该总机_其This: any,
            该字典群之总机之形制要求总集: 某较复杂之范
        ): 范_字典群之总机<...>
    
        // 重载形式之二:要求仅给出一个实参。
        export declare function 作一字典群之总机 <...>(
            该字典群之总机之形制要求总集?: 某较复杂之范
        ): 范_字典群之总机<...>
    }
  2. 【字典机】之工厂函数

    不妨暂称【字典群之总机】为【甲】,称用以构建单个【字典机】之工厂函数为【乙】。须知,【甲】会自行按需调用【乙】,以构建出【字典机】。 故不推荐开发者手工(或者说人为)调用【乙】。

    细节从略。

  3. 诸常量

    export const 任何给定的字典群之总机_成批重建字典数据之各色方案: Array<范_字典群之总机_成批重建字典数据之方案> = [
        '仅限那些允许参与数据自动构建任务且尚无构建好之数据的字典参与',
        '所有允许参与数据自动构建任务的字典均参与,不论其是否已构建好数据',
        '强制一切字典参与,不论其是否已构建好数据',
    ]
    
    export const 任何给定的字典_构建诸条目内容映射表之各色方案: Array<范_单个字典构建诸字典条目内容映射表之方案> = [
        '不必构建',
        '从该字典之诸条目原式之集提取而得',
        '脱离该字典之诸条目原式之集而构建,仅一次即可',
        '脱离该字典之诸条目原式之集而构建,且须反复构建',
    ]
    
    export const 任何给定的字典_构建诸条目内容映射表之默认方案: 范_单个字典构建诸字典条目内容映射表之方案 = '从该字典之诸条目原式之集提取而得'
    
    export const 字典特别条目_其代表全选者_默认的呈示称谓 = '〔全选〕'
    export const 字典特别条目_其代表全都不选者_默认的呈示称谓 = '〔全都不选〕'
  4. 【字典群之总机】的 期待_迄今所有批次的字典机之数据重建任务均已落定

    【字典群之总机】的 中的 期待_迄今所有批次的字典机之数据重建任务均已落定 是一个【期待】。

    须知,每当某【字典机】调用 重建数据 函数时,不论主动(人为)调用还是被动(由【总机】)调用,如果当时该【字典机】并未处在数据重建过程当中,则【该字典机】将开始新的数据重建过程,并为此新建一个【期待】,并保有之,并令 重建数据 函数返回该【期待】。相反,若业已开始的数据重建过程尚未结束,而该【字典机】再次主动或被动调用 重建数据 函数,则该【字典机】不会启动新的数据构建过程,亦不会新建【期待】,而是令 重建数据 函数直接返回已经保有的、代表尚未结束的数据重建过程的那个【期待】。

    每当某【总机】调用 令一批字典各自重建数据 函数时,该函数返回一个【期待】,暂称【期待甲】。【期待甲】是对所有参与该批次数据重建任务的【字典机】保有的【期待】Promise.allSettled.then() 而得到的所谓“汇总【期待】”。故,为明确,下文将【期待甲】改称【汇总期待甲】为宜。

    若【汇总期待甲】尚未落定,该【总机】再次调用 令一批字典各自重建数据 函数,该函数返回一个新的【期待】,暂称【汇总期待乙】。不难理解,【汇总期待甲】未必早于【汇总期待乙】落定。因为批次甲可能要求重建【字典子】、【字典丑】和【字典寅】的数据,而批次乙却要求重建【字典卯】、【字典辰】和【字典巳】的数据。

    如果开发者既不关心【汇总期待甲】,也不关心【汇总期待乙】,而是想在确保甲、乙两批次任务落定之后的所谓“最终期待”,要如何做呢?答案是忽略两次调用 令一批字典各自重建数据 函数分别返回的【汇总期待甲】、【汇总期待甲乙】,改为人为取用【总机】的 期待_迄今所有批次的字典机之数据重建任务均已落定 (下称暂称【集总期待】)。该【集总期待】总是在该【总机】迄今一切在行任务全部落定之后才落定。

    用法示范:

    /**
     * 下面故意连续发起三批任务。
     *
     * 须知,
     * 这三批任务并不一定依照启动顺序结束。
     * 它们的结束顺序往往是不可预测的。
     */
    某字典群之总机..令一批字典各自重建数据()
    某字典群之总机..令一批字典各自重建数据('强制一切字典参与,不论其是否已构建好数据')
    某字典群之总机..令一批字典各自重建数据()
    
    const 期待_上述总机的所有批次的所有数据重建任务均已落定 = 某字典群之总机..期待_迄今所有批次的字典机之数据重建任务均已落定
    
    期待_上述总机的所有批次的所有数据重建任务均已落定.then(function () {
        console.log('该字典群迄今一切数据重建任务均已完成!')
    }).catch(function (迄今一切批次累积的所有异常之记载) {
        console.log(`该字典群迄今一切数据重建任务均已结束!但期间遭遇了 ${
            迄今一切批次累积的所有异常之记载.length
        } 次故障。如下:`, 迄今一切批次累积的所有异常之记载)
    })

应用示范集

  1. 示范1

    为某 Vuejs 部件构建一个【字典群之总机】。

    1. Vuejs 的【类 HTML】之界面模板

      <template v-if="字典群总机">
          <el-select v-model="某表单项之取值">
              <el-option
                  v-for="字典条目之视式 in 字典群总机.为.取某字典诸条目之视式_其列表('字典甲')"
                  :key="字典条目之视式.唯一标识"
                  :value="字典条目之视式.值"
                  :label="字典条目之视式.呈示称谓"
              ></el-option>
          </el-select>
      </template>
    2. 逻辑控制

      • 采用 TypeScript 语言之写法。

        import { Vue, Component } from 'vue-property-decorator'
        
        import {
            作一字典群之总机,
        } from '@wulechuan/controllers-of-enum-dictionaries'
        
        import type {
            范_字典条目内容映射表_从呈示称谓至值,
            范_字典条目内容映射表_从值至呈示称谓,
        } from '@wulechuan/controllers-of-enum-dictionaries'
        
        export type 范_本示范应用中一切字典之字典条目之原式 = {
            /** 故意采用外国字,以示范在当今常见的项目中如何采用本工具(即指字典群总机)。 */
            id: string;
        
            /** 故意采用外国字,以示范在当今常见的项目中如何采用本工具(即指字典群总机)。 */
            label: string;
        };
        
        export type 范_本示范应用中一切字典之字典条目之视式 = 范_字典条目之视式_最简式<
            范_本示范应用中一切字典之字典条目之原式['id']
        >;
        
        
        
        @Component({})
        export default class Vue部件甲 extends Vue {
            private 某表单项之取值: null | number = null
        
            public 字典群总机: null | 范_本应用中一切字典群之总机<Page示范页1> = null
        
            private mounted (): void {
                this.字典群总机 = 作一字典群之总机<范_本示范应用中一切字典之字典条目之原式, 范_本示范应用中一切字典之字典条目之视式>(
                    this,
        
                    {
                        该字典群之称谓: '我的第一个【字典群】',
        
                        该总机的调试信息之详尽等级: 2,
        
                        第一批字典机形制要求总集_其列表: [
                            {
                                该字典之唯一标识: '字典甲',
        
                                诸事之应对: { // 此乃【字典甲】独有的应对其诸事之办法。
                                    构建该字典所有条目之原式 () {
                                        return new Promise(落实之 => setTimeout(落实之, 2358)).then(() => {
                                            const 数据列表: Array<范_本示范应用中一切字典之字典条目之原式> = [
                                                '九章算术',
                                                '诗经',
                                                '尚书',
                                                '楚辞',
                                                '本草纲目',
                                                '孙子兵法',
                                                '史记',
                                                '传习录',
                                            ].map((名典之名称, 其列表编号) => {
                                                const 名典字典条目之原式: 范_本示范应用中一切字典之字典条目之原式 = {
                                                    id: `${其列表编号 + 1}`,
                                                    label: 名典之名称,
                                                }
        
                                                return 名典字典条目之原式
                                            })
        
                                            return 数据列表
                                        })
                                    }
                                },
                            },
                        ],
        
                        诸事之应对: { // 此乃【总机】应对其诸事之办法。
                            内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法 (
                                某字典之一切条目之原式_其列表
                            ) {
                                const 从呈示称谓至值: 范_字典条目内容映射表_从呈示称谓至值 = {}
                                const 从值至呈示称谓: 范_字典条目内容映射表_从值至呈示称谓 = {}
        
                                某字典之一切条目之原式_其列表.forEach(该字典某条目之原式 => {
                                    const { id, label } = 该字典某条目之原式
                                    从值至呈示称谓[id] = label
                                    从呈示称谓至值[label] = id
                                })
        
                                return Promise.resolve({ 从呈示称谓至值, 从值至呈示称谓 })
                            },
        
                            内任何所谓标准字典_凭某条目之原式构建其视式_默认做法 (
                                某字典某条目之原式
                            ) {
                                const { id, label } = 某字典某条目之原式
                                const 该字典该条目之视式 = { 唯一标识: id, 呈示称谓: label, : id }
                                return 该字典该条目之视式
                            },
                        },
                    }
                )
            }
        }
      • 采用 JavaScript 语言之写法。

        import {
            作一字典群之总机,
        } from '@wulechuan/controllers-of-enum-dictionaries'
        
        export default {
            name: 'Vue部件甲',
        
            data () {
                return {
                    某表单项之取值: null,
                    字典群总机: null,
                }
            },
        
            mounted () {
                this.字典群总机 = 作一字典群之总机(
                    this, // 注意!当本工具用于 Vuejs 框架上时,此处须给出正确的 this 对象。
        
                    {
                        该字典群之称谓: '我的第一个【字典群】',
        
                        该总机的调试信息之详尽等级: 2,
        
                        第一批字典机形制要求总集_其列表: [
                            {
                                该字典之唯一标识: '字典甲',
        
                                诸事之应对: { // 此乃【字典甲】独有的应对其诸事之办法。
                                    构建该字典所有条目之原式 () {
                                        return new Promise(落实之 => setTimeout(落实之, 2358)).then(() => {
                                            const 数据列表 = [
                                                '九章算术',
                                                '诗经',
                                                '尚书',
                                                '楚辞',
                                                '本草纲目',
                                                '孙子兵法',
                                                '史记',
                                                '传习录',
                                            ].map((名典之名称, 其列表编号) => {
                                                const 名典字典条目之原式 = {
                                                    id: `${其列表编号 + 1}`,
                                                    label: 名典之名称,
                                                }
        
                                                return 名典字典条目之原式
                                            })
        
                                            return 数据列表
                                        })
                                    }
                                },
                            },
                        ],
        
                        诸事之应对: { // 此乃【总机】应对其诸事之办法。
                            内任何所谓标准字典_凭字典条目原式之集构建诸字典条目内容映射表_默认做法 (
                                某字典之一切条目之原式_其列表
                            ) {
                                const 从呈示称谓至值 = {}
                                const 从值至呈示称谓 = {}
        
                                某字典之一切条目之原式_其列表.forEach(该字典某条目之原式 => {
                                    const { id, label } = 该字典某条目之原式
                                    从值至呈示称谓[id] = label
                                    从呈示称谓至值[label] = id
                                })
        
                                return Promise.resolve({ 从呈示称谓至值, 从值至呈示称谓 })
                            },
        
                            内任何所谓标准字典_凭某条目之原式构建其视式_默认做法 (
                                某字典某条目之原式
                            ) {
                                const { id, label } = 某字典某条目之原式
                                const 该字典该条目之视式 = { 唯一标识: id, 呈示称谓: label, : id }
                                return 该字典该条目之视式
                            },
                        },
                    }
                )
            },
        }
  2. 完整可运行的示范应用

    见本工具集源代码仓库中随附的示范应用 2 则:

    1. 〔仓库根文件夹〕/文档集/示范应用集/示范应用-1/采用-javascript-编写
    2. 〔仓库根文件夹〕/文档集/示范应用集/示范应用-1/采用-typescript-编写

未来计划

尚无。


许可证类型

WTFPL

注意:

我未研究过许可证的约束。因此姑且声明为 WTFPL 类型。但实际上该许可证类型可能与我采用的开源模块有冲突。

Package Sidebar

Install

npm i @wulechuan/controllers-of-enum-dictionaries

Weekly Downloads

17

Version

1.0.2

License

WTFPL

Unpacked Size

281 kB

Total Files

19

Last publish

Collaborators

  • wulechuan