Skip to content

README.md

Latest commit

 

History

History
276 lines (215 loc) · 7.53 KB

README.md

File metadata and controls

276 lines (215 loc) · 7.53 KB
Raw

@nstudio/nativescript-toolbar

iOS UIToolbar with first-class UIBarButtonItem and UIToolbarAppearance support.

npm install @nstudio/nativescript-toolbar

Platform Support

  • iOS: fully implemented (UIToolbar)
  • Android: no-op placeholder (toolbar is a native iOS component, but Android users can still install the plugin without errors)

Usage

NativeScript Core (programmatic)

import { Color, EventData, Page } from '@nativescript/core';
import {
  NToolbar,
  ToolbarItemTapEventData,
  ToolbarItem,
} from '@nstudio/nativescript-toolbar';

export function navigatingTo(args: EventData) {
  const page = args.object as Page;

  const toolbar = new NToolbar();
  toolbar.height = 44;
  toolbar.barStyle = 'default';
  toolbar.translucent = true;
  toolbar.tintColor = new Color('#2563eb');

  const items: ToolbarItem[] = [
    { systemItem: 'add', onTap: () => console.log('Add') },
    { systemItem: 'flexibleSpace' },
    { title: 'Edit', style: 'plain', onTap: () => console.log('Edit') },
    { systemItem: 'fixedSpace', width: 8 },
    { systemImage: 'gearshape', onTap: () => console.log('Settings') },
  ];

  toolbar.setItems(items, true);

  toolbar.on(
    NToolbar.itemTapEvent,
    (event: ToolbarItemTapEventData) => {
      console.log('Tapped index:', event.data.index);
      console.log('Tapped descriptor id:', event.data.item.id);
    }
  );

  page.content = toolbar;
}

Angular registration

import { registerElement } from '@nativescript/angular';
import { NToolbar } from '@nstudio/nativescript-toolbar';

registerElement('NToolbar', () => NToolbar);

Angular usage

<!-- any Angular component template -->
<NToolbar
  #toolbar
  height="44"
  barStyle="default"
  translucent="true"
  tintColor="#2563eb"
  (loaded)="onToolbarLoaded($event)"
  (itemTap)="onToolbarTap($event)">
</NToolbar>
import { Component } from '@angular/core';
import { EventData } from '@nativescript/core';
import { NToolbar, ToolbarItem, ToolbarItemTapEventData } from '@nstudio/nativescript-toolbar';

@Component({
  selector: 'demo-toolbar',
  templateUrl: './demo-toolbar.component.html',
})
export class DemoToolbarComponent {
  onToolbarLoaded(args: EventData) {
    const toolbar = args.object as NToolbar;
    const items: ToolbarItem[] = [
      { id: 'compose', systemItem: 'compose' },
      { systemItem: 'flexibleSpace' },
      { id: 'publish', title: 'Publish', style: 'done' },
      { systemItem: 'fixedSpace', width: 8 },
      { id: 'filters', systemImage: 'slider.horizontal.3' },
    ];
    toolbar.setItems(items, true);
  }

  onToolbarTap(args: ToolbarItemTapEventData) {
    console.log('Tapped:', args.data.item?.id ?? args.data.index);
  }
}

React registration

import { registerElement } from 'react-nativescript';
import { NToolbar } from '@nstudio/nativescript-toolbar';

registerElement('nToolbar', () => NToolbar);

Solid registration

import { registerElement } from 'dominative';
import { NToolbar } from '@nstudio/nativescript-toolbar';

registerElement('nToolbar', NToolbar);

Svelte registration

import { registerNativeViewElement } from '@nativescript-community/svelte-native/dom';
import { NToolbar } from '@nstudio/nativescript-toolbar';

registerNativeViewElement('nToolbar', () => NToolbar);

Vue registration

import { registerElement } from 'nativescript-vue';
import { NToolbar } from '@nstudio/nativescript-toolbar';

registerElement('NToolbar', () => NToolbar);

API

Class

NToolbar extends View.

