配置

Ionic Config 提供了一种方法，可以在整个应用中全局更改组件的属性。它可以设置应用模式、选项卡按钮布局、动画等。

🌐 Ionic Config provides a way to change the properties of components globally across an app. It can set the app mode, tab button layout, animations, and more.

全局配置

🌐 Global Config

可用的配置键可以在 IonicConfig 接口中找到。

🌐 The available config keys can be found in the IonicConfig interface.

以下示例禁用波纹效果并将模式默认为 Material Design：

🌐 The following example disables ripple effects and default the mode to Material Design:

JavaScript
Angular
Angular (Standalone)
React
Vue

example.js
window.Ionic = {
  config: {
    rippleEffect: false,
    mode: 'md',
  },
};

app.module.ts
import { IonicModule } from '@ionic/angular';

@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      rippleEffect: false,
      mode: 'md'
    })
  ],
  ...
})

main.ts
import { provideIonicAngular } from '@ionic/angular/standalone';

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      rippleEffect: false,
      mode: 'md'
    })
  ]
})

setupIonicReact 函数必须在渲染任何 Ionic 组件（包括 IonApp）之前调用。

🌐 The setupIonicReact function must be called before rendering any Ionic components (including IonApp).

App.tsx
import { setupIonicReact } from '@ionic/react';

setupIonicReact({
  rippleEffect: false,
  mode: 'md',
});

main.ts
import { IonicVue } from '@ionic/vue';
import { createApp } from 'vue';

createApp(App).use(IonicVue, {
  rippleEffect: false,
  mode: 'md',
});

每个组件的配置

🌐 Per-Component Config

Ionic 配置不是响应式的。在组件渲染后更新配置的值将会得到之前的值。建议在需要响应式值时使用组件的属性，而不是更新配置。

🌐 Ionic Config is not reactive. Updating the config's value after the component has rendered will result in the previous value. It is recommended to use a component's properties instead of updating the config, when you require reactive values.

JavaScript
Angular
Angular (Standalone)
React
Vue

不推荐

window.Ionic = {
  config: {
    // Not recommended when your app requires reactive values
    backButtonText: 'Go Back',
  },
};

推荐

<ion-back-button></ion-back-button>

<script>
  const backButton = document.querySelector('ion-back-button');

  /**
   * The back button text can be updated
   * anytime the locale changes.
   */
  backButton.text = 'Go Back';
</script>

不推荐

import { IonicModule } from '@ionic/angular';

@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      // Not recommended when your app requires reactive values
      backButtonText: 'Go Back'
    })
  ],
  ...
});

推荐

<ion-back-button [text]="backButtonText"></ion-back-button>

@Component(...)
class MyComponent {
  /**
   * The back button text can be updated
   * anytime the locale changes.
   */
  backButtonText = 'Go Back';
}

不推荐

import { provideIonicAngular } from '@ionic/angular/standalone';

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      // Not recommended when your app requires reactive values
      backButtonText: 'Go Back'
    })
  ]
})

推荐

<ion-back-button [text]="backButtonText"></ion-back-button>

@Component(...)
class MyComponent {
  /**
   * The back button text can be updated
   * anytime the locale changes.
   */
  backButtonText = 'Go Back';
}

不推荐

import { setupIonicReact } from '@ionic/react';

setupIonicReact({
  // Not recommended when your app requires reactive values
  backButtonText: 'Go Back',
});

推荐

import { useState } from 'react';
import { IonBackButton } from '@ionic/react';

const ExampleComponent = () => {
  const [backButtonText, setBackButtonText] = useState('Go Back');
  return (
    {/*
     * The back button text can be updated
     * anytime the locale changes.
     */}
    <IonBackButton text={backButtonText}></IonBackButton>
  )
}

不推荐

import { IonicVue } from '@ionic/vue';
import { createApp } from 'vue';

// Not recommended when your app requires reactive values
createApp(App).use(IonicVue, {
  backButtonText: 'Go Back',
});

推荐

<template>
  <ion-back-button [text]="backButtonText"></ion-back-button>
