DOCSEARCHbyAlgolia
Submit Docs

FinalX Documentation

website·Indexed 30 days ago

https://finalx.vercel.app

A UI component library and toolkit featuring headless components, a centralized tool package for network requests and middleware, and a dedicated CLI scaffolding tool. Includes components such as Form, Step, NavBar, Dialog, Modal, and Wrapper, as well as utilities like apiServer and httpHelper from @finalx/common.

Tokens
7.3K
Snippets
50
Records
59
Agent score
73%

What's inside FinalX

  1. Extend and customize Docusaurus layouts with React

    Docusaurus is powered by React, allowing developers to extend or customize the website layout. You can create custom components or pages while maintaining the consistent global header and footer.

  2. Understand the Headless UI Component Architecture

    The component library follows a 'Headless' (无 UI) architecture, meaning components are not bound to a specific UI layer. Developers are responsible for implementing the actual UI and interface. The library provides the core logic, basic animation effects, and usage methods, which are designed to cover most common use cases.

  3. Initialize a new project using the FinalX CLI

    To start a new project with FinalX, install the @finalx/cli globally using your preferred package manager (npm, yarn, or pnpm) and then run the init command to generate the project structure.
    # Install the CLI globally
npm install @finalx/cli -g

# Generate project structure
finalx init <projectName>

  4. Get started with Docusaurus documentation

    Docusaurus is designed for quick installation and setup. To begin building your website, place your documentation files into the docs directory.

  5. Use BottomWrapper to handle bottom safe area insets

    The BottomWrapper component from @finalx/components is specifically designed to wrap bottom-aligned content (like footers or action bars) to automatically identify and handle the bottom safe area of the device.
    import { BottomWrapper } from "@finalx/components";

function Index({ children }) {
  return (
    <BottomWrapper
      style={{
        width: "100vw",
        height: "380rpx",
        backgroundColor: "#FFF9EE",
        borderRadius: "32rpx 32rpx 0 0",
        boxSizing: "border-box"
      }}
    >
      <View>...</View>
    </BottomWrapper>
  );
}

  6. Initialize global configuration for FinalX

    Global configuration should be defined in a global.config.ts file located at the project root and imported into the application's initialization file (e.g., main.ts, main.tsx, main.js, or main.jsx). Use the globalConfig function from @finalx/common to apply these settings.
    import { globalConfig } from "@finalx/common";

globalConfig({
  log: true,
  request: {
    baseUrl: "https://api.finalx.cc",
    wsUrl: "wss://api.finalx.cc",
    wsCheckUser: true,
    wsEventKey: {
      eventKey: "event",
      dataKey: "data"
    }
  },
  middleware: {
    userAuth: {
      filterKey: ["nickname", { key: "avatar", rule: (val: any, key: string) => !!val[key] }]
    }
  },
  component: {
    wrapperOffset: { top: '0rpx', bottom: '120rpx' },
    map: {
      key: 'AAAA-BBBBB-CCCCC-DDDDD-EEEEE-FFFFF', // Tencent Map Key
      center: { latitude: 20.2222, longitude: 120.111111 },
      distance: 1000,
      scale: { scale: 18, minScale: 16.2, maxScale: 19 },
      bounds: {
        northeast: { latitude: 30.1111111, longitude: 120.333333 },
        southwest: { latitude: 30.222222, longitude: 120.444444 },
      },
    },
  }
});

  7. Integrate FinalX components into an existing Taro project

    To add FinalX functionality to an existing Taro project, install the @finalx/components package as a dependency using npm, yarn, or pnpm.
    npm install @finalx/components -s

  8. Use Wrapper to handle top and bottom safe area insets

    The Wrapper component from @finalx/components is used to automatically calculate and apply safe area spacing for the top and bottom of a page. It provides props to toggle these spacings and customize the background and styles.
    import { Wrapper } from "@finalx/components";

function Index({ children }) {
  return (
    <Wrapper
      space={false} // Disable top safe area spacing
      bottomSpace={false} // Disable bottom safe area spacing
      bgColor="#f8ecd6"
      style={{
        position: 'relative',
        paddingBottom: '280rpx',
        minHeight: '100vh',
        boxSizing: 'border-box',
      }}
    >
      <View>...</View>
    </Wrapper>
  );
}

  9. Configure the Step popup window

    The pop property allows you to display a popup window associated with the step bar. It supports custom styling, positioning, and click events.
    interface Pop {
  title?: string; // Popup title
  style?: CSSProperties; // Popup styles
  offset?: { left?: number; right?: number }; // Popup offset
  children?: ReactElement; // Popup child elements
  onClick?: () => any; // Click event handler
}

  10. Configure Modal and BottomModal properties

    The following properties are available for both Modal and BottomModal components to control behavior and styling:

  11. Customize Step content styles

    Use the content property to apply custom CSS styles to the titles and descriptions of the step items.
    interface Content {
  titleStyle?: CSSProperties; // Styles for the title
  descStyle?: CSSProperties; // Styles for the description
}

  12. Manage requests with the useRequest hook

    The useRequest hook is a wrapper around taro-hooks used for managing request state (loading, data, error) and lifecycle. It takes two arguments: requestOptions (the request configuration) and an optional options object for behavior control.
    import { useRequest } from "@finalx/common";

const { data, loading, run } = useRequest(
  { url: APIS.USERS, method: "GET" },
  {} // options
);