Properties

  • items: ToolbarItem[]
  • barStyle: 'default' | 'black' | 'blackOpaque' | 'blackTranslucent' | number
  • translucent: boolean
  • barTintColor: string | Color | UIColor
  • tintColor: string | Color | UIColor
  • position: 'any' | 'bottom' | 'top' | 'topAttached' | number
  • defaultMetrics: 'default' | 'compact' | 'defaultPrompt' | 'compactPrompt' | 'landscapePhone' | 'landscapePhonePrompt' | number
  • itemChangesAnimated: boolean
  • standardAppearance: ToolbarAppearance (iOS 13+)
  • compactAppearance: ToolbarAppearance (iOS 13+)
  • scrollEdgeAppearance: ToolbarAppearance (iOS 15+)
  • compactScrollEdgeAppearance: ToolbarAppearance (iOS 15+)

Events

  • itemTap: raised when a descriptor-backed tappable item is pressed (ToolbarItemTapEventData)

Methods

  • setItems(items: ToolbarItem[], animated?: boolean): void
  • getNativeItems(): UIBarButtonItem[]
  • getNativeItem(indexOrId: number | string): UIBarButtonItem | null
  • setAppearance(slot: 'standard' | 'compact' | 'scrollEdge' | 'compactScrollEdge', appearance: ToolbarAppearance): void
  • setBackgroundImage(image, position?, metrics?): void
  • getBackgroundImage(position?, metrics?): UIImage | null
  • clearBackgroundImage(position?, metrics?): void
  • setShadowImage(image, position?): void
  • getShadowImage(position?): UIImage | null
  • clearShadowImage(position?): void

ToolbarItem

ToolbarItem supports native and high-level item creation:

type ToolbarItem = {
  id?: number | string;
  nativeItem?: UIBarButtonItem; // escape hatch: pass fully native item

  systemItem?: ToolbarSystemItem; // done, add, flexibleSpace, fixedSpace, etc.
  title?: string;
  style?: 'plain' | 'bordered' | 'done' | 'prominent' | number;
  image?: string | ImageSource | UIImage; // supports sys:// (sf:// and symbol:// aliases also supported)
  systemImage?: string; // SF Symbol name
  landscapeImagePhone?: string | ImageSource | UIImage;
  customView?: View | UIView | (() => View | UIView);

  width?: number;
  enabled?: boolean;
  tintColor?: string | Color | UIColor;
  tag?: number;
  accessibilityIdentifier?: string;

  // iOS 14+ menu/action support
  menu?: UIMenu;
  primaryAction?: UIAction;

  // iOS 15+/16+/17+ optional flags
  changesSelectionAsPrimaryAction?: boolean;
  selected?: boolean;
  hidden?: boolean;
  springLoaded?: boolean;
  symbolAnimationEnabled?: boolean;

  onTap?: (args: ToolbarItemTapEventData) => void;
}

ToolbarSystemItem supports:

  • done, cancel, edit, save, add
  • flexibleSpace, fixedSpace
  • compose, reply, action, organize, bookmarks
  • search, refresh, stop, camera, trash
  • play, pause, rewind, fastForward
  • undo, redo, pageCurl, close, writingTools

Appearance API (UIToolbarAppearance, iOS 13+)

toolbar.standardAppearance = {
  preset: 'opaque',
  backgroundColor: '#ffffff',
  shadowColor: '#e5e7eb',
  buttonAppearance: {
    normal: {
      titleTextAttributes: {
        foregroundColor: '#111827',
      },
    },
    highlighted: {
      titleTextAttributes: {
        foregroundColor: '#2563eb',
      },
    },
  },
};

toolbar.scrollEdgeAppearance = {
  preset: 'transparent',
  backgroundEffectStyle: 'systemThinMaterial',
};

ToolbarAppearance options:

  • preset: 'default' | 'opaque' | 'transparent'
  • backgroundColor
  • backgroundEffectStyle (UIBlurEffectStyle name or numeric value)
  • backgroundImage
  • backgroundImageContentMode
  • shadowColor
  • shadowImage
  • buttonAppearance
  • doneButtonAppearance
  • prominentButtonAppearance (if available on the OS/runtime)

Native Escape Hatch

For any unsupported edge case, create UIBarButtonItem yourself and pass it via ToolbarItem.nativeItem. The plugin will still place it in the toolbar and keep getNativeItems()/getNativeItem() in sync.

License

Apache License Version 2.0