# @decaf-ts/decoration 中文文档

规范地址：https://npmcn.com/package/%40decaf-ts/decoration/

版本：0\.20\.0
npm 元数据更新时间：2026-11-06T19:07:33.107Z
中文译文更新时间：2026-11-13T05:38:07.760Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40decaf-ts/decoration
原文对照：https://npmcn.com/package/%40decaf-ts/decoration/?lang=original
项目主页：https://github.com/decaf-ts/decoration#readme
源码仓库：https://github.com/decaf-ts/decoration

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：498 kB，92 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- 首次发布：2025-09-12T17:51:24.650Z
- 最新版本发布：2026-11-06T19:07:32.718Z
- 近 30 天下载量：2190（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 33 个）

## 中文简介

无咖啡因咖啡因的装饰和元数据机制

## 安装

```sh
npm install @decaf-ts/decoration
```

也可以使用：`pnpm add @decaf-ts/decoration`、`yarn add @decaf-ts/decoration`、`bun add @decaf-ts/decoration`

## README

![Banner](https://npmcn.com/package/%40decaf-ts/decoration/workdocs/assets/decaf-logo.svg)

## @ decaf-ts/装饰

装饰模块提供了一个小型可调和的系统,用于建造和应用TypeScript装饰器,并具有花纹感知分辨率和集中运行时元数据存储. 它允许您定义基础装饰器,提供特定框架的覆盖和扩展("flavours"),并在运行时记录/读取类及其成员的丰富的元数据.

### 核心概念

-   **元数据**:一个集中的,静态的班级,用于读取和写出班级及其成员的元数据. 它支持嵌入键并可以在构造器上镜像元数据以方便访问.
-   **装饰**: 用于创建和管理装饰器的建筑师类. 它允许您定义一组基本装饰器,然后用不同的"口味"来覆盖或扩展.
-   **火焰**:提供具体框架执行装饰的机制。 这使得您可以创建对基础框架不可知的库,然后为不同的环境(如Angular,React,Vue)提供具体的执行.
-   **装饰者**: 一套公用事业装饰器(`@metadata`, (中文(简体) ), `@prop`, (中文(简体) ), `@method`, (中文(简体) ), `@param`, (中文(简体) ), `@apply`用于与元数据系统合作.

![Licence](https://img.shields.io/github/license/decaf-ts/ts-workspace.svg?style=plastic) ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/ts-workspace?style=plastic) ![GitHub top language](https://img.shields.io/github/languages/top/decaf-ts/ts-workspace?style=plastic)

[![Build & Test](https://github.com/decaf-ts/ts-workspace/actions/workflows/nodejs-build-prod.yaml/badge.svg)](https://github.com/decaf-ts/ts-workspace/actions/workflows/nodejs-build-prod.yaml) [![CodeQL](https://github.com/decaf-ts/ts-workspace/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/decaf-ts/ts-workspace/actions/workflows/codeql-analysis.yml)[![Snyk Analysis](https://github.com/decaf-ts/ts-workspace/actions/workflows/snyk-analysis.yaml/badge.svg)](https://github.com/decaf-ts/ts-workspace/actions/workflows/snyk-analysis.yaml) [![Pages builder](https://github.com/decaf-ts/ts-workspace/actions/workflows/pages.yaml/badge.svg)](https://github.com/decaf-ts/ts-workspace/actions/workflows/pages.yaml) [![.github/workflows/release-on-tag.yaml](https://github.com/decaf-ts/ts-workspace/actions/workflows/release-on-tag.yaml/badge.svg?event=release)](https://github.com/decaf-ts/ts-workspace/actions/workflows/release-on-tag.yaml)

![Open Issues](https://img.shields.io/github/issues/decaf-ts/ts-workspace.svg) ![Closed Issues](https://img.shields.io/github/issues-closed/decaf-ts/ts-workspace.svg) ![Pull Requests](https://img.shields.io/github/issues-pr-closed/decaf-ts/ts-workspace.svg) ![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)

![Forks](https://img.shields.io/github/forks/decaf-ts/ts-workspace.svg) ![Stars](https://img.shields.io/github/stars/decaf-ts/ts-workspace.svg) ![Watchers](https://img.shields.io/github/watchers/decaf-ts/ts-workspace.svg)

![Node Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=Node&query=$.engines.node&colorB=blue) ![NPM Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=NPM&query=$.engines.npm&colorB=purple)

现有文件 [这里](https://decaf-ts.github.io/ts-workspace/)

最小大小: 5.6 KB kb gziped

# 说明

@decaf-ts/装饰提供了两种互补能力:

-   一个小型的,建构器风格的API(装饰)来定义和应用可被"风味"所变化的装饰(例如不同的框架或环境),同时保持一个稳定的基于密钥的API.
-   一个集中运行时间元数据存储器(Metadata),用于读取和撰写关于类及其成员的结构化信息,使用反射-元数据进行设计-时间类型提示.

该模块旨在规范不同背景的装饰器的构成、发现和执行,以及在运行期间元数据的存储和询问.

主要组成部分

-   装饰(建筑师和登记处)
    
    -   您为密钥( 例如“ 组件 ”) 创建了装饰管道 .
    -   对于默认的风味 ("decaf"),您用定义(...)定义了底部装饰器.
    -   对于其他花花(如"vue","nest"),可以将底部装饰器(该花花的定義)上覆,也可以用外加(extend (.))来延长.
    -   在运行时,一个全局花香解析器(setFlavour Resolver)决定哪一种花香适用于给定目标. 如果这种风味具有超常功能,则使用;否则,则使用默认的基础装饰. 任何特制外加和默认外加都附加.
    -   应用的结果()是一个装饰器函数,其名称编码了调试的风味和键.
-   装饰设施
    
    -   元数据( key, value): 在类或成员上写入任意的元数据 .
    -   prop (): 抓取一个属性的反射设计: 类型并记录在属性下的元数据中.
    -   应用(. 装饰器):由多种不同种类的装饰器组成并按顺序应用.
    -   propMetadata(键,值):既执行元数据(键,值)又执行prop()的便利厂.
    -   说明(正文):为描述的类别或财产储存一种对人类友好的描述。 分类或描述...
-   元数据存储
    
    -   静态方便 API 由单通实例支持. 它将每个类构建器映射到结构化的元数据对象.
    -   键被嵌入(例如"properties.name","description.class")并使用分解器(默认")来导航.
    -   当镜像被启用(默认)时,内部元数据对象也会被定义在一个稳定而不可设想的密钥(DecorationKeys.REFLECT)下在构造器上进行快速检查.
    -   帮助方法 :
        -   属性(cent):列出已记录类型信息的已知属性名称.
        -   说明(cor, proc?):读取类别或属性的描述.
        -   类型(cor, proc):读取一个属性的已记录设计类型.
        -   获取/ set(cor, key):低水平访问任意路径.

常数和类型

-   默认味素:默认味素标识符 ("decaf").
-   ObjectKeySplitter:嵌入式元数据密钥的分隔符 ("").
-   装饰钥匙:有名的元数据密钥(REFLECT,PROPERTIES,CLAS,DESCRIPTION,设计:型号等).
-   默认元数据:用作基准的默认元数据形状.
-   BasicMetadata / Constructionor:描述元数据结构和类构造器签名的效用类型.

设计要点

-   可编译和风味意识:装饰构建器允许不同的环境或框架在同一语义键下贡献出不同的装饰者行为. 这在构建适配器(如Angular vs React 组件)而不改变用户代码导入时有用.
-   可预测的应用命令:默认的装饰器首先被应用(或使用特有调味器),然后是外加. 外加可以来自默认的口味和/或解开的口味.
-   内源元数据:元数据存储使得直接记录和查询关于模型,属性和行为的运行时间事实. 这对ORM,序列器,验证器和UI绑定器特别有帮助.

# 如何使用

本指南举例说明如何利用《公约》的主要特点 `@decaf-ts/decoration` 图书馆.

## 元数据

这个 `Metadata` class 是运行时类型信息和其他元数据的集中存储.

### 存储和获取元数据

你可以用这个 `@metadata` 装饰者或 `Metadata.set()` 财务报告和审定财务报表 `Metadata.get()` 用于存储和检索某类或其成员的元数据的方法.

```typescript
import { metadata, Metadata } from '@decaf-ts/decoration';

@metadata('my-class-key', 'my-class-value')
class MyClass {
  @metadata('my-prop-key', 'my-prop-value')
  myProp: string;
}

// Retrieve metadata
const classMetadata = Metadata.get(MyClass, 'my-class-key'); // 'my-class-value'
const propMetadata = Metadata.get(MyClass, 'my-prop-key'); // 'my-prop-value'
```

### 处理财产和方法类型

这个 `@prop` 财务报告和审定财务报表 `@method` 装饰器会自动捕捉设计-时间类型信息.

```typescript
import { prop, method, Metadata } from '@decaf-ts/decoration';

class MyService {
  @prop()
  myProperty: string;

  @method()
  myMethod(param1: number): boolean {
    // ...
  }
}

// Retrieve type information
const propType = Metadata.type(MyService, 'myProperty'); // String
const returnType = Metadata.return(MyService, 'myMethod'); // Boolean
const paramTypes = Metadata.params(MyService, 'myMethod'); // [Number]
```

## 装饰

这个 `Decoration` 类允许您以不同的"口味"创建和管理装饰.

### 创建简单的装饰器

```typescript
import { Decoration } from '@decaf-ts/decoration';

const myDecorator = Decoration.for('my-decorator')
  .define((target: any) => {
    console.log('My decorator was applied to', target.name);
  })
  .apply();

@myDecorator
class MyDecoratedClass {}
```

### 创建亮度装饰器

可以为不同的"口味"创建不同版本的装饰.

```typescript
import { Decoration, DefaultFlavour } from '@decaf-ts/decoration';

// Define the default decorator
const defaultDecorator = Decoration.for('my-flavoured-decorator')
  .define((target: any) => {
    console.log('Default decorator applied to', target.name);
  })
  .apply();

// Define a decorator for the 'vue' flavour
const vueDecorator = Decoration.flavouredAs('vue')
  .for('my-flavoured-decorator')
  .define((target: any) => {
    console.log('Vue decorator applied to', target.name);
  })
  .apply();

// Use the default decorator
@defaultDecorator
class MyDefaultClass {}

// Use the 'vue' decorator by setting the flavour
Decoration.setResolver(() => 'vue');

@defaultDecorator
class MyVueClass {}
```

### 扩展装饰

您可以扩展一个带有额外功能的现有装饰.

```typescript
import { Decoration } from '@decaf-ts/decoration';

const baseDecorator = Decoration.for('my-extended-decorator')
  .define((target: any) => {
    console.log('Base decorator applied');
  })
  .apply();

const extendedDecorator = Decoration.for('my-extended-decorator')
  .extend((target: any) => {
    console.log('Extended decorator applied');
  })
  .apply();

@extendedDecorator
class MyExtendedClass {}
// Console output:
// Base decorator applied
// Extended decorator applied
```

## 通用装饰

### `@apply`

这个 `@apply` 装饰器允许您对单个目标应用多个装饰器.

```typescript
import { apply } from '@decaf-ts/decoration';

const decorator1 = (target: any) => { console.log('Decorator 1'); };
const decorator2 = (target: any) => { console.log('Decorator 2'); };

@apply(decorator1, decorator2)
class MyMultipliedClass {}
```

### `@propMetadata` 财务报告和审定财务报表 `@methodMetadata`

这些装饰器是同时应用元数据和捕捉类型信息的快捷键.

```typescript
import { propMetadata, methodMetadata, Metadata } from '@decaf-ts/decoration';

class MyMetaClass {
  @propMetadata('my-key', 'my-value')
  myProp: string;

  @methodMetadata('my-method-key', 'my-method-value')
  myMethod() {}
}

const propMeta = Metadata.get(MyMetaClass, 'my-key'); // 'my-value'
const propType = Metadata.type(MyMetaClass, 'myProp'); // String
const methodMeta = Metadata.get(MyMetaClass, 'my-method-key'); // 'my-method-value'
```

### 相关

[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=decaf-ts&repo=ts-workspace)](https://github.com/decaf-ts/ts-workspace)

### 社会

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/decaf-ts/)

#### 语文

![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white) ![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black) ![NodeJS](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white) ![ShellScript](https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge&logo=gnu-bash&logoColor=white)

## 获得帮助

如果您有错误报告, 请回答问题或建议 [创建一个新问题](https://github.com/decaf-ts/ts-workspace/issues/new/choose)。 。 。 .

## 捐款

我感谢对这一项目作出的任何贡献。 请阅读 [这个](https://npmcn.com/package/%40decaf-ts/decoration/workdocs/98-Contributing.md) 要开始.

## 支助

第一种最简单的方法就是支持它 [捐款](https://npmcn.com/package/%40decaf-ts/decoration/workdocs/98-Contributing.md). 甚至在文档中找到打字很重要.

财政支持总是受到欢迎,帮助我和该项目保持生命和健康.

所以,如果你可以, 如果这个项目以任何方式。 要么通过学习 要么只是帮助你 节省宝贵的时间, 请考虑捐赠.

## 许可证

这个项目将在 [Mozilla 公共许可证2.0](https://npmcn.com/package/%40decaf-ts/decoration/LICENSE.md)。 。 。 .

由开发者为开发者...

## 常见问题

### @decaf-ts/decoration 是什么？

无咖啡因咖啡因的装饰和元数据机制

### 如何安装 @decaf-ts/decoration？

在项目目录运行 npm install @decaf-ts/decoration，或使用 pnpm add / yarn add / bun add。

### @decaf-ts/decoration 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @decaf-ts/decoration 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @decaf-ts/decoration 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @decaf-ts/decoration 可以商用吗？

@decaf-ts/decoration 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @decaf-ts/decoration 的下载量有多少？

根据 npm 官方下载统计，@decaf-ts/decoration 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,190 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @decaf-ts/decoration 还在维护吗？

最新版本 0\.20\.0 发布于 2026/11/07（6 天前）；至今共发布 67 个版本，其中过去 12 个月发布了 33 个；首次发布于 2025/09/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。