</template>

<script setup lang="ts">
  import { IonBackButton } from '@ionic/vue';
  import { ref } from 'vue';

  /**
   * The back button text can be updated
   * anytime the locale changes.
   */
  const backButtonText = ref('Go Back');
</script>

每个平台的配置

🌐 Per-Platform Config

Ionic 配置也可以按每个平台进行设置。例如，这允许你在应用在可能较慢的设备的浏览器中运行时禁用动画。开发者可以利用平台工具来实现这一点。

🌐 Ionic Config can also be set on a per-platform basis. For example, this allows you to disable animations if the app is being run in a browser on a potentially slower device. Developers can take advantage of the Platform utilities to accomplish this.

在以下示例中，仅当 Ionic 应用在移动 Web 浏览器中运行时，我们才会禁用该应用中的所有动画。

🌐 In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser.

Angular
Angular (Standalone)
React
Vue

note

由于配置是在运行时设置的，你将无法访问平台依赖注入。相反，你可以直接使用提供程序使用的底层函数。

请参阅 Angular 平台文档了解你可以检测的平台类型。

🌐 See the Angular Platform Documentation for the types of platforms you can detect. :::

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      animated: !isPlatform('mobileweb')
    })
  ],
  ...
})

note

由于配置是在运行时设置的，你将无法访问平台依赖注入。相反，你可以直接使用提供程序使用的底层函数。

请参阅 Angular 平台文档了解你可以检测的平台类型。

🌐 See the Angular Platform Documentation for the types of platforms you can detect. :::

main.ts
import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      animated: !isPlatform('mobileweb')
    })
  ]
})

note

请参阅 React 平台文档了解你可以检测的平台类型。

App.tsx
import { isPlatform, setupIonicReact } from '@ionic/react';

setupIonicReact({
  animated: !isPlatform('mobileweb'),
});

note

请参阅 Vue 平台文档了解你可以检测的平台类型。

main.ts
import { IonicVue, isPlatform } from '@ionic/vue';

createApp(App).use(IonicVue, {
  animated: !isPlatform('mobileweb'),
});

后备措施

🌐 Fallbacks

下一个示例允许你根据平台设置完全不同的配置，如果没有平台匹配，则回退到默认配置：

🌐 The next example allows you to set an entirely different configuration based upon the platform, falling back to a default config if no platforms match:

Angular
Angular (Standalone)
React
Vue

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

const getConfig = () => {
  let config = {
    animated: false
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous'
    }
  }

  return config;
}
@NgModule({
  ...
  imports: [
    IonicModule.forRoot(getConfig())
  ],
  ...
});

main.ts
import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';

const getConfig = () => {
  let config = {
    animated: false
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous'
    }
  }

  return config;
}

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

App.tsx
import { isPlatform, setupIonicReact } from '@ionic/react';

const getConfig = () => {
  let config = {
    animated: false,
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous',
    };
  }

  return config;
};

setupIonicReact(getConfig());

main.ts
import { IonicVue, isPlatform } from '@ionic/vue';

const getConfig = () => {
  let config = {
    animated: false,
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous',
    };
  }

  return config;
};

createApp(App).use(IonicVue, getConfig());

覆盖

🌐 Overrides

最后一个示例允许你根据不同的平台要求累积配置对象。

🌐 This final example allows you to accumulate a config object based upon different platform requirements.

Angular
Angular (Standalone)
React
Vue

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide'
    }
  }

  return {
    tabButtonLayout: 'icon-top'
  };
}
@NgModule({
  ...
  imports: [
    IonicModule.forRoot(getConfig())
  ],
  ...
});

main.ts
import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';

const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide'
    }
  }

  return {
    tabButtonLayout: 'icon-top'
  };
}

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

App.tsx
import { isPlatform, setupIonicReact } from '@ionic/react';

const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide',
    };
  }

  return {
    tabButtonLayout: 'icon-top',
  };
};

setupIonicReact(getConfig());

main.ts
import { IonicVue, isPlatform } from '@ionic/vue';

const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide',
    };
  }

  return {
    tabButtonLayout: 'icon-top',
  };
};

createApp(App).use(IonicVue, getConfig());

访问模式

🌐 Accessing the Mode

在某些情况下，你可能需要在应用逻辑中以编程方式访问当前的 Ionic 模式。这对于应用条件行为、获取特定资源或根据活动的样式模式执行其他操作非常有用。

🌐 In some cases, you may need to access the current Ionic mode programmatically within your application logic. This can be useful for applying conditional behavior, fetching specific assets, or performing other actions based on the active styling mode.

读取配置（Angular）

🌐 Reading the Config (Angular)

Ionic Angular 提供了一个 Config 提供者用于访问 Ionic 配置。

🌐 Ionic Angular provides a Config provider for accessing the Ionic Config.

get

描述	以 `any` 形式返回配置值。如果配置未定义，则返回 `null`。
签名	`get(key: string, fallback?: any) => any`

示例

🌐 Examples

Angular
Angular (Standalone)

import { Config } from '@ionic/angular';

@Component(...)
class AppComponent {
  constructor(config: Config) {
    const mode = config.get('mode');
  }
}

import { Config } from '@ionic/angular/standalone';

@Component(...)
class AppComponent {
  constructor(config: Config) {
    const mode = config.get('mode');
  }
}

getBoolean

描述	返回一个配置值，类型为 `boolean`。如果配置未定义，则返回 `false`。
函数签名	`getBoolean(key: string, fallback?: boolean) => boolean`

示例

🌐 Examples

Angular
Angular (Standalone)

import { Config } from '@ionic/angular';

@Component(...)
class AppComponent {
  constructor(config: Config) {
    const swipeBackEnabled = config.getBoolean('swipeBackEnabled');
  }
}

import { Config } from '@ionic/angular/standalone';

@Component(...)
class AppComponent {
  constructor(config: Config) {
    const swipeBackEnabled = config.getBoolean('swipeBackEnabled');
  }
}

getNumber

描述	返回一个配置值作为 `number`。如果配置未定义，则返回 `0`。
签名	`getNumber(key: string, fallback?: number) => number`

接口

🌐 Interfaces

IonicConfig

以下是 Ionic 使用的配置选项。

🌐 Below are the config options that Ionic uses.

| 配置 | 类型 | 描述 |

| --- | --- | --- |

| actionSheetEnter | AnimationBuilder | 为所有 ion-action-sheet 提供自定义进入动画，覆盖默认的“动画”。 |

| actionSheetLeave | AnimationBuilder | 为所有 ion-action-sheet 提供自定义离开动画，覆盖默认的“动画”。 |

| alertEnter | AnimationBuilder | 为所有 ion-alert 提供自定义进入动画，覆盖默认的“动画”。 |

| alertLeave | AnimationBuilder | 为所有 ion-alert 提供自定义离开动画，覆盖默认的“动画”。 |

| animated | boolean | 如果 true，Ionic 将在整个应用中启用所有动画和过渡。 |

| backButtonDefaultHref | string | 覆盖所有 <ion-back-button> 组件中 defaultHref 属性的默认值。 |

| backButtonIcon | string | 覆盖所有 <ion-back-button> 组件中的默认图标。 |

| backButtonText | string | 覆盖所有 <ion-back-button> 组件中的默认文本。 |

| innerHTMLTemplatesEnabled | boolean | 相关组件：ion-alert、ion-infinite-scroll-content、ion-loading、ion-refresher-content、ion-toast。如果 true，传递给相关组件的内容将被解析为 HTML 而不是纯文本。默认值为 false。 |

| hardwareBackButton | boolean | 如果 true，Ionic 将会响应安卓设备上的硬件返回按钮。 |

| infiniteLoadingSpinner | SpinnerTypes | 在所有 <ion-infinite-scroll-content> 组件中覆盖默认的加载动画类型。 |

| loadingEnter | AnimationBuilder | 为所有 ion-loading 提供自定义进入动画，覆盖默认的“动画”。 |

| loadingLeave | AnimationBuilder | 为所有 ion-loading 提供自定义离开动画，覆盖默认的“动画”。 |

| loadingSpinner | SpinnerTypes | 覆盖所有 ion-loading 覆盖层的默认加载动画。 |

| menuIcon | string | 覆盖所有 <ion-menu-button> 组件中的默认图标。 |

| menuType | string | 覆盖所有 <ion-menu> 组件的默认菜单类型。 |

| modalEnter | AnimationBuilder | 为所有 ion-modal 提供自定义进入动画，覆盖默认的“动画”。 |

| modalLeave | AnimationBuilder | 为所有 ion-modal 提供自定义离开动画，覆盖默认的“动画”。 |

| mode | Mode | 该模式决定整个应用使用哪种平台样式。 |

| navAnimation | AnimationBuilder | 覆盖整个应用中所有 ion-nav 和 ion-router-outlet 的默认“动画”。 |

| pickerEnter | AnimationBuilder | 为所有 ion-picker 提供自定义进入动画，覆盖默认的“动画”。 |

| pickerLeave | AnimationBuilder | 为所有 ion-picker 提供自定义离开动画，覆盖默认的“动画”。 |

| platform | PlatformConfig | 覆盖默认的平台检测方法。 |

| popoverEnter | AnimationBuilder | 为所有 ion-popover 提供自定义进入动画，覆盖默认的“动画”。 |

| popoverLeave | AnimationBuilder | 为所有 ion-popover 提供自定义离开动画，覆盖默认的“动画”。 |

| refreshingIcon | string | 覆盖所有 <ion-refresh-content> 组件中的默认图标。 |

| refreshingSpinner | SpinnerTypes | 在所有 <ion-refresh-content> 组件中覆盖默认的加载动画类型。 |

| rippleEffect | boolean | 如果 true，Material Design 水波纹效果将在整个应用中启用。 |

| sanitizerEnabled | boolean | 如果 true，Ionic 将在接受自定义 HTML 的组件属性上启用基本的 DOM 清理器。 |

| spinner | SpinnerTypes | 覆盖所有 <ion-spinner> 组件中的默认加载动画。 |

| statusTap | boolean | 如果 true，点击或轻触状态栏将使内容滚动到顶部。 |

| swipeBackEnabled | boolean | 如果 true，Ionic 将在整个应用中启用“滑动返回”手势。 |

| tabButtonLayout | TabButtonLayout | 覆盖整个应用中所有 ion-bar-button 的默认“布局”。 |

| toastDuration | number | 覆盖所有 ion-toast 组件的默认 duration。 |

| toastEnter | AnimationBuilder | 为所有 ion-toast 提供自定义进入动画，覆盖默认的“动画”。 |

| toastLeave | AnimationBuilder | 为所有 ion-toast 提供自定义离开动画，覆盖默认的“动画”。 |

| toggleOnOffLabels | boolean | 覆盖所有 ion-toggle 组件中的默认 enableOnOffLabels。 |

| experimentalCloseWatcher | boolean | 实验性： 如果 true，将使用 CloseWatcher API 来处理所有 Escape 键和硬件返回按钮的按下，以关闭菜单和覆盖层并进行导航。请注意，hardwareBackButton 配置选项也必须为 true。 |

| focusManagerPriority | FocusManagerPriority[] | 实验性: 当定义时，Ionic 会在每次页面过渡后将焦点移动到相应的元素。这确保依赖辅助技术的用户在页面过渡发生时得到通知。默认情况下处于禁用状态。 |

全局配置​

每个组件的配置​

每个平台的配置​

后备措施​

覆盖​

访问模式​

读取配置（Angular）​

get​

示例​

getBoolean​

示例​

getNumber​

接口​

IonicConfig​

目录

全局配置

每个组件的配置

每个平台的配置

后备措施

覆盖

访问模式

读取配置（Angular）

get

示例

getBoolean

示例

getNumber

接口

IonicConfig