@mamba/flatlist

12.1.0 • Public • Published

Flatlist

O componente Flatlist serve para renderizar listas simples e básicas com utilização de setas(UP / DOWN) do teclado e touch.

Propriedades Descrição Tipo Padrão
renderItem Recebe o Component onde os items serão renderizados Component null
renderTitle Define um component para ser usado Título das seções. Caso seja omitido, sera renderizado um título padrão Component null
data Recebe um objeto com os itens que seram renderizados object null
dataSection Recebe um objeto com os itens que seram renderizados em sessões object null
className Classe a ser adicionado ao elemento pai do componente string ``
style Define os estilos para o container pai do FlatList, podendo ser uma string ou um objeto de propriedades CSS em JavaScript string object
separator Define um separador para as seções. Caso seja omitido, sera renderizado o separador padrão Component null
showSeparator Define se deve mostrar o separador boolean true
intersectSelectedEvents Previne chamadas iguais de eventos: itemSelectedonSelected boolean false
autoSelectOnTouch Define se dispara a classe para realçar o item quando for selecionado por touch boolean true
autoShortcuts Define se os shortcuts serão gerados automaticamente com base nos índices (max. 0-9) boolean false
decorator Define um objeto padrão que irá para todos os items da listagem object undefined
decoratorOverrides Define um objeto que irá sobrescrever a propriedade decorator. object undefined
overrideEnterKeystroke Define se o FlatList sempre vai ter prioridade no evento de enter do teclado boolean true
disableEnterKeystroke Define se o FlatList deve habilitar ou desabilitar o evento de enter boolean false
disabled Permite desabilitar os eventos da FlatList e das Rows boolean false
selectedIndex Define a linha que irá estar selecionada quando for criado a lista number 0
navBar Permite habilitar a barra de navegação pelo touch ou teclas de seta boolean false
navDownLabel Texto definido para o botão de descer string Diminuir
navUpLabel Texto definido para o botão de subir string Aumentar
showPrefix Define se deve mostrar o prefixo boolean true

Métodos

Método Descrição
render(current?: any[] | Record<string, any>) Renderiza a lista com o estado atual ou passando uma lista customizada.
setSelected(rowData: DefaultRowProps | Record<string, any>, isKeystroke = false) Seleciona um item da lista programaticamente.
hide() Esconde a lista. Útil para não precisar redesenhar a lista em alguns cenários e salvar processamento.
show() Mostra a lista.

Eventos

<Flatlist ... on:active="itemActive(event)" on:selected="itemSelected(event)" />

Eventos Disparado quando ... Tipo
active Recebe os propriedades do item que esta ativo/selecionado function(event)
selected Recebe os propriedades do item que foi selecionado por click ou teclado function(event)
setup Configura elemento que recebe entrada(input) como primeiro item para ser simulado como linha da lista. ⚠️ Este elemento precisa ser uma referência de um HTMLElement. Se o componente Svelte pai desse elemento DOM tiver a propriedade autofocus, também precisa ser retirado. O setupFirstFocusable retorna true ou false se obteve todos os requisitos. function({ setupFirstFocusable: ({ element, forwardedRef = undefined }) => Boolean })

Exemplo de configuração do on:setup

Declarando um método on:setup no Flatlist e o Input que irá funcionar como linha da lista:

<!-- Lembre-se de não setar a propriedade `autofocus`, senão terá um comportamento inadequado. -->
<MoneyInput ref:moneyInput />

<FlatList ... on:setup="setupFlatlist(event)" />

Exemplo de método:

<script>
  export default {
    methods: {
      setupFlatlist({ setupFirstFocusable }) {
        const { refs: { moneyInput: element } = {} } = this;

        // Verificando se o componente pai esta renderizado
        if (element && element.refs && element.refs.amountInput) {
          // Desconstruindo o <input> da lista de referências do pai
          const { amountInput } = element.refs;

          // Chama a função
          setupFirstFocusable({
            element: amountInput,
            forwardedRef: 'input',
          });
        }
      },
    },
  };
</script>

Passando Data

Data é um array de objetos que irão compor os items da lista. Todas as propriedades do objeto serão repassadas para o componente renderItem com exceção das propriedades shortcut e onSelected, na qual o faz o uso para:

  • O shortcut que você definir será usado para criar atalhos do teclado no component.
  • O onSelected é usado como método para quando o item for selecionado.
  • Outras propriedades serão passadas normalmente para o componente declarado no renderItem.
const data = [
  {
    label: {
      value: 'Row 1',
    },
    shortcut: 1,
    onSelected: ({ sectionIndex, index, position, data }) => {
      /*
       * In this case, this anonymous function can call this script methods
       */
      console.log(index, sectionIndex, position, data); // 0 0 1 {label: {…}, shortcut: 1, onSelected: ƒ}
    },
  },
  {
    label: {
      value: 'Row 2',
    },
    shortcut: 2,
  },
  false && {
    // Conditional item
    label: {
      value: 'Row 3',
    },
    shortcut: 3,
  },
];

Método onSelect da row

Função anônima
  • A função anônima pode chamar qualquer método da página:

    // FlatList data
    const data = [
      {
        shortcut: 1
        label: {
          value: 'My Row',
        },
        onSelected: (item) => {
          const { someProp } = this.get();
    
          this.itemHandler(item, someProp);
        },
      }
    ];
    // ... Page methods
    methods: {
      itemHandler(item, someProp) {
        // ... do something with item and someProp
      },
    },
Executar um método que retorne uma função
  • Executando um método no onSelect, irá chamar a função desejada quando a lista for montada, possibilitando retornar uma função dinâmica.

    // FlatList data
    const data = [
      {
        shortcut: 1
        label: {
          value: 'Choose your destiny',
        },
        onSelected: this.getSelectedHandler(),
      }
    ];
    // ... Page methods
    methods: {
      getSelectedHandler() {
        if(myCondition) return (itemData) => {
          console.log('Condition function', itemData);
        };
    
        return (itemData) => {
          console.log('Default function', itemData);
        };
      },
    },
Referênciando um método da página
  • Você pode referenciar um método da página para ser usado no onSelected, mas o this de dentro do escopo da função referenciada, será a referência de seu objeto.

    // FlatList data
    const data = [
      {
        shortcut: 1
        label: {
          value: 'Some row',
        },
        onSelected: this.itemHandler,
      }
    ];
    // ... Page methods
    methods: {
      itemHandler() { // Without bind
        console.log(this) // { label: { value: 'Some row' }}, shortcut: 1, onSelected: function... }
      },
    },
  • Para referenciar métodos do mesmo componente/página, quando executada de dentro do escopo da função, use bind na referência do onSelect:

    // FlatList data
    const data = [
      {
        label: 'Item row',
        onSelected: this.itemHandler.bind(this),
      },
    ];
    // ... Page methods
    methods: {
      anotherMethod() {
        // ...
      },
      itemHandler() { // With bind
        this.anotherMethod();
      },
    },

Múltiplas seções

Útil para renderizar múltiplas listas com contextos diferentes.

const dataSection = [
  {
    title: 'Título da seção',
    data: [ ... ]
  }
]
Propriedades Descrição Tipo
title É usada para renderizar um título antes da lista. A omissão dela faz com que nenhum título seja renderizado. string
data Array de objetos que irão compor os items da seção. array

Exemplo de renderItem

<!-- Item.html -->

<!-- <FlatList /> envia `isActive` para seu component, podendo ser udado para realçar o elemento selecionado -->
<div class:active="isActive">
  <!-- Recebe `label` do `data`  -->
  {label}
</div>

<style>
  .active {
    background: #f00;
  }
</style>

Item de lista padrão

O FlatList exporta um componente padrão para ser usado na propriedade renderItem dele:

Exemplo:

<FlatList data="{dataList}" renderItem="{DefaultRow}" decorator="{GetDefaultDecorator}" />

<script>
  import { DefaultRow, FlatList, GetDefaultDecorator } from '@mamba/flatlist/index.js';
  export default {
    components: {
      FlatList,
    },
    helpers: {
      DefaultRow,
      GetDefaultDecorator,
    },
    data() {
      return {
        // Row items
        dataList: [],
      };
    },
  };
</script>

Decoradores

Como decoradores define um objeto padrão que irá aplicar para todos os items da listagem sem a necessidade de colocar manualmente em cada objeto de sua lista, o FlatList exporta um decorador padrão, o GetDefaultDecorator:

import { GetDefaultDecorator } from '@mamba/flatlist/index.js';

GetDefaultDecorator é um objeto pré-definido que ja entrega os padrões de layout para cada modelo de POS.

  • Se alguma lista tiver muitas variações do padrão, você pode definir seu prórpio decorator, ou se precisar alterar algum detalhe do padrão, use o decoratorOverrides.
  • decoratorOverrides pode ser usado para sobrescrever alguma propriedade padrão para todas as linhas, ou por modelo de POS específico, como por exemplo, tirar os prefixos:
<FlatList ... decorator={GetDefaultDecorator} decoratorOverrides={{ prefix: null }} />

Por modelo:

<FlatList ... decorator={GetDefaultDecorator} decoratorOverrides={{ S920: { prefix: null } }} />

Estrutura do DefaultRow

A estrutura do objeto que irá compor o array para o DefaultRow é diferente, tendo várias propriedades para customiza-lo:

type Alignment = 'start' | 'center' | 'end';

declare type Component = void;

interface ComponentView {
  // Fixture value
  value?: () => Component | any;

  /* If Value is component, set its props like:
   * props: {
   *   checked: true,
   * },
   */
  props?: object;

  /* If Value is component, set its events like:
   * on: {
   *   change: () => console.log('change'),
   * },
   */
  on?: object;
}

interface Fixture extends ComponentView {
  // Styles
  style?: object;
  wrapperStyle?: object;
  contentStyle?: object;
}

type SelectEvent = {
  data: DefaultRowProps;
  index: number;
  position: number;
  renderItemRefs: Component;
  telemetryEmitType: 'KEYBOARD' | 'TOUCH';
};

interface DefaultRowProps {
  // Action when selected with touch, keyboard action, or shortcut.
  onSelected?: (event: SelectEvent) => {};

  // The keyboard shortcut
  shortcut?: number | string;

  // Row top level style
  wrapperStyle?: object;

  // Row content container style (don't include and/start fixtures container)
  contentStyle?: object;

  // If row should highlighted or not
  highlightSelect?: boolean;

  // The highlight color
  highlightColor?: string;

  // If the row should have minimal spaces
  small?: boolean;

  // Whether the line should behave without internal spaces so that your children can fill it.
  fill?: boolean;

  // Vertical items align
  align?: Alignment;

  // Useful to put anything before the label
  startFixture?: Fixture;

  // If you dont want work with labels, you can inject your own main content in the row.
  customView?: ComponentView;

  // show or not chevron icon on all lines
  showChevron?: boolean;

  // Row labels
  label?: {
    value: string;
    description?: string;
    style?: object;

    // Anything immediate before label. Can be a function that will receive the row position
    prefix?: (position: number) => string | number;
    prefixStyle?: object;
  };

  rightLabel?: {
    value: string;
    description?: string;
    style?: object;

    // Anything immediate next to righLabel. Can be a function that will compute some value
    sufix?: () => string | number;
    sufixStyle?: object;
  };

  // Useful to put anything after the label or rightLabel block
  endFixture?: Fixture;
}

Acesse as ref do DefaultRow

Utilize para acessa o elemento e ter acesso as suas funcionalidades, como States e Funções .

Exemplo
interface DefaultRowProps = {
  // Action when selected with touch, keyboard action, or shortcut.
  onSelected: function(event) {
    const { endFixture } = event.renderItemRefs;
    endFixture.updateProps({
      checked: true,
    });
  },
}

Estilos

O DefaultRow possúi propriedades de estilo para customizar suas partes como style, wrapperStyle e contentStyle. O valor delas é um objeto de propriedades CSS em JavaScript:

{
  label: {
    value: 'Item',
  },
  style: {
    fontSize: '14px',
    borderBottomWidth: '2px',
  },
}

Readme

Keywords

none

Package Sidebar

Install

npm i @mamba/flatlist

Weekly Downloads

24

Version

12.1.0

License

Apache-2.0

Unpacked Size

124 kB

Total Files

21

Last publish

Collaborators

  • gabriel.arimatea
  • rrelias
  • guiguimartins
  • agjunior
  • janileodantas
  • mambaweb
  • jaikmestone