Sign in Join
Wiki copytemporary

xmlconf/ru: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: xmlconf/ru

OldNewLine
1+Модуль XMLConf предоставляет компонент TXMLConfig. Он использует объект TXMLDocument для чтения и записи XML-файла, но происходит непосредственно от TComponent.
2+
3+##### Отказ от ответственности
4+
5+Эта документация не является официальной, она основана на обычном процессе 1) изучения исходного кода; 2) экспериментирования; 3) размышлений: «Интересно, это ли имел в виду автор?»
6+
7+## Свойства и процедуры
8+
9+##### property Filename
10+
11+``` pascal
12+property Filename: String (published)
13+```
14+
15+Имя XML-файла. Установка другого имени файла:
16+
17+- Очищает текущий xml-файл.
18+- Освобождает объект xmldocument
19+- Если *Filename* существует и *StartEmpty* имеет значение false:
20+ - Новый xmldocument создается путем чтения файла, который должен иметь тот же root элемент, что и *RootName*, в противном случае возникает исключение.
21+ - В противном случае создается новый объект xmldocument с корневым элементом *RootName*
22+
23+*Я не проверял это экспериментально, но похоже, что пустой xmldocument создается (в памяти) при создании компонента, и это можно изменить. Однако его нельзя сохранить, пока у него не будет имени файла - нет имени файла по умолчанию - следовательно, все изменения неизбежно будут потеряны, когда имя файла будет установлено*.
24+
25+##### property StartEmpty
26+
27+``` pascal
28+property StartEmpty: Boolean (published)
29+```
30+
31+Определяет, читается ли существующий xmlfile из *Filename*.
32+
33+- По умолчанию false - читается существующий файл.
34+
35+##### property RootName
36+
37+``` pascal
38+property RootName: DOMString (published)
39+```
40+
41+Имя root элемента в файле. Должно соответствовать значению в файле при чтении существующего файла.
42+
43+- По умолчанию - 'CONFIG'. *Проще всего оставить это в покое, если у вас нет веской причины это менять*.
44+
45+##### procedure Flush
46+
47+``` pascal
48+procedure Flush (public)
49+```
50+
51+Записывает файл xml - если задано имя файла.
52+
53+##### procedure Clear
54+
55+``` pascal
56+procedure Clear (public)
57+```
58+
59+Воссоздает xmldocument как пустой документ.
60+
61+##### constructor Create
62+
63+``` pascal
64+constructor Create(AOwner: TComponent) (public)
65+```
66+
67+##### destructor Destroy
68+
69+``` pascal
70+destructor Destroy (public)
71+```
72+
73+## Работа с ключами и путями
74+
75+XMLConfig поддерживает «стек» путей (как массив широких строк). Общий путь к элементу может быть `<rootName>/key1/key2/key3/key4/value="some_value".`
76+
77+Это будет выглядеть в файле в виде
78+
79+``` xml
80+<CONFIG>
81+ <key1>
82+ <key2>
83+ <key3>
84+ <key4 value="some_value"/>
85+ </key3>
86+ </key2>
87+ </key1>
88+</CONFIG>
89+```
90+
91+(пренебрегая любыми другими элементами). Однако стек путей может содержать пути, а не только узлы, поэтому он может состоять как из четырех элементов глубиной `key1;key2; key3;key4`, так и точно так же только двух элементов `key1/key2;key3/key4`, или трех элементов `key1;key2/key3;key4`.
92+
93+Кроме того, при чтении или установке значения можно указать полный путь, так что можно полностью игнорировать «стек» пути и указать полный путь (после *RootName*) для каждого значения. У каждого значения есть эффективный путь, а стек путей - это просто удобный способ добраться до конкретного эффективного пути.
94+
95+##### procedure OpenKey
96+
97+``` pascal
98+procedure OpenKey(const aPath: WideString) (public)
99+```
100+
101+"Помещает" aPath в стек. Если текущий путь был `<RootName>/key1` и `aPath = key2/key3`, после вызова OpenKey текущий путь будет `<RootName>/key1/key2/key3`.
102+
103+##### procedure CloseKey
104+
105+``` pascal
106+procedure CloseKey (public)
107+```
108+
109+"Выталкивает" верхний путь из стека. Обратите внимание, что это последний введенный путь, а НЕ верхний(предыдущий) элемент. Таким образом, после приведенного выше примера OpenKey, за которым следует вызов CloseKey, стек возвращается к `<RootName>/key1`, а не `<RootName>/key1/key2`.
110+
111+##### procedure ResetKey
112+
113+``` pascal
114+procedure ResetKey (public)
115+```
116+
117+Полностью очищает стек. Эффективный путь возвращается к `<RootName>`
118+
119+## Получение, установка и удаление значений
120+
121+Все значения фактически читаются и записываются как строки, а другие перегруженные типы предоставляют определенные переводы 'AsString'.
122+
123+##### function GetValue: WideString / procedure SetValue(const APath: WideString; const AValue: WideString)
124+
125+``` pascal
126+function GetValue(const APath: WideString; const ADefault: WideString): WideString (public)
127+```
128+
129+``` pascal
130+procedure SetValue(const APath: WideString; const AValue: WideString) (public)
131+```
132+
133+Устанавливает или получает строковое значение из *RootName* / *Текущий_путь_из_стэка* / *APath*. Путь создается, если он не существует в сеттере, и ADefault возвращается, если путь не существует в геттере.
134+
135+##### function GetValue: Integer / procedure SetValue(const APath: WideString; AValue: Integer)
136+
137+``` pascal
138+function GetValue(const APath: WideString; ADefault: Integer): Integer; (public)
139+```
140+
141+``` pascal
142+procedure SetValue(const APath: WideString; AValue: Integer); (public)
143+```
144+
145+Целочисленные значения преобразуются в/из строк с помощью функций `IntToStr` и `strToIntDef`.
146+
147+##### function GetValue: Boolean / procedure SetValue(const APath: WideString; AValue: Boolean)
148+
149+``` pascal
150+function GetValue(const APath: WideString; ADefault: Boolean): Boolean; (public)
151+```
152+
153+``` pascal
154+procedure SetValue(const APath: WideString; AValue: Boolean); (public)
155+```
156+
157+Логические значения сохраняются как "True" или "False".
158+
159+> **Warning:** некоторые другие компоненты FCL/LCL XML (например, производные от TCustomPropertyStorage, такие как TXMLPropStorage) хранят логические значения с использованием целочисленных значений, несмотря на использование XMLConifg в качестве компонента хранения. Это, конечно, проблема только в том случае, если вы используете одни и те же файлы из обоих компонентов или переключаетесь с одного на другой во время разработки, как это сделал я
160+
161+.
162+
163+##### procedure SetDeleteValue(const APath: WideString; const AValue, DefValue: WideString) / procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Integer) / procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Boolean)
164+
165+``` pascal
166+procedure SetDeleteValue(const APath: WideString; const AValue, DefValue: WideString); (public)
167+```
168+
169+``` pascal
170+procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Integer); (public)
171+```
172+
173+``` pascal
174+procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Boolean); (public)
175+```
176+
177+Если `AValue = DefValue`, элемент удаляется. В противном случае устанавливается значение AValue.
178+
179+*Я не использовал это, но предположительно мог бы использовать для хранения, например, значений свойств с четко определенными значениями по умолчанию, только если они отличаются от значений по умолчанию*.
180+
181+##### procedure DeletePath(const APath: WideString)
182+
183+``` pascal
184+procedure DeletePath(const APath: WideString); (public)
185+```
186+
187+Удаляет **все** за пределами пути APath
188+
189+##### procedure DeleteValue(const APath: WideString)
190+
191+``` pascal
192+procedure DeleteValue(const APath: WideString); (public)
193+```
194+
195+Удаляет **значение**, указанное APath. Если APath не указывает значение, он ничего не делает
196+
197+##### property Modified: Boolean read FModified
198+
199+``` pascal
200+property Modified: Boolean read FModified; (public)
201+```
202+
203+Позволяет узнать, был ли изменен xmldocument и, следовательно, необходимо ли его очистить.
204+
205+*Однако процедура `Flush` ничего не делает, если документ не изменен, поэтому в любом случае проще просто вызвать процедуру `Flush`*.
206+
207+## Пример
208+
209+Следующая последовательность инструкций:
210+
211+``` pascal
212+ XmlConfig1.Filename := FILE_NAME ; // читаем файл, если он уже существует, но ...
213+ XmlConfig1.Clear ; // если файл уже существует, то очищаем данные, потому что хотим начать с нуля
214+ XmlConfig1.SetValue ('L1/L2/L3', '333') ; // добавляем немного данных
215+ XmlConfig1.SetValue ('L1/L2/L4', '44') ;
216+ XmlConfig1.SetValue ('L1/L2/L3', '33') ; // это перезапишет предыдущее значение
217+ XmlConfig1.OpenKey ('L1/L2') ; // с этого момента все ключи будут относиться к L1/L2
218+ XmlConfig1.SetValue ('Lm', 'mm') ; // они будут добавлены в L1/L2
219+ XmlConfig1.SetValue ('Lm/Ln', 'nn') ;
220+ XmlConfig1.SetValue ('/Lx/Ly', 'yy') ; // и из-за начального символа '/' оно будет добавлено в root
221+ XmlConfig1.CloseKey ;
222+ XmlConfig1.SetValue ('L6/L7', '77') ; // L6 будет удален
223+ XmlConfig1.SetValue ('L9', '99') ;
224+ XmlConfig1.SetValue ('L9/L99', '9999') ; // Предыдущее L9 было атрибутом, теперь оно будет узлом
225+ XmlConfig1.DeletePath ('L6') ;
226+ XmlConfig1.Flush ;
227+```
228+
229+даст такой XML:
230+
231+``` xml
232+ <?xml version="1.0" encoding="utf-8"?>
233+ <CONFIG L9="99">
234+ <L1>
235+ <L2 L3="33" L4="44" Lm="mm">
236+ <Lm Ln="nn"/>
237+ </L2>
238+ </L1>
239+ <Lx Ly="yy"/>
240+ <L9 L99="9999"/>
241+ </CONFIG>
242+```
243+
244+Обратите внимание, что последний элемент в параметре aPath для SetValue на самом деле является атрибутом: `XmlConfig1.SetValue ('L1/L2/L3', '333')` фактически задает атрибут `L3` для элемента `L1/L2`.
245+
246+------------------------------------------------------------------------
247+
248+## См.также
249+
250+- XMLConf/TXMLConf представлен в пакете [[fcl-xml]].
251+
252+---
253+*From the Free Pascal wiki, page "xmlconf/ru", as it stood on 2022-01-02 after a change by FTurtle, out of the wiki's dump of 2024-05-26. 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