Custom Attributes/zh CN: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		自定义属性（Custom Attributes）目前允许您为类型定义和类的已发布属性添加额外的元数据，这些元数据可以通过RTTI（运行时类型信息）进行查询。
2	2
3	3		截至2020年10月，该功能仅在FPC主干版本（即3.3.1）中可用
4	4
5		-	~~## Contents~~
6		-
7		-	* 1 属性可以用来做什么？
8		-	* 2 如何声明属性？
9		-	* 3 如何使用属性？
10		-	* 3.1 查询属性
11		-	* 4 属性特性与Delphi的兼容性
12		-	* 5 完整示例
13		-
14	5		## 属性可以用来做什么？
15	6
16	7		属性用于将特定的元数据与类相关联。例如，您可以使用属性来标记一个类，指定其对应的数据库表名，或者为Web服务类添加一个标识其基本路径的字符串。
17	8
18	9		## 如何声明属性？
19	10
20	11		属性只是从新的系统类型`TCustomAttribute`派生的类。实现此类`TCustomAttribute`后代的构造函数是最重要的特性，因为它们用于向属性传递额外的参数（如上述示例中的关联数据库表名或基本路径）。
21	12
22	13		重要：如果您想在不使用任何参数的情况下使用您的属性类型，则必须自己声明一个无参数的构造函数，因为`TCustomAttribute`的构造函数是私有的。
23	14
24	15		## 如何使用属性？
25	16
26	17		通过将至少一个属性子句放在类型或属性之前，可以将属性绑定到类型或属性。对于类型，属性在类型定义（如类、记录或枚举声明）或唯一类型重声明（例如"TLongInt = type LongInt"）中指定。仅允许类型重声明，不允许仅重命名类型（例如"TLongInt = LongInt"）。
27	18
28	19		如果设置了新的模式开关`PREFIXEDATTRIBUTES`（在Delphi和DelphiUnicode模式下是默认的），则可用属性子句。
29	20
30	21		属性子句的语法如下：
31	22		```
32	23		ATTRIBUTECLAUSE::='[' ATTRIBUTELIST ']'
33	24		ATTRIBUTELIST::=ATTRIBUTE [, ATTRIBUTELIST ]
34	25		ATTRIBUTE::=IDENTIFIER [ ( PARAMLIST ) ]
35	26		PARAMLIST::=CONSTEXPR [, PARAMLIST ]
36	27		```
37	28
38	29		其中，`IDENTIFIER`是属性类的名称。如果属性类的名称以"Attribute"结尾（不区分大小写），则后续可以省略"Attribute"后缀。因此，在以下示例中，`TMyAttribute`和`TMy`是等效的替代方案：
39	30		```
40	31		program tcustomattr;
41	32
42	33		{$mode objfpc}{$H+}$
43	34		{$modeswitch prefixedattributes}
44	35
45	36		type
46	37		TMyAttribute = class(TCustomAttribute)
47	38		constructor Create;
48	39		constructor Create(aArg: String);
49	40		constructor Create(aArg: TGUID);
50	41		constructor Create(aArg: LongInt);
51	42		end;
52	43
53	44		{$M+}
54	45		[TMyAttribute]
55	46		TTestClass = class
56	47		private
57	48		fTest: LongInt;
58	49		published
59	50		[TMyAttribute('Test')]
60	51		property Test: LongInt read fTest;
61	52		end;
62	53		{$M-}
63	54
64	55		[TMyAttribute(1234)]
65	56		[TMy('Hello World')]
66	57		TTestEnum = (
67	58		teOne,
68	59		teTwo
69	60		);
70	61
71	62		[TMyAttribute(IInterface), TMy(42)]
72	63		TLongInt = type LongInt;
73	64
74	65		constructor TMyAttribute.Create;
75	66		begin
76	67		end;
77	68
78	69		// ... 其他构造函数实现 ...
79	70
80	71		constructor TMyAttribute.Create(aArg: String);
81	72		begin
82	73		end;
83	74
84	75		constructor TMyAttribute.Create(aArg: LongInt);
85	76		begin
86	77		end;
87	78
88	79		constructor TMyAttribute.Create(aArg: TGUID);
89	80		begin
90	81		end;
91	82
92	83		begin
93	84
94	85
95	86		begin
96	87
97	88		end.
98	89		```
99	90
100	91		### 查询属性
101	92
102	93		属性可以通过TypInfo和Rtti单元进行访问。
103	94
104	95		对于TypInfo单元，访问属性的方式如下：
105	96
106	97		对于类型：
107	98
108	99		* 使用`TTypeData`中的`AttributesTable`字段、
109	100		* 对`PTypeInfo`使用`GetAttributeTable`、
110	101		* 对属性表使用`GetAttribute`结合索引获取`TCustomAttribute`实例。
111	102
112	103		对于属性：
113	104
114	105		* 使用`TPropInfo`的`AttributesTable`、
115	106		* 对属性表使用`GetAttribute`结合索引获取`TCustomAttribute`实例、
116	107		* 对`PPropInfo`使用`GetPropAttribute`结合索引获取`TCustomAttribute`实例。
117	108
118	109		对于Rtti单元，访问属性的方式如下：
119	110
120	111		对于类型：
121	112
122	113		* 对目标类型的`TRttiType`使用`GetAttributes`。
123	114
124	115		对于属性：
125	116
126	117		* 对目标属性的`TRttiProperty`使用`GetAttributes`。
127	118
128	119		## 属性特性与Delphi的兼容性
129	120
130	121		该特性本身与Delphi兼容，但FPC对未绑定属性的容忍度较低。如果属性类未知或属性子句未绑定到有效的类型或属性，编译器将生成错误。
131	122
132	123		FPC的RTTI不被认为是与Delphi兼容的，但它涵盖了相同的功能。与Delphi（使用Invoke创建属性实例）不同，FPC使用构造函数函数。FPC的实现优势在于它可以在没有完整Invoke支持的系统上工作。
133	124
134	125		此外，使用`PREFIXEDATTRIBUTES`模式开关会禁用函数、方法和过程/方法类型的指令子句。启用`PREFIXEDATTRIBUTES`模式开关后，以下用法不再允许：
135	126		```
136	127		procedure Test; [cdecl];
137	128		begin
138	129
139	130		end;
140	131		```
141	132
142	133		## 完整示例
143	134		```
144	135		program testattributes;
145	136		{
146	137		这是一个简单的示例，说明如何使用自定义属性。
147	138		该类使用自定义属性在程序启动时检索静态日期。这仅用于演示。
148	139		此演示包含：
149	140		- 创建
150	141		- 装饰
151	142		- 检索
152	143		}
153	144
154	145		{$mode delphi}{$H+}{$M+}
155	146		{$warn 5079 off} { 关闭实验性警告 }
156	147		uses
157	148		sysutils, typinfo, rtti, classes;
158	149
159	150		type
160	151		{ 用于装饰类以指定特定日期的自定义属性 }
161	152		ADateTimeAttribute = class(TCustomAttribute)
162	153		private
163	154		FArg:TDateTime;
164	155		public
165	156		{ 展示自定义属性可以有多个构造函数 }
166	157		constructor Create(const aArg: TDateTime);overload;
167	158		{ 我们可以使用预定义的%DATE%编译器包含
168	159		在自定义属性的上下文中，我们需要一个
169	160		常量表达式作为默认参数 }
170	161		constructor Create(const aArg: String = {$I %DATE%});overload;
171	162		published
172	163		property Date:TDateTime read FArg;
173	164		end;
174	165
175	166		{ 使用我们的自定义属性装饰的日期时间类 }
176	167		{ 注意：您可以省略'Attribute'，编译器会解析它 }
177	168		{ [ADateTime(21237.0)] 调用第一个构造函数，显示1958年的某个日期 }
178	169
179	170		{ 这将调用第二个构造函数 }
180	171		[ADateTime]
181	172		TMyDateTimeClass = class
182	173		private
183	174		FDateTime:TDateTime;
184	175		public
185	176		constructor create;
186	177		published
187	178		[ADateTime]
188	179		property Day:TDateTime read FDateTime write FDateTime;
189	180		end;
190	181
191	182		constructor ADateTimeAttribute.Create(const aArg: TDateTime);
192	183		begin
193	184		FArg := aArg;
194	185		end;
195	186
196	187		constructor ADateTimeAttribute.Create(const aArg: string );
197	188		var
198	189		MySettings:TFormatSettings;
199	190		begin
200	191		{ 根据编译器如何格式化%DATE%包含来设置日期格式 }
201	192		MySettings := DefaultFormatSettings;
202	193		MySettings.ShortDateFormat:='yyyymmdd';
203	194		MySettings.DateSeparator :='/';
204	195		{ 现在进行转换 }
205	196		FArg := StrToDateTime(aArg, MySettings);
206	197		end;
207	198
208	199		{ 我们查询rtti来设置值 }
209	200		constructor TMyDateTimeClass.Create;
210	201		var
211	202		Context : TRttiContext;
212	203		AType : TRttiType;
213	204		Attribute : TCustomAttribute;
214	205		begin
215	206		inherited;
216	207		Context := TRttiContext.Create;
217	208		try
218	209		AType := Context.GetType(TypeInfo(TMyDateTimeClass));
219	210		for Attribute in AType.GetAttributes do begin
220	211		if Attribute is ADateTimeAttribute then
221	212		FDateTime := ADateTimeAttribute(Attribute).Date;
222	213		end;
223	214		finally
224	215		Context.Free
225	216		end;
226	217		end;
227	218
228	219		var
229	220		Test:TMyDateTimeClass;
230	221		begin
231	222		Test := TMyDateTimeClass.Create;
232	223		try
233	224		writeln('Compile date is :',DateTimeToStr(Test.Day));
234	225		finally
235	226		Test.Free;
236	227		end;
237	228		end.
238	229		```
239	230
240	231		---
241	232		From the Free Pascal wiki, page "Custom Attributes/zh CN", as the Internet Archive kept it on 2025-05-16, last changed on 2024-07-13. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history