版本：v8

設定

Ionic Config 提供一種方法來全域變更應用程式中元件的屬性。它可以設定應用程式模式、索引標籤按鈕版面配置、動畫等等。

全域設定

可用的設定鍵可以在 IonicConfig 介面中找到。

以下範例會停用漣漪效果，並將模式預設為 Material Design

JavaScript
Angular
Angular (獨立)
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'
    })
  ]
})

必須在渲染任何 Ionic 元件 (包括 IonApp) 之前呼叫 setupIonicReact 函數。

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',
});

每個元件設定

Ionic Config 不是反應式的。在元件渲染後更新設定的值將會導致先前的值。當您需要反應式的值時，建議使用元件的屬性，而不是更新設定。

JavaScript
Angular
Angular (獨立)
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>

每個平台設定

Ionic Config 也可以在每個平台設定。例如，如果應用程式在可能速度較慢的裝置上的瀏覽器中執行，這可以讓您停用動畫。開發人員可以利用平台工具來達成此目的。

在以下範例中，我們僅在應用程式在行動網路瀏覽器中執行時，停用我們 Ionic 應用程式中的所有動畫。

Angular
Angular (獨立)
React
Vue

注意

由於設定是在執行階段設定的，因此您將無法存取平台依賴性注入。相反地，您可以直接使用提供者使用的底層函數。

請參閱Angular 平台文件，了解您可以偵測的平台類型。

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

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

注意

由於設定是在執行階段設定的，因此您將無法存取平台依賴性注入。相反地，您可以直接使用提供者使用的底層函數。

請參閱Angular 平台文件，了解您可以偵測的平台類型。

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

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

注意

請參閱React 平台文件，了解您可以偵測的平台類型。

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

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

注意

請參閱Vue 平台文件，了解您可以偵測的平台類型。

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

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

回退

下一個範例可讓您根據平台設定完全不同的設定，如果沒有任何平台符合，則會回退至預設設定

Angular
Angular (獨立)
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());

覆寫

最後一個範例可讓您根據不同的平台需求累積設定物件。

Angular
Angular (獨立)
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());

讀取設定 (Angular)

Ionic Angular 提供一個 Config 提供者，用於存取 Ionic Config。

get

描述	傳回設定值為 `any`。如果未定義設定，則傳回 `null`。
簽名	`get(key: string, fallback?: any) => any`

範例

Angular
Angular (獨立)

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`

範例

Angular
Angular (獨立)

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`

介面

IonicConfig

以下是 Ionic 使用的設定選項。

設定	類型	描述
`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 將回應 Android 裝置中的硬體返回按鈕。
`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