Конфигурация

Настройки, которые ваше расширение объявляет в contributes.config, хранятся под ключами с префиксом идентификатора вашего расширения: <publisher>.<name>.<property>.

Типы на этой странице (ConfigHandle, ConfigChangeEvent и остальные) не экспортируются из @fragmenta/extension, их структура приведена для справки.

getConfig

getConfig(section?: string, overrideIdentifier?: ConfigOverrideIdentifier): ConfigHandle

Возвращает дескриптор, ограниченный section — передайте префикс, чтобы читать ключи относительно него. Без section дескриптор охватывает все настройки.

const config = sdk.workspace.getConfig(`${context.extension.id}.guessNumber`)

const max = config.get<number>('maxNumber', 10)

Значения являются действующими: для каждого ключа берётся значение из первого источника, в котором есть значение, в таком порядке — policy, memory, team, project, user, application, default (объявленные значения по умолчанию).

Дескриптор — это снимок, сделанный при вызове getConfig: при изменении настроек он не меняется. Вызовите getConfig снова — например, в onDidChangeConfig, чтобы прочитать свежие значения.

ConfigHandle

| Опция | Описание | | --- | --- | | get<T>() | Вся секция объектом. | | get<T>(key) | Значение по key относительно секции; пути через точку вроде 'a.b' работают. undefined, если значения нет. | | get<T>(key, defaultValue) | То же, но возвращает defaultValue, если значение undefined. | | has(key) | Есть ли у key значение — задекларированные значения по умолчанию тоже считаются. | | keys() | Имена непосредственных дочерних элементов секции, без вложенных путей. | | update(key, value, target?, overrideIdentifier?) | Записать значение — см. update. |

interface ConfigHandle {
  has(key: string): boolean
  get<T>(): T | undefined
  get<T>(key: string): T | undefined
  get<T>(key: string, defaultValue: T): T
  keys(): string[]
  update(key: string, value: ConfigData, target?: ConfigTarget, overrideIdentifier?: ConfigOverrideIdentifier): void
}

type ConfigData = string | number | boolean | null | ConfigObject | ConfigArray | undefined

interface ConfigObject extends Record<string, ConfigData> {}
interface ConfigArray extends Array<ConfigData> {}

type ConfigTarget = 'memory' | 'user' | 'project' | 'team' | 'application' | 'policy' | 'default'

interface ConfigOverrideIdentifier {
  resource?: string
  custom?: string
}

update

update(key: string, value: ConfigData, target?: ConfigTarget, overrideIdentifier?: ConfigOverrideIdentifier): void

• key задаётся относительно секции handle'а: у handle'а с секцией записывается ключ <section>.<key>.
• target — одно из 'memory' | 'user' | 'project' | 'team' | 'application' | 'policy' | 'default', по умолчанию 'user'.
• update возвращает void: запись отправляется без ожидания применения. Handle'ы, полученные из getConfig после этого, уже видят новое значение; onDidChangeConfig срабатывает, когда изменение применено.

onDidChangeConfig

onDidChangeConfig(listener: (e: ConfigChangeEvent) => void): IDisposable

Срабатывает на любое изменение настроек — для всех ключей, не только вашего расширения.

| Опция | Описание | | --- | --- | | keys | Полные ключи, которые изменились. | | overrides | Ключи, изменённые для конкретных override'ов, сгруппированные по идентификаторам. | | source | ConfigTarget, из которого пришло изменение. | | sourceConfig | Расширениям не передаётся — всегда undefined. | | affectsConfig(key, overrideIdentifier?) | Затрагивает ли изменение key. |

affectsConfig(key) возвращает true, если изменённый ключ равен key или является его родителем: изменение a.b затрагивает a.b.c. Изменение дочернего ключа родителя не затрагивает — изменение a.b.c не затрагивает a.b, — поэтому передавайте полный ключ, который читаете:

context.subscriptions.push(
  sdk.workspace.onDidChangeConfig((event) => {
    if (event.affectsConfig(`${context.extension.id}.guessNumber.maxNumber`)) {
      // перечитать значение
    }
  }),
)

С overrideIdentifier affectsConfig также учитывает ключи, изменённые для этого override'а: resource и custom должны совпадать оба, а идентификатор без обоих полей подходит к любому override'у.

interface ConfigChangeEvent {
  readonly keys: string[]
  readonly overrides: Array<{
    identifiers: ConfigOverrideIdentifier[]
    keys: string[]
  }>
  readonly source: ConfigTarget
  readonly sourceConfig?: ConfigData
  affectsConfig(key: string, overrides?: ConfigOverrideIdentifier): boolean
}