add theme registry documentation, update base readme (#2)
This commit is contained in:
Jason Morse
GitHub
Родитель
74f321a5c3
Коммит
743a1ffb78
20
README.md
20
README.md
|
|
@ -1,7 +1,23 @@
|
|||
# UI Fabric React Native
|
||||
|
||||
# Contributing
|
||||
## Getting Started
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
To start developing in the repository you can:
|
||||
|
||||
1. `git clone https://github.com/microsoft/ui-fabric-react-native.git`
|
||||
1. `cd ui-fabric-react-native`
|
||||
1. `yarn`
|
||||
1. `yarn build` or `yarn start`
|
||||
|
||||
The demo package is currently where controls can be played with. If yarn start doesn't work go into the demo package and run yarn from there.
|
||||
|
||||
### Yarn + Lerna
|
||||
|
||||
This repo is set up as a monorepo using Lerna + Yarn workspaces. The yarn commands will trigger the lerna commands which will execute yarn commands in each package.
|
||||
|
||||
## Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,79 @@
|
|||
# Theme Registry
|
||||
|
||||
The theme registry is a helper for creating a directed graph of themes, with the ability to invalidate either subtrees within the hierarchy, or the entire set of themes. These themes can be queried by name, returning cached values if they are valid, or causing themes to be recreated on demand.
|
||||
|
||||
Having themes be connected in a graph is a requirement for theming in React Native where actual platform values may change dynamically. An example might be system font sizes or high contrast settings. In the case that these change the individual themes need to be reconfigured.
|
||||
|
||||
## Internal Structure
|
||||
|
||||
Beyond the dynamic portion of the graph, there are two special themes: the hidden platform theme and the default theme.
|
||||
|
||||
- Platform Theme - this encapsulates a set of defaults that come from the system. Information such as root typography settings or system colors can be set here. Depending on usage this could also contain default values for various elements of the theme. If a change happens here, all themes will be recreated.
|
||||
- Default Theme - this theme is the default theme for the entire UI tree. It can be obtained by using a name that is falsy, or by not specifying the theme name. It will inherit from the platform theme and be the implicit parent of all other themes.
|
||||
|
||||
## Usage
|
||||
|
||||
There is only a single exported generic function which returns an IThemeRegistry object.
|
||||
|
||||
export function createThemeRegistry<ITheme, IThemeDefinition>(
|
||||
platformDefaults: ITheme,
|
||||
resolver: ResolveTheme<ITheme, IThemeDefinition>
|
||||
): IThemeRegistry<ITheme, IThemeDefinition>
|
||||
|
||||
This is parameterized on two types (which can be the same):
|
||||
|
||||
- ITheme - a fully resolved theme, suitable for returning to callers
|
||||
- IThemeDefinition - either a partial theme, or other values which can be processed into a full theme.
|
||||
|
||||
| Parameter | Usage |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **platformDefaults** | A fully resolved theme containing the default values for the platform. This will not be processed but will be used as-is. |
|
||||
| **resolver** | A function which takes a theme definition, and parent theme, and will turn them into a new theme. When a theme is invalidated this will be re-run to create a new theme from the existing definition and a likely updated parent theme. |
|
||||
|
||||
The returned theme registry object should be held by the caller and used across the lifetime of the session. Generally this will not be exposed directly but will be wrapped in a more friendly API.
|
||||
|
||||
### Theme Registry APIs
|
||||
|
||||
The returned theme registry object has three APIs which provide the interface to wrap and expose to clients.
|
||||
|
||||
#### setTheme
|
||||
|
||||
registerTheme is the API which allows the caller to either create, or update an entry in the graph.
|
||||
|
||||
setTheme(
|
||||
definition: IThemeDefinition | ProcessTheme<ITheme, IThemeDefinition>,
|
||||
name?: string,
|
||||
parent?: string
|
||||
): void
|
||||
|
||||
| Param | Usage |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **definition** | this can either be a theme definition, or a function that accepts a parent theme and returns a new theme definition. If a theme definition is specified the standard resolution logic will be used. If a function is provided the function will be called to generate the a new theme definition which will then be run through the standard resolver. The results will be cached and invalidated the same as for standard resolution |
|
||||
| **name** | name of the theme. This will replace an existing entry. If empty or default, it will set/replace the default theme. |
|
||||
| **parent** | theme to use as a parent. If unspecified the default theme will be set as the parent. |
|
||||
|
||||
#### getTheme
|
||||
|
||||
This will return a theme by name, regenerating the theme if it has been invalidated in some way, otherwise returning the cached value.
|
||||
|
||||
getTheme(
|
||||
name?: string
|
||||
): ITheme
|
||||
|
||||
The usage of name is consistent with that of register theme, empty === the default theme.
|
||||
|
||||
#### updatePlatformDefaults
|
||||
|
||||
This allows the platform theme to be updated if the values have changed. Calling this will cause the full graph to be invalidated.
|
||||
|
||||
updatePlatformDefaults(platformDefaults: TPartialTheme): void
|
||||
|
||||
This will call the resolver to merge the updates with the existing platform theme to produce a new one.
|
||||
|
||||
#### addEventListener & removeEventListener
|
||||
|
||||
This allows callers to register for theme change events. The events will provide the name of the theme and they will be called when the theme is invalidated, not when it is rebuilt.
|
||||
|
||||
### ToDo Items:
|
||||
|
||||
- add the ability to have additional processors for themes that run at the time of theme resolution. This allows users to add additional data to the theme and add additional logic to run.
|
||||
Загрузка…
Ссылка в новой задаче