Skip to content

Commit cc67924

Browse files
wcandillonwcandillon
authored
Update documentation on Text (#2023)
1 parent 24ff62b commit cc67924

File tree

4 files changed

+145
-184
lines changed

4 files changed

+145
-184
lines changed

‎docs/docs/text/fonts.md

Lines changed: 0 additions & 174 deletions
This file was deleted.

‎docs/docs/text/paragraph.md

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ slug: /text/paragraph
88
React Native Skia offers an API to perform text layouts.
99
Behind the scene, this API is the Skia Paragraph API.
1010

11-
1211
## Hello World
1312

1413
In the example below, we create a simple paragraph based on custom fonts.
@@ -79,6 +78,34 @@ const textStyle = {
7978
};
8079
```
8180

81+
## Fonts
82+
83+
By default, the paragraph API will use the system fonts.
84+
You can also use custom fonts with this API was well.
85+
86+
The `useFonts` hooks allows you to load custom fonts to be used for your Skia drawing.
87+
The font files should be organized by family names.
88+
For example:
89+
90+
```tsx twoslash
91+
import {useFonts} from "@shopify/react-native-skia";
92+
93+
const fontMgr = useFonts({
94+
Roboto: [
95+
require("./Roboto-Medium.ttf"),
96+
require("./Roboto-Regular.ttf"),
97+
require("./Roboto-Bold.ttf"),
98+
],
99+
Helvetica: [require("./Helvetica.ttf")],
100+
});
101+
if (!fontMgr) {
102+
// Returns null until all fonts are loaded
103+
}
104+
// Now the fonts are available
105+
```
106+
107+
You can also list the available system fonts via `listFontFamilies()` function.
108+
82109
## Styling Paragraphs
83110

84111
These properties define the overall layout and behavior of a paragraph.
@@ -96,7 +123,7 @@ These properties define the overall layout and behavior of a paragraph.
96123
| `textHeightBehavior` | Controls the behavior of text ascent and descent in the first and last lines. |
97124
| `textStyle` | Default text style for the paragraph (can be overridden by individual text styles). |
98125

99-
### Text Style Properties
126+
## Text Style Properties
100127

101128
These properties are used to style specific segments of text within a paragraph.
102129

‎docs/docs/text/text.md

Lines changed: 116 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Please note that the y origin of the Text is the bottom of the text, not the top
1111
| Name | Type | Description |
1212
|:------------|:-----------|:----------------------------------------------------------------|
1313
| text | `string` | Text to draw |
14-
| font | `SkFont` | Font to use (optional, see [font management](/docs/text/fonts)) |
14+
| font | `SkFont` | Font to use (optional) |
1515
| x | `number` | Left position of the text (default is 0) |
1616
| y | `number` | Bottom position the text (default is 0, the ) |
1717

@@ -40,21 +40,130 @@ export const HelloWorld = () => {
4040

4141
<img src={require("/static/img/text/hello-world.png").default} width="256" height="256" />
4242

43-
### Emojis
43+
## Fonts
44+
45+
Once the fonts are loaded, we provide a `matchFont` function that given a font style will return a font object that you can use directly.
4446

4547
```tsx twoslash
46-
import {Canvas, Text, useFont, Fill} from "@shopify/react-native-skia";
48+
import {useFonts, Text, matchFont} from "@shopify/react-native-skia";
49+
50+
const Demo = () => {
51+
const fontMgr = useFonts({
52+
Roboto: [
53+
require("./Roboto-Medium.ttf"),
54+
require("./Roboto-Regular.ttf"),
55+
require("./Roboto-Bold.ttf"),
56+
]
57+
});
58+
if (!fontMgr) {
59+
return null;
60+
}
61+
const fontStyle = {
62+
fontFamily: "Roboto",
63+
fontWeight: "bold",
64+
fontSize: 16
65+
} as const;
66+
const font = matchFont(fontStyle, fontMgr);
67+
return (
68+
<Text text="Hello World" y={32} x={32} font={font} />
69+
);
70+
};
71+
```
72+
73+
## System Fonts
74+
75+
System fonts are available via `Skia.FontMgr.System()`.
76+
You can list system fonts via `listFontFamilies` function returns the list of available system font families.
77+
By default the function will list system fonts but you can pass an optional `fontMgr` object as parameter.
78+
79+
```jsx twoslash
80+
import {listFontFamilies} from "@shopify/react-native-skia";
81+
82+
console.log(listFontFamilies());
83+
```
84+
85+
Output example on Android:
86+
```
87+
["sans-serif", "arial", "helvetica", "tahoma", "verdana", ...]
88+
```
89+
90+
or on iOS:
91+
```
92+
["Academy Engraved LET", "Al Nile", "American Typewriter", "Apple Color Emoji", ...]
93+
```
94+
95+
By default matchFont, will match fonts from the system font manager:
96+
97+
```jsx twoslash
98+
import {Platform} from "react-native";
99+
import {Canvas, Text, matchFont, Fill, Skia} from "@shopify/react-native-skia";
100+
101+
const fontFamily = Platform.select({ ios: "Helvetica", default: "serif" });
102+
const fontStyle = {
103+
fontFamily,
104+
fontSize: 14,
105+
fontStyle: "italic",
106+
fontWeight: "bold",
107+
};
108+
const font = matchFont(fontStyle);
47109

48110
export const HelloWorld = () => {
49-
const fontSize = 32;
50-
const font = useFont(require("./NotoColorEmoji.ttf"), fontSize);
51111
return (
52112
<Canvas style={{ flex: 1 }}>
53113
<Fill color="white" />
54-
<Text text="🙋🌎" font={font} y={fontSize} x={0} />
114+
<Text
115+
x={0}
116+
y={fontStyle.fontSize}
117+
text="Hello World"
118+
font={font}
119+
/>
55120
</Canvas>
56121
);
57122
};
58123
```
59124

60-
<img src={require("/static/img/text/text-emoji.png").default} width="256" height="256" />
125+
The `fontStyle` object can have the following list of optional attributes:
126+
127+
- `fontFamily`: The name of the font family.
128+
- `fontSize`: The size of the font.
129+
- `fontStyle`: The slant of the font. Can be `normal`, `italic`, or `oblique`.
130+
- `fontWeight`: The weight of the font. Can be `normal`, `bold`, or any of `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`.
131+
132+
By default, `matchFont` uses the system font manager to match the font style. However, if you want to use your custom font manager, you can pass it as the second parameter to the `matchFont` function:
133+
134+
```jsx twoslash
135+
import {matchFont, useFonts} from "@shopify/react-native-skia";
136+
137+
const fontMgr = useFonts({
138+
Roboto: [
139+
require("../../Tests/assets/Roboto-Medium.ttf"),
140+
require("../../Tests/assets/Roboto-Bold.ttf"),
141+
]
142+
});
143+
144+
const font = matchFont(fontStyle, fontMgr);
145+
```
146+
147+
## Low-level API
148+
149+
The basic usage of the system font manager is as follows.
150+
These are the APIs used behind the scene by the `matchFont` function.
151+
152+
```tsx twoslash
153+
import {Platform} from "react-native";
154+
import {Skia, FontStyle} from "@shopify/react-native-skia";
155+
156+
const familyName = Platform.select({ ios: "Helvetica", default: "serif" });
157+
const fontSize = 32;
158+
// Get the system font manager
159+
const fontMgr = Skia.FontMgr.System();
160+
// The custom font manager is available via Skia.TypefaceFontProvider.Make()
161+
const customFontMgr = Skia.TypefaceFontProvider.Make();
162+
// typeface needs to be loaded via Skia.Data and instanciated via
163+
// Skia.Typeface.MakeFreeTypeFaceFromData()
164+
// customFontMgr.registerTypeface(customTypeFace, "Roboto");
165+
166+
// Matching a font
167+
const typeface = fontMgr.matchFamilyStyle(familyName, FontStyle.Bold);
168+
const font = Skia.Font(typeface, fontSize);
169+
```

‎docs/sidebars.js

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,6 @@ const sidebars = {
6868
type: "category",
6969
label: "Text",
7070
items: [
71-
"text/fonts",
7271
"text/paragraph",
7372
"text/text",
7473
"text/glyphs",

0 commit comments

Comments
 (